Merge branch 'gh-pages' into create-version-script

expressjs · Oct 6, 2024 · 3d59273 · 3d59273
2 parents c50693f + 24a104a
commit 3d59273
Show file tree

Hide file tree

Showing 67 changed files with 558 additions and 104 deletions.
diff --git a/.github/workflows/update-external-docs.yml b/.github/workflows/update-external-docs.yml
@@ -1,8 +1,8 @@
 name: Update External Docs
 on:
+    workflow_dispatch:
     schedule:
-    - cron:  '0 8 * * 1'
-
+        - cron:  '0 8 * * 1'
 
 permissions:
     pull-requests: write
@@ -11,24 +11,24 @@ permissions:
 jobs:
     update-docs:
         runs-on: ubuntu-latest
+        if: github.repository_owner == 'expressjs'
         steps:
-            - uses: actions/checkout@v3
+            - uses: actions/checkout@v4
             - name: Use Node.js 20
               uses: actions/setup-node@v4
               with:
                 node-version: 20
             - name: Run scripts
               run: bash ./get-contributing.sh && bash ./get-readmes.sh && node ./get-express-version.mjs
             - name: Create Pull Request
-              uses: peter-evans/create-pull-request@v5
+              uses: gr2m/create-or-update-pull-request-action@v1
+              env:
+                GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
               with: 
-                token: ${{ secrets.GITHUB_TOKEN }}
                 commit-message: update external docs
                 title: 'Update external docs'
                 body: >
                   This auto-generated PR updates external documentation to the expressjs.com repository.
                 labels: doc
+                team_reviewers: docs-wg
                 branch: external-docs-${{ github.sha }}
-                delete-branch: true
-
-
diff --git a/_data/express.yml b/_data/express.yml
@@ -1,2 +1,2 @@
-current_version: "4.19.2"
-next_version: "5.0.0-beta.1"
+current_version: "4.21.0"
+next_version: "5.0.0"
diff --git a/_includes/api/en/4x/app-listen.md b/_includes/api/en/4x/app-listen.md
@@ -48,8 +48,6 @@ app.listen = function () {
 }
 ```
 
-<div class="doc-box doc-info" markdown="1">
-NOTE: All the forms of Node's
+{% include admonitions/note.html content="All the forms of Node's
 [http.Server.listen()](https://nodejs.org/api/http.html#http_server_listen)
-method are in fact actually supported.
-</div>
+method are in fact actually supported." %}
diff --git a/_includes/api/en/4x/express.static.md b/_includes/api/en/4x/express.static.md
@@ -3,8 +3,10 @@
 This is a built-in middleware function in Express.
 It serves static files and is based on  [serve-static](/resources/middleware/serve-static.html).
 
-<div class="doc-box doc-info" markdown="1">NOTE: For best results, [use a reverse proxy](/{{page.lang}}/advanced/best-practice-performance.html#use-a-reverse-proxy) cache to improve performance of serving static assets.
-</div>
+{% capture alert_content %}
+For best results, [use a reverse proxy](/{{page.lang}}/advanced/best-practice-performance.html#use-a-reverse-proxy) cache to improve performance of serving static assets.
+{% endcapture %}
+{% include admonitions/note.html content=alert_content %}
 
 The `root` argument specifies the root directory from which to serve static assets.
 The function determines the file to serve by combining `req.url` with the provided `root` directory.
@@ -16,7 +18,7 @@ See also the [example below](#example.of.express.static).
 
 | Property      | Description                                                           |   Type      | Default         |
 |---------------|-----------------------------------------------------------------------|-------------|-----------------|
-| `dotfiles`    | Determines how dotfiles (files or directories that begin with a dot ".") are treated.  <br/><br/>See [dotfiles](#dotfiles) below. | String | "ignore"|
+| `dotfiles`    | Determines how dotfiles (files or directories that begin with a dot ".") are treated.  <br/><br/>See [dotfiles](#dotfiles) below. | String | `undefined` |
 | `etag`        | Enable or disable etag generation <br/><br/>NOTE: `express.static` always sends weak ETags. | Boolean | `true` |
 | `extensions`  | Sets file extension fallbacks: If a file is not found, search for files with the specified extensions and serve the first one found. Example: `['html', 'htm']`.| Mixed | `false` |
 | `fallthrough`  | Let client errors fall-through as unhandled requests, otherwise forward a client error. <br/><br/>See [fallthrough](#fallthrough) below.| Boolean | `true` |
@@ -30,15 +32,14 @@ See also the [example below](#example.of.express.static).
 For more information, see [Serving static files in Express](/starter/static-files.html).
 and [Using middleware - Built-in middleware](/{{page.lang}}/guide/using-middleware.html#middleware.built-in).
 
-<h5 id='dotfiles'> dotfiles</h5>
+<h5 id='dotfiles'>dotfiles</h5>
 
 Possible values for this option are:
 
 - "allow" - No special treatment for dotfiles.
 - "deny" - Deny a request for a dotfile, respond with `403`, then call `next()`.
 - "ignore" - Act as if the dotfile does not exist, respond with `404`, then call `next()`.
-
-**NOTE**: With the default value, it will not ignore files in a directory that begins with a dot.
+- `undefined` - Act as ignore, except that files in a directory that begins with a dot are **NOT** ignored.
 
 <h5 id='fallthrough'>fallthrough</h5>
 

diff --git a/_includes/api/en/4x/req-params.md b/_includes/api/en/4x/req-params.md
@@ -20,6 +20,4 @@ If you need to make changes to a key in `req.params`, use the [app.param](/{{ pa
 
 Any changes made to the `req.params` object in a middleware or route handler will be reset.
 
-<div class="doc-box doc-info" markdown="1">
-NOTE: Express automatically decodes the values in `req.params` (using `decodeURIComponent`).
-</div>
+{% include admonitions/note.html content="Express automatically decodes the values in `req.params` (using `decodeURIComponent`)." %}
diff --git a/_includes/api/en/4x/res-append.md b/_includes/api/en/4x/res-append.md
@@ -1,13 +1,10 @@
 <h3 id='res.append'>res.append(field [, value])</h3>
 
-<div class="doc-box doc-info" markdown="1">
-`res.append()` is supported by Express v4.11.0+
-</div>
-
+{% include admonitions/note.html content="`res.append()` is supported by Express v4.11.0+" %}
 Appends the specified `value` to the HTTP response header `field`.  If the header is not already set,
 it creates the header with the specified value.  The `value` parameter can be a string or an array.
 
-Note: calling `res.set()` after `res.append()` will reset the previously-set header value.
+{% include admonitions/note.html content="calling `res.set()` after `res.append()` will reset the previously-set header value." %}
 
 ```js
 res.append('Link', ['<http://localhost/>', '<http://localhost:3000/>'])

diff --git a/_includes/api/en/4x/router-route.md b/_includes/api/en/4x/router-route.md
@@ -45,6 +45,4 @@ router.route('/users/:user_id')
 This approach re-uses the single `/users/:user_id` path and adds handlers for
 various HTTP methods.
 
-<div class="doc-box doc-info" markdown="1">
-NOTE: When you use `router.route()`, middleware ordering is based on when the _route_ is created, not when method handlers are added to the route.  For this purpose, you can consider method handlers to belong to the route to which they were added.
-</div>
+{% include admonitions/note.html content="When you use `router.route()`, middleware ordering is based on when the _route_ is created, not when method handlers are added to the route.  For this purpose, you can consider method handlers to belong to the route to which they were added." %}
diff --git a/_includes/api/en/5x/app-listen.md b/_includes/api/en/5x/app-listen.md
@@ -48,8 +48,4 @@ app.listen = function () {
 }
 ```
 
-<div class="doc-box doc-info" markdown="1">
-NOTE: All the forms of Node's
-[http.Server.listen()](https://nodejs.org/api/http.html#http_server_listen)
-method are in fact actually supported.
-</div>
+{% include admonitions/note.html content="All the forms of Node's [http.Server.listen()](https://nodejs.org/api/http.html#http_server_listen) method are in fact actually supported." %}
diff --git a/_includes/api/en/5x/req-params.md b/_includes/api/en/5x/req-params.md
@@ -20,6 +20,4 @@ If you need to make changes to a key in `req.params`, use the [app.param](/{{ pa
 
 Any changes made to the `req.params` object in a middleware or route handler will be reset.
 
-<div class="doc-box doc-info" markdown="1">
-NOTE: Express automatically decodes the values in `req.params` (using `decodeURIComponent`).
-</div>
+{% include admonitions/note.html content="Express automatically decodes the values in `req.params` (using `decodeURIComponent`)." %}
diff --git a/_includes/api/en/5x/res-append.md b/_includes/api/en/5x/res-append.md
@@ -7,7 +7,7 @@
 Appends the specified `value` to the HTTP response header `field`.  If the header is not already set,
 it creates the header with the specified value. The `value` parameter can be a string or an array.
 
-Note: calling `res.set()` after `res.append()` will reset the previously-set header value.
+{% include admonitions/note.html content="calling `res.set()` after `res.append()` will reset the previously-set header value." %}
 
 ```js
 res.append('Link', ['<http://localhost/>', '<http://localhost:3000/>'])

diff --git a/_includes/api/en/5x/res-render.md b/_includes/api/en/5x/res-render.md
@@ -10,12 +10,10 @@ The `view` argument is a string that is the file path of the view file to render
 
 For more information, see [Using template engines with Express](/{{page.lang}}/guide/using-template-engines.html).
 
-**NOTE:** The `view` argument performs file system operations like reading a file from disk and evaluating Node.js modules, and as so for security reasons should not contain input from the end-user.
+{% include admonitions/note.html content="The `view` argument performs file system operations like reading a file from disk and evaluating Node.js modules, and as so for security reasons should not contain input from the end-user." %}
 
-<div class="doc-box doc-notice" markdown="1">
-The local variable `cache` enables view caching. Set it to `true`,
-to cache the view during development; view caching is enabled in production by default.
-</div>
+{% include admonitions/caution.html content="The local variable `cache` enables view caching. Set it to `true`,
+to cache the view during development; view caching is enabled in production by default." %}
 
 ```js
 // send the rendered view to the client

diff --git a/_includes/api/en/5x/router-route.md b/_includes/api/en/5x/router-route.md
@@ -45,6 +45,4 @@ router.route('/users/:user_id')
 This approach re-uses the single `/users/:user_id` path and adds handlers for
 various HTTP methods.
 
-<div class="doc-box doc-info" markdown="1">
-NOTE: When you use `router.route()`, middleware ordering is based on when the _route_ is created, not when method handlers are added to the route. For this purpose, you can consider method handlers to belong to the route to which they were added.
-</div>
+{% include admonitions/note.html content="When you use `router.route()`, middleware ordering is based on when the _route_ is created, not when method handlers are added to the route. For this purpose, you can consider method handlers to belong to the route to which they were added." %}
diff --git a/_includes/footer/footer-pt-br.html b/_includes/footer/footer-pt-br.html
@@ -8,11 +8,11 @@
                 <img src="https://raw.githubusercontent.com/openjs-foundation/artwork/main/openjs_foundation/openjs_foundation-logo-horizontal-color.svg" alt="OpenJS Foundation" width="125" height="39"/>
             </a>
             <div id="footer-policy">
-                <a href="https://terms-of-use.openjsf.org">Terms of Use</a>
-                <a href="https://privacy-policy.openjsf.org">Privacy Policy</a> 
-                <a id="coc" href="https://github.com/expressjs/express/blob/master/Code-Of-Conduct.md">Code of Conduct</a>
-                <a href="https://trademark-policy.openjsf.org">Trademark Policy</a>
-                <a id="security" href="https://github.com/expressjs/express/security/policy">Security Policy</a>
+                <a href="https://terms-of-use.openjsf.org">Termos de Uso</a>
+                <a href="https://privacy-policy.openjsf.org">Política de Privacidade</a> 
+                <a id="coc" href="https://github.com/expressjs/express/blob/master/Code-Of-Conduct.md">Código de Conduta</a>
+                <a href="https://trademark-policy.openjsf.org">Política de Marcas</a>
+                <a id="security" href="https://github.com/expressjs/express/security/policy">Política de Segurança</a>
                 <a id="license" href="http://creativecommons.org/licenses/by-sa/3.0/us/">Licença</a>
             </div>
         </div>

diff --git a/_includes/header/header-de.html b/_includes/header/header-de.html
@@ -77,6 +77,8 @@
               <ul id="application-menu" class="menu">
                   <li><a href="/{{ page.lang }}/4x/api.html"{% if page.menu == 'api' %} class="active"{% endif %}>API-Referenz</a>
                       <ul>
+                          <li><a href="/{{ page.lang }}/5x/api.html">5.x</a>
+                          </li>
                           <li><a href="/{{ page.lang }}/4x/api.html">4.x</a>
                           </li>
                           <li><a href="/{{ page.lang }}/3x/api.html">3.x (veraltet)</a>

diff --git a/_includes/header/header-es.html b/_includes/header/header-es.html
@@ -78,6 +78,8 @@
               <ul id="application-menu" class="menu">
                   <li><a href="/{{ page.lang }}/4x/api.html"{% if page.menu == 'api' %} class="active"{% endif %}>Referencia de API</a>
                       <ul>
+                          <li><a href="/{{ page.lang }}/5x/api.html">5.x</a>
+                          </li>
                           <li><a href="/{{ page.lang }}/4x/api.html">4.x</a>
                           </li>
                           <li><a href="/{{ page.lang }}/3x/api.html">3.x (en desuso)</a>

diff --git a/_includes/header/header-fr.html b/_includes/header/header-fr.html
@@ -78,6 +78,8 @@
               <ul id="application-menu" class="menu">
                   <li><a href="/{{ page.lang }}/4x/api.html"{% if page.menu == 'api' %} class="active"{% endif %}>Référence de l'API</a>
                       <ul>
+                          <li><a href="/{{ page.lang }}/5x/api.html">5.x</a>
+                          </li>
                           <li><a href="/{{ page.lang }}/4x/api.html">4.x</a>
                           </li>
                           <li><a href="/{{ page.lang }}/3x/api.html">3.x (obsolète)</a>

diff --git a/_includes/header/header-it.html b/_includes/header/header-it.html
@@ -75,6 +75,8 @@
               <ul id="application-menu" class="menu">
                   <li><a href="/{{ page.lang }}/4x/api.html"{% if page.menu == 'api' %} class="active"{% endif %}>Riferimento API</a>
                       <ul>
+                          <li><a href="/{{ page.lang }}/5x/api.html">5.x</a>
+                          </li>
                           <li><a href="/{{ page.lang }}/4x/api.html">4.x</a>
                           </li>
                           <li><a href="/{{ page.lang }}/3x/api.html">3.x (deprecato)</a>

diff --git a/_includes/header/header-ja.html b/_includes/header/header-ja.html
@@ -78,6 +78,8 @@
               <ul id="application-menu" class="menu">
                   <li><a href="/{{ page.lang }}/4x/api.html"{% if page.menu == 'api' %} class="active"{% endif %}>API リファレンス</a>
                       <ul>
+                          <li><a href="/{{ page.lang }}/5x/api.html">5.x</a>
+                          </li>
                           <li><a href="/{{ page.lang }}/4x/api.html">4.x</a>
                           </li>
                           <li><a href="/{{ page.lang }}/3x/api.html">3.x (非推奨)</a>

diff --git a/_includes/header/header-ko.html b/_includes/header/header-ko.html
@@ -78,6 +78,8 @@
               <ul id="application-menu" class="menu">
                   <li><a href="/{{ page.lang }}/4x/api.html"{% if page.menu == 'api' %} class="active"{% endif %}>API 참조</a>
                       <ul>
+                          <li><a href="/{{ page.lang }}/5x/api.html">5.x</a>
+                          </li>
                           <li><a href="/{{ page.lang }}/4x/api.html">4.x</a>
                           </li>
                           <li><a href="/{{ page.lang }}/3x/api.html">3.x(더 이상 사용되지 않음)</a>

diff --git a/_includes/header/header-pt-br.html b/_includes/header/header-pt-br.html
@@ -78,6 +78,8 @@
               <ul id="application-menu" class="menu">
                   <li><a href="/{{ page.lang }}/4x/api.html"{% if page.menu == 'api' %} class="active"{% endif %}>Referência da API</a>
                       <ul>
+                          <li><a href="/{{ page.lang }}/5x/api.html">5.x</a>
+                          </li>
                           <li><a href="/{{ page.lang }}/4x/api.html">4.x</a>
                           </li>
                           <li><a href="/{{ page.lang }}/3x/api.html">3.x (descontinuada)</a>

diff --git a/_includes/header/header-ru.html b/_includes/header/header-ru.html
@@ -78,6 +78,8 @@
               <ul id="application-menu" class="menu">
                   <li><a href="/{{ page.lang }}/4x/api.html"{% if page.menu == 'api' %} class="active"{% endif %}>API</a>
                       <ul>
+                          <li><a href="/{{ page.lang }}/5x/api.html">5.x</a>
+                          </li>
                           <li><a href="/{{ page.lang }}/4x/api.html">4.x</a>
                           </li>
                           <li><a href="/{{ page.lang }}/3x/api.html">3.x (устарел)</a>

diff --git a/_includes/header/header-sk.html b/_includes/header/header-sk.html
@@ -78,6 +78,8 @@
                 <ul id="application-menu" class="menu">
                     <li><a href="/{{ page.lang }}/4x/api.html" {% if page.menu == 'api' %} class="active" {% endif %}>API referenčná príručka</a>
                         <ul>
+                            <li><a href="/{{ page.lang }}/5x/api.html">5.x</a>
+                            </li>
                             <li><a href="/{{ page.lang }}/4x/api.html">4.x</a>
                             </li>
                             <li><a href="/{{ page.lang }}/3x/api.html">3.x (zastaralé)</a>

diff --git a/_includes/header/header-th.html b/_includes/header/header-th.html
@@ -78,6 +78,8 @@
               <ul id="application-menu" class="menu">
                   <li><a href="/{{ page.lang }}/4x/api.html"{% if page.menu == 'api' %} class="active"{% endif %}>การอ้างอิง API</a>
                       <ul>
+                          <li><a href="/{{ page.lang }}/5x/api.html">5.x</a>
+                          </li>
                           <li><a href="/{{ page.lang }}/4x/api.html">4.x</a>
                           </li>
                           <li><a href="/{{ page.lang }}/3x/api.html">3.x (เลิกใช้)</a>

diff --git a/_includes/header/header-tr.html b/_includes/header/header-tr.html
@@ -82,6 +82,8 @@
               <ul id="application-menu" class="menu">
                   <li><a href="/{{ page.lang }}/4x/api.html"{% if page.menu == 'api' %} class="active"{% endif %}>API Kaynak</a>
                       <ul>
+                          <li><a href="/{{ page.lang }}/5x/api.html">5.x</a>
+                          </li>
                           <li><a href="/{{ page.lang }}/4x/api.html">4.x</a>
                           </li>
                           <li><a href="/{{ page.lang }}/3x/api.html">3.x (Kullanımdan kaldırıldı)</a>

diff --git a/_includes/header/header-uk.html b/_includes/header/header-uk.html
@@ -77,6 +77,8 @@
               <ul id="application-menu" class="menu">
                   <li><a href="/{{ page.lang }}/4x/api.html"{% if page.menu == 'api' %} class="active"{% endif %}>Довідник API</a>
                       <ul>
+                          <li><a href="/{{ page.lang }}/5x/api.html">5.x</a>
+                          </li>
                           <li><a href="/{{ page.lang }}/4x/api.html">4.x</a>
                           </li>
                           <li><a href="/{{ page.lang }}/3x/api.html">3.x (застаріла)</a>

diff --git a/_includes/header/header-uz.html b/_includes/header/header-uz.html
@@ -78,6 +78,8 @@
               <ul id="application-menu" class="menu">
                   <li><a href="/{{ page.lang }}/4x/api.html"{% if page.menu == 'api' %} class="active"{% endif %}>API qo'llanma</a>
                       <ul>
+                          <li><a href="/{{ page.lang }}/5x/api.html">5.x</a>
+                          </li>
                           <li><a href="/{{ page.lang }}/4x/api.html">4.x</a>
                           </li>
                           <li><a href="/{{ page.lang }}/3x/api.html">3.x (eskirgan)</a>

diff --git a/_includes/header/header-zh-cn.html b/_includes/header/header-zh-cn.html
@@ -78,6 +78,8 @@
               <ul id="application-menu" class="menu">
                   <li><a href="/{{ page.lang }}/4x/api.html"{% if page.menu == 'api' %} class="active"{% endif %}>API 参考</a>
                       <ul>
+                          <li><a href="/{{ page.lang }}/5x/api.html">5.x</a>
+                          </li>
                           <li><a href="/{{ page.lang }}/4x/api.html">4.x</a>
                           </li>
                           <li><a href="/{{ page.lang }}/3x/api.html">3.x（不推荐）</a>

diff --git a/_includes/header/header-zh-tw.html b/_includes/header/header-zh-tw.html
@@ -78,6 +78,8 @@
               <ul id="application-menu" class="menu">
                   <li><a href="/{{ page.lang }}/4x/api.html"{% if page.menu == 'api' %} class="active"{% endif %}>API 參照</a>
                       <ul>
+                          <li><a href="/{{ page.lang }}/5x/api.html">5.x</a>
+                          </li>
                           <li><a href="/{{ page.lang }}/4x/api.html">4.x</a>
                           </li>
                           <li><a href="/{{ page.lang }}/3x/api.html">3.x（已淘汰）</a>