From effa46e9306db0ccfff7a1c9f5758bb5ae85a252 Mon Sep 17 00:00:00 2001
From: Ivan Boothe <git@rootwork.org>
Date: Sat, 6 Nov 2021 22:29:56 -0700
Subject: [PATCH 01/15] docs: update GitHub deployment instructions (#5888)

* SSH is required for GitHub deployment now

Matches what is listed in the default README.md of a new Docusaurus site

* Minimum node version required is 14.x

documentation.yml as written fails to run because the minimum node version for Docusaurus is 14.x

* Add link to default URL of locally-served site

* Correct deployment workflow

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
---
 website/docs/deployment.mdx | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx
index ff492bd640bb..e4fecee79270 100644
--- a/website/docs/deployment.mdx
+++ b/website/docs/deployment.mdx
@@ -33,6 +33,8 @@ Docusaurus includes a [`docusaurus serve`](cli.md#docusaurus-serve-sitedir) comm
 npm run serve
 ```
 
+By default this will load your site at [http://localhost:3000/](http://localhost:3000/).
+
 ## Trailing slash configuration {#trailing-slashes}
 
 Docusaurus has a [`trailingSlash` config](./api/docusaurus.config.js.md#trailing-slash), to allow customizing URLs/links and emitted filename patterns.
@@ -169,6 +171,14 @@ cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'
 </Tabs>
 ````
 
+:::caution
+
+Beginning in August 2021, GitHub requires every command-line sign-in to use the **personal access token** instead of the password. When GitHub prompts for your password, enter the PAT instead. See the [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) for more information.
+
+Alternatively, you can use SSH (`USE_SSH=true`) to login.
+
+:::
+
 ### Triggering deployment with GitHub Actions {#triggering-deployment-with-github-actions}
 
 [GitHub Actions](https://help.github.com/en/actions) allow you to automate, customize, and execute your software development workflows right in your repository.
@@ -205,7 +215,7 @@ jobs:
       - uses: actions/checkout@v1
       - uses: actions/setup-node@v1
         with:
-          node-version: '12.x'
+          node-version: '14.x'
       - name: Test Build
         run: |
           if [ -e yarn.lock ]; then
@@ -223,7 +233,7 @@ jobs:
       - uses: actions/checkout@v1
       - uses: actions/setup-node@v1
         with:
-          node-version: '12.x'
+          node-version: '14.x'
       - uses: webfactory/ssh-agent@v0.5.0
         with:
           ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }}

From caa9d923a61b541d8e0c8eaa94b050f62c43ab1f Mon Sep 17 00:00:00 2001
From: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
Date: Sun, 7 Nov 2021 21:29:08 +1300
Subject: [PATCH 02/15] docs: add example for Github Pages deployment; rewrite
 deployment section (#4409)

* docs: Minor copy changes + increment numbered list

* docs: Add alternative github pages deploy workflow

* docs: Add separate PR workflow for alternative gh-pages deploy example

* docs: Minor `gh-pages` deploy config improvements

Improve some comments and clarifies the file path beyond file name alone for each config file.

Additionally removes the workflow path triggers as in practice these being updated shouldn't be triggering a re-run of the workflow again (assuming deterministic build from same input results in same output).

If there is a need for such a manual trigger of the workflow is probably a better approach. Performing a build because workflow comments were modified only would be pointless for example.

* docs: Clarify `gh-pages` deploy config some more

* chore: PR Feedback - Remove inline documentation

Upstream doesn't see value including help comments for a copy/paste config under the basis that it adds friction to the viewer seeking guidance how to perform something they don't know.

* chore: PR Feedback - Rephrase instruction

MatanBobi requested a rephrase during review.

* Rewrite

* Fixes

* Fix!

* Format

* Fix indentation

* Improvements

* Minor fixes

Co-authored-by: Josh-Cena <sidachen2003@gmail.com>
---
 website/docs/deployment.mdx | 454 ++++++++++++++++++++++--------------
 1 file changed, 274 insertions(+), 180 deletions(-)

diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx
index e4fecee79270..bb4cb9cdef76 100644
--- a/website/docs/deployment.mdx
+++ b/website/docs/deployment.mdx
@@ -23,27 +23,30 @@ You can deploy your site to static site hosting services such as [Vercel](https:
 
 A Docusaurus site is statically rendered, and it can generally work without JavaScript!
 
-## Testing your Build Locally {#testing-build-locally}
+## Configuration {#configuration}
+
+The following parameters are required in `docusaurus.config.js` in order for Docusaurus to optimize routing and serve files from the correct location:
+
+| Name | Description |
+| --- | --- |
+| `url` | URL for your site. For a site deployed at `https://my-org.com/my-project/`, `url` is `https://my-org.com/`. |
+| `baseUrl` | Base URL for your project, with a trailing slash. For a site deployed at `https://my-org.com/my-project/`, `baseUrl` is `/my-project/`. |
 
-It is important to test your build locally before deploying to production.
+## Testing your Build Locally {#testing-build-locally}
 
-Docusaurus includes a [`docusaurus serve`](cli.md#docusaurus-serve-sitedir) command for that:
+It is important to test your build locally before deploying to production. Docusaurus provides a [`docusaurus serve`](cli.md#docusaurus-serve-sitedir) command for that:
 
 ```bash npm2yarn
 npm run serve
 ```
 
-By default this will load your site at [http://localhost:3000/](http://localhost:3000/).
+By default, this will load your site at [http://localhost:3000/](http://localhost:3000/).
 
 ## Trailing slash configuration {#trailing-slashes}
 
 Docusaurus has a [`trailingSlash` config](./api/docusaurus.config.js.md#trailing-slash), to allow customizing URLs/links and emitted filename patterns.
 
-The default value generally works fine.
-
-Unfortunately, each static hosting provider has a **different behavior**, and deploying the exact same site to various hosts can lead to distinct results.
-
-Depending on your host, it can be useful to change this config.
+The default value generally works fine. Unfortunately, each static hosting provider has a **different behavior**, and deploying the exact same site to various hosts can lead to distinct results. Depending on your host, it can be useful to change this config.
 
 :::tip
 
@@ -65,32 +68,48 @@ It is not the best option, compared to a static hosting provider / CDN.
 
 :::
 
+:::warning
+
+In the following sections, we will introduce a few common hosting providers and how they should be configured to deploy Docusaurus sites most efficiently. The documentation may not be up-to-date: recent changes in their API may not be reflected on our side. If you see outdated content, PRs are welcome.
+
+For the same concern of up-to-datedness, we have stopped accepting PRs adding new hosting options. You can, however, publish your writeup on a separate site (e.g. your blog, or the provider's official website), and ask us to include a link to your writeup.
+
+:::
+
 ## Deploying to GitHub Pages {#deploying-to-github-pages}
 
-Docusaurus provides an easy way to publish to [GitHub Pages](https://pages.github.com/). Which is hosting that comes for free with every GitHub repository.
+Docusaurus provides an easy way to publish to [GitHub Pages](https://pages.github.com/), which comes for free with every GitHub repository.
 
-### `docusaurus.config.js` settings {#docusaurusconfigjs-settings}
+### Overview {#github-pages-overview}
 
-First, modify your `docusaurus.config.js` and add the required params:
+Usually, there are two repositories (at least, two branches) involved in a publishing process: the branch containing the source files, and the branch containing the build output to be served with GitHub Pages. In the following tutorial they will be referred to as **"source"** and **"target"**, respectively.
 
-| Name | Description |
-| --- | --- |
-| `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, it is your GitHub username. In the case of Docusaurus, it is "_facebook_" which is the GitHub organization that owns Docusaurus. |
-| `projectName` | The name of the GitHub repository. For example, the repository name for Docusaurus is "docusaurus", so the project name is "docusaurus". |
-| `deploymentBranch` | The name of the branch to deploy the static files to. This defaults to "gh-pages" for non-organization GitHub Pages repos. If the repo name ends in ".github.io", you have to either specify this property or set the environment variable `DEPLOYMENT_BRANCH`. |
-| `url` | URL for your GitHub Page's user/organization page. This is commonly https://_username_.github.io. |
-| `baseUrl` | Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. |
+Each GitHub repository is associated with a GitHub Pages service. If the target repository is called `my-org/my-project` (where `my-org` is the organization name or username), the deployed site will appear at `https://my-org.github.io/my-project/`. Specially, if the target repository is called `my-org/my-org.github.io` (the _organization GitHub Pages repo_), the site will appear at `https://my-org.github.io/`.
 
 :::info
 
-In case you want to use your custom domain for GitHub Pages, create a `CNAME` file in the `static` directory. Anything within the `static` directory will be copied to the root of the `build` directory for deployment.
-
-When using a custom domain, you should be able to move back from `baseUrl: '/projectName/'` to `baseUrl: '/'`
+In case you want to use your custom domain for GitHub Pages, create a `CNAME` file in the `static` directory. Anything within the `static` directory will be copied to the root of the `build` directory for deployment. When using a custom domain, you should be able to move back from `baseUrl: '/projectName/'` to `baseUrl: '/'`.
 
 You may refer to GitHub Pages' documentation [User, Organization, and Project Pages](https://help.github.com/en/articles/user-organization-and-project-pages) for more details.
 
 :::
 
+GitHub Pages picks up deploy-ready files (the output from `docusaurus build`) from the default branch (`master` / `main`, usually) or the `gh-pages` branch, and either from the root or the `/docs` folder. You can configure that through `Settings > Pages` in your repository. This branch will be called the "target branch".
+
+We provide a `docusaurus deploy` command that helps you deploy your site from the source branch to the target branch in one command: clone, build, and commit.
+
+### `docusaurus.config.js` settings {#docusaurusconfigjs-settings}
+
+First, modify your `docusaurus.config.js` and add the following params:
+
+| Name | Description |
+| --- | --- |
+| `organizationName` | The GitHub user or organization that owns the target repository. |
+| `projectName` | The name of the target repository. |
+| `deploymentBranch` | The name of target branch. Defaults to `'gh-pages'` for non-organization GitHub Pages repos (`projectName` not ending in `.github.io`). Otherwise, this needs to be explicit as a config field or environment variable. |
+
+These fields also have their environment variable counterparts, which have a higher priority: `ORGANIZATION_NAME`, `PROJECT_NAME`, and `DEPLOYMENT_BRANCH`.
+
 :::caution
 
 GitHub Pages adds a trailing slash to Docusaurus URLs by default. It is recommended to set a `trailingSlash` config (`true` or `false`, not `undefined`).
@@ -123,16 +142,15 @@ Specify the Git user as an environment variable.
 
 | Name | Description |
 | --- | --- |
-| `GIT_USER` | The username for a GitHub account that has commit access to this repo. For your own repositories, this will usually be your GitHub username. The specified `GIT_USER` must have push access to the repository specified in the combination of `organizationName` and `projectName`. |
+| `GIT_USER` | The username for a GitHub account that **has push access to the target repo**. For your own repositories, this will usually be your GitHub username. |
 
 Optional parameters, also set as environment variables:
 
 | Name | Description |
 | --- | --- |
 | `USE_SSH` | Set to `true` to use SSH instead of the default HTTPS for the connection to the GitHub repo. |
-| `DEPLOYMENT_BRANCH` | The branch that the website will be deployed to, defaults to `gh-pages`. For GitHub Pages Organization repos (`config.projectName` ending in `github.io`), you need to either set this env variable or specify the `deploymentBranch` param in `docusaurus.config.js`. |
-| `CURRENT_BRANCH` | The branch that contains the latest docs changes that will be deployed. Usually, the branch will be `main`, but it could be any branch (default or otherwise) except for `gh-pages`. If nothing is set for this variable, then the current branch will be used. |
-| `GIT_PASS` | Password (or token) of the `git` user (specified by `GIT_USER`). For example, to facilitate non-interactive deployment (e.g. continuous deployment) |
+| `CURRENT_BRANCH` | The source branch. Usually, the branch will be `main` or `master`, but it could be any branch except for `gh-pages`. If nothing is set for this variable, then the current branch from which `docusaurus deploy` is invoked will be used. |
+| `GIT_PASS` | Personal access token of the `git` user (specified by `GIT_USER`), to facilitate non-interactive deployment (e.g. continuous deployment) |
 
 GitHub enterprise installations should work in the same manner as github.com; you only need to set the organization's GitHub Enterprise host as an environment variable:
 
@@ -183,95 +201,195 @@ Alternatively, you can use SSH (`USE_SSH=true`) to login.
 
 [GitHub Actions](https://help.github.com/en/actions) allow you to automate, customize, and execute your software development workflows right in your repository.
 
-This workflow assumes your documentation resided in `documentation` branch of your repository and your [publishing source](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) is configured for `gh-pages` branch.
+The workflow examples below assume your website source resides in the `main` branch of your repository (the _source branch_ is `main`), under a folder called `website/`, and your [publishing source](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) is configured for the `gh-pages` branch (the _target branch_ is `gh-pages`).
+
+Our goal is that:
+
+1. When a new pull request is made to `main` and updates `website/`, there's an action that ensures the site builds successfully, without actually deploying. This job will be called `test-deploy`.
+2. When a pull request is merged to the `main` branch or someone pushes to the `main` branch directly and `website/` is updated, it will be built and deployed to the `gh-pages` branch. After that, the new built output will be served on the GitHub Pages site. This job will be called `deploy`.
+
+Here are two approaches to deploying your docs with GitHub Actions. Based on the location of your target branch (`gh-pages`), choose the relevant tab below:
+
+- Source repo and target repo are the **same** repository.
+- The target repo is a **remote** repository, different from the source.
+
+````mdx-code-block
+<Tabs>
+<TabItem value="same" label="Same">
+
+While you can have both jobs defined in the same workflow file, the `deploy` job will always be listed as skipped in the PR check suite status. That's added noise providing no value to the review process, and as you cannot easily share common snippets, it is better to manage them as separate workflows instead.
+
+We will use a popular third-party deployment action: [peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus).
+
+<details>
+
+<summary>GitHub action files</summary>
+
+Add these two workflow files:
+
+:::warning
+
+These files assume you are using yarn. If you use npm, change `cache: yarn`, `yarn install --frozen-lockfile`, `yarn build` to `cache: npm`, `npm ci`, `npm run build` accordingly.
+
+:::
+
+```yml title=".github/workflows/deploy.yml"
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths: [website/**]
+
+jobs:
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: 14.x
+          cache: yarn
+      - name: Build website
+        working-directory: website
+        run: |
+          yarn install --frozen-lockfile
+          yarn build
+
+      # Popular action to deploy to GitHub Pages:
+      # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # Build output to publish to the `gh-pages` branch:
+          publish_dir: ./website/build
+          # Assign commit authorship to the official GH-Actions bot for deploys to `gh-pages` branch:
+          # https://github.com/actions/checkout/issues/13#issuecomment-724415212
+          # The GH actions bot is used by default if you didn't specify the two fields.
+          # You can swap them out with your own user credentials.
+          user_name: github-actions[bot]
+          user_email: 41898282+github-actions[bot]@users.noreply.github.com
+```
+
+```yml title=".github/workflows/test-deploy.yml"
+name: Test deployment
+
+on:
+  pull_request:
+    branches: [main]
+    paths: [website/**]
+
+jobs:
+  test-deploy:
+    name: Test deployment
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: 14.x
+          cache: yarn
+      - name: Test build
+        working-directory: website
+        run: |
+          yarn install --frozen-lockfile
+          yarn build
+```
+
+</details>
+
+</TabItem>
+<TabItem value="remote" label="Remote">
+
+A cross-repo publish is more difficult to set up, because you need to push to another repo with permission checks. We will be using SSH to do the authentication.
 
 1. Generate a new [SSH key](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
-1. By default, your public key should have been created in `~/.ssh/id_rsa.pub` or use the name you've provided in the previous step to add your key to [GitHub deploy keys](https://developer.github.com/v3/guides/managing-deploy-keys/).
-1. Copy key to clipboard with `xclip -sel clip < ~/.ssh/id_rsa.pub` and paste it as a [deploy key](https://developer.github.com/v3/guides/managing-deploy-keys/#deploy-keys) in your repository. Copy file content if the command line doesn't work for you. Check the box for `Allow write access` before saving your deployment key.
-1. You'll need your private key as a [GitHub secret](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets) to allow Docusaurus to run the deployment for you.
-1. Copy your private key with `xclip -sel clip < ~/.ssh/id_rsa` and paste a GitHub secret with name `GH_PAGES_DEPLOY`. Copy file content if the command line doesn't work for you. Save your secret.
-1. Create your [documentation workflow file](https://help.github.com/en/actions/configuring-and-managing-workflows/configuring-a-workflow#creating-a-workflow-file) in `.github/workflows/`. In this example it's `documentation.yml`.
+2. By default, your public key should have been created in `~/.ssh/id_rsa.pub`; otherwise, use the name you've provided in the previous step to add your key to [GitHub deploy keys](https://developer.github.com/v3/guides/managing-deploy-keys/).
+3. Copy the key to clipboard with `xclip -sel clip < ~/.ssh/id_rsa.pub` and paste it as a [deploy key](https://developer.github.com/v3/guides/managing-deploy-keys/#deploy-keys) in your repository. Copy the file content if the command line doesn't work for you. Check the box for `Allow write access` before saving your deployment key.
+4. You'll need your private key as a [GitHub secret](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets) to allow Docusaurus to run the deployment for you.
+5. Copy your private key with `xclip -sel clip < ~/.ssh/id_rsa` and paste a GitHub secret with the name `GH_PAGES_DEPLOY`. Copy the file content if the command line doesn't work for you. Save your secret.
+6. Create your [documentation workflow file](https://help.github.com/en/actions/configuring-and-managing-workflows/configuring-a-workflow#creating-a-workflow-file) in `.github/workflows/`. In this example it's `deploy.yml`.
+
+<details>
+
+<summary>GitHub action file</summary>
 
 :::warning
 
 Please make sure that you replace `actions@github.com` with your GitHub email and `gh-actions` with your name.
 
+This file assumes you are using yarn. If you use npm, change `cache: yarn`, `yarn install --frozen-lockfile`, `yarn build` to `cache: npm`, `npm ci`, `npm run build` accordingly.
+
 :::
 
-```yaml title="documentation.yml"
-name: documentation
+```yml title=".github/workflows/deploy.yml"
+name: Deploy to GitHub Pages
 
 on:
   pull_request:
-    branches: [documentation]
+    branches: [main]
   push:
-    branches: [documentation]
+    branches: [main]
 
 jobs:
-  checks:
+  test-deploy:
     if: github.event_name != 'push'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v1
-      - uses: actions/setup-node@v1
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
         with:
-          node-version: '14.x'
-      - name: Test Build
+          node-version: 14.x
+          cache: yarn
+      - name: Test deployment
         run: |
-          if [ -e yarn.lock ]; then
-            yarn install --frozen-lockfile
-          elif [ -e package-lock.json ]; then
-            npm ci
-          else
-            npm i
-          fi
-          npm run build
-  gh-release:
+          yarn install --frozen-lockfile
+          yarn build
+  deploy:
     if: github.event_name != 'pull_request'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v1
-      - uses: actions/setup-node@v1
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
         with:
-          node-version: '14.x'
+          node-version: 14.x
+          cache: yarn
       - uses: webfactory/ssh-agent@v0.5.0
         with:
           ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }}
-      - name: Release to GitHub Pages
+      - name: Deploy to GitHub Pages
         env:
           USE_SSH: true
           GIT_USER: git
         run: |
           git config --global user.email "actions@github.com"
           git config --global user.name "gh-actions"
-          if [ -e yarn.lock ]; then
-            yarn install --frozen-lockfile
-          elif [ -e package-lock.json ]; then
-            npm ci
-          else
-            npm i
-          fi
-          npm run deploy
+          yarn install --frozen-lockfile
+          yarn deploy
 ```
 
-1. Now when a new pull request arrives towards your repository in branch `documentation` it will automatically ensure that Docusaurus build is successful.
-1. When pull request is merged to `documentation` branch or someone pushes to `documentation` branch directly it will be built and deployed to `gh-pages` branch.
-1. After this step, your updated documentation will be available on the GitHub pages.
+</details>
+
+</TabItem>
+</Tabs>
+````
 
 ### Triggering deployment with Travis CI {#triggering-deployment-with-travis-ci}
 
 Continuous integration (CI) services are typically used to perform routine tasks whenever new commits are checked in to source control. These tasks can be any combination of running unit tests and integration tests, automating builds, publishing packages to NPM, and deploying changes to your website. All you need to do to automate the deployment of your website is to invoke the `yarn deploy` script whenever your website is updated. The following section covers how to do just that using [Travis CI](https://travis-ci.com/), a popular continuous integration service provider.
 
 1. Go to https://github.com/settings/tokens and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/). When creating the token, grant it the `repo` scope so that it has the permissions it needs.
-1. Using your GitHub account, [add the Travis CI app](https://github.com/marketplace/travis-ci) to the repository you want to activate.
-1. Open your Travis CI dashboard. The URL looks like `https://travis-ci.com/USERNAME/REPO`, and navigate to the `More options` > `Setting` > `Environment Variables` section of your repository.
-1. Create a new environment variable named `GH_TOKEN` with your newly generated token as its value, then `GH_EMAIL` (your email address) and `GH_NAME` (your GitHub username).
-1. Create a `.travis.yml` on the root of your repository with the following:
+2. Using your GitHub account, [add the Travis CI app](https://github.com/marketplace/travis-ci) to the repository you want to activate.
+3. Open your Travis CI dashboard. The URL looks like `https://travis-ci.com/USERNAME/REPO`, and navigate to the `More options > Setting > Environment Variables` section of your repository.
+4. Create a new environment variable named `GH_TOKEN` with your newly generated token as its value, then `GH_EMAIL` (your email address) and `GH_NAME` (your GitHub username).
+5. Create a `.travis.yml` on the root of your repository with the following:
 
-```yaml title=".travis.yml"
+```yml title=".travis.yml"
 language: node_js
 node_js:
-  - '12.13.0'
+  - '14.15.0'
 branches:
   only:
     - main
@@ -281,7 +399,8 @@ script:
   - git config --global user.name "${GH_NAME}"
   - git config --global user.email "${GH_EMAIL}"
   - echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
-  - yarn && GIT_USER="${GH_NAME}" yarn deploy
+  - yarn install
+  - GIT_USER="${GH_NAME}" yarn deploy
 ```
 
 Now, whenever a new commit lands in `main`, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the `yarn deploy` script.
@@ -293,34 +412,35 @@ Now, whenever a new commit lands in `main`, Travis CI will run your suite of tes
 Follow these steps to create a pipeline that automatically deploys a new version of your website whenever you push changes to the selected branch of your project:
 
 1. Go to https://github.com/settings/tokens and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/). When creating the token, grant it the `repo` scope so that it has the permissions it needs.
-1. Sign in to your Buddy account and create a new project.
-1. Choose GitHub as your git hosting provider and select the repository with the code of your website.
-1. Using the left navigation panel, switch to the `Pipelines` view.
-1. Create a new pipeline. Define its name, set the trigger mode to `On push`, and select the branch that triggers the pipeline execution.
-1. Add a `Node.js` action.
-1. Add these command in the action's terminal:
-   ```bash
-   GIT_USER=<GH_PERSONAL_ACCESS_TOKEN>
-   git config --global user.email "<YOUR_GH_EMAIL>"
-   git config --global user.name "<YOUR_GH_USERNAME>"
-   yarn deploy
-   ```
+2. Sign in to your Buddy account and create a new project.
+3. Choose GitHub as your git hosting provider and select the repository with the code of your website.
+4. Using the left navigation panel, switch to the `Pipelines` view.
+5. Create a new pipeline. Define its name, set the trigger mode to `On push`, and select the branch that triggers the pipeline execution.
+6. Add a `Node.js` action.
+7. Add these commands in the action's terminal:
+
+```bash
+GIT_USER=<GH_PERSONAL_ACCESS_TOKEN>
+git config --global user.email "<YOUR_GH_EMAIL>"
+git config --global user.name "<YOUR_GH_USERNAME>"
+yarn deploy
+```
 
 After creating this simple pipeline, each new commit pushed to the branch you selected deploys your website to GitHub Pages using `yarn deploy`. Read [this guide](https://buddy.works/guides/react-docusaurus) to learn more about setting up a CI/CD pipeline for Docusaurus.
 
 ### Using Azure Pipelines {#using-azure-pipelines}
 
-1.  Sign Up at [Azure Pipelines](https://azure.microsoft.com/en-us/services/devops/pipelines/) if you haven't already.
-1.  Create an organization and within the organization create a project and connect your repository from GitHub.
-1.  Go to https://github.com/settings/tokens and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) with the `repo` scope.
-1.  In the project page (which looks like `https://dev.azure.com/ORG_NAME/REPO_NAME/_build` create a new pipeline with the following text. Also, click on edit and add a new environment variable named `GH_TOKEN` with your newly generated token as its value, then `GH_EMAIL` (your email address) and `GH_NAME` (your GitHub username). Make sure to mark them as secret. Alternatively, you can also add a file named `azure-pipelines.yml` at your repository root.
+1. Sign Up at [Azure Pipelines](https://azure.microsoft.com/en-us/services/devops/pipelines/) if you haven't already.
+2. Create an organization and within the organization create a project and connect your repository from GitHub.
+3. Go to https://github.com/settings/tokens and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) with the `repo` scope.
+4. In the project page (which looks like `https://dev.azure.com/ORG_NAME/REPO_NAME/_build` create a new pipeline with the following text. Also, click on edit and add a new environment variable named `GH_TOKEN` with your newly generated token as its value, then `GH_EMAIL` (your email address) and `GH_NAME` (your GitHub username). Make sure to mark them as secret. Alternatively, you can also add a file named `azure-pipelines.yml` at your repository root.
 
-```yaml title="azure-pipelines.yml"
+```yml title="azure-pipelines.yml"
 trigger:
   - main
 
 pool:
-  vmImage: 'ubuntu-latest'
+  vmImage: ubuntu-latest
 
 steps:
   - checkout: self
@@ -328,33 +448,33 @@ steps:
 
   - task: NodeTool@0
     inputs:
-      versionSpec: '10.x'
-    displayName: 'Install Node.js'
+      versionSpec: 14.x
+    displayName: Install Node.js
 
   - script: |
       git config --global user.name "${GH_NAME}"
       git config --global user.email "${GH_EMAIL}"
       git checkout -b main
       echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
-      yarn && GIT_USER="${GH_NAME}" yarn deploy
+      yarn install
+      GIT_USER="${GH_NAME}" yarn deploy
     env:
       GH_NAME: $(GH_NAME)
       GH_EMAIL: $(GH_EMAIL)
       GH_TOKEN: $(GH_TOKEN)
-    displayName: 'yarn install and build'
+    displayName: Install and build
 ```
 
 ### Using Drone {#using-drone}
 
-1.  Create a new ssh key that will be the [deploy key](https://docs.github.com/en/free-pro-team@latest/developers/overview/managing-deploy-keys#deploy-keys) for your project.
-1.  Name your private and public keys to be specific and so that it does not overwrite your other [ssh keys](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
-1.  Go to `https://github.com/USERNAME/REPO/settings/keys` and add a new deploy key by pasting in our public key you just generated.
-1.  Open your Drone.io dashboard and login. The URL looks like `https://cloud.drone.io/USERNAME/REPO`.
-1.  Click on the repository, click on activate repository, and add a secret called `git_deploy_private_key` with your private key value that you just generated.
-1.  Create a `.drone.yml` on the root of your repository with below text.
+1. Create a new ssh key that will be the [deploy key](https://docs.github.com/en/free-pro-team@latest/developers/overview/managing-deploy-keys#deploy-keys) for your project.
+2. Name your private and public keys to be specific and so that it does not overwrite your other [ssh keys](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
+3. Go to `https://github.com/USERNAME/REPO/settings/keys` and add a new deploy key by pasting in our public key you just generated.
+4. Open your Drone.io dashboard and login. The URL looks like `https://cloud.drone.io/USERNAME/REPO`.
+5. Click on the repository, click on activate repository, and add a secret called `git_deploy_private_key` with your private key value that you just generated.
+6. Create a `.drone.yml` on the root of your repository with below text.
 
-```yaml
-# .drone.yml
+```yml title=".drone.yml"
 kind: pipeline
 type: docker
 trigger:
@@ -368,13 +488,13 @@ trigger:
     - echo "$GITHUB_PRIVATE_KEY" > "$HOME/.ssh/id_rsa"
     - chmod 0600 $HOME/.ssh/id_rsa
     - cd website
-    - npm i
-    - npm run deploy
+    - yarn install
+    - yarn deploy
   environment:
     USE_SSH: true
     GIT_USER: $DRONE_COMMIT_AUTHOR
     GITHUB_PRIVATE_KEY:
-      from_secret: "git_deploy_private_key"
+      from_secret: git_deploy_private_key
 ```
 
 Now, whenever you push a new tag to github, this trigger will start the drone ci job to publish your website.
@@ -454,79 +574,63 @@ After your project has been imported, all subsequent pushes to branches will gen
 [Qovery](https://www.qovery.com) is a fully-managed cloud platform that runs on your AWS, Digital Ocean and Scaleway account where you can host static sites, backend APIs, databases, cron jobs, and all your other apps in one place.
 
 1. Create a Qovery account. Visit the [Qovery dashboard](https://console.qovery.com) to create an account if you don't already have one.
-
-2. Create a project
-
-- Click on **Create project** and give a name to your project.
-- Click on **Next**.
-
-3. Create a new environment
-
-- Click on **Create environment** and give a name (e.g. staging, production).
-
-4. Add an application
-
-- Click on **Create an application**, give a name and select your GitHub or GitLab repository where your Docusaurus app is located.
-- Define the main branch name and the root application path.
-- Click on **Create**.
-
-After the application is created:
-
-- Navigate to your application **Settings**
-- Select **Port**
-- Add port used by your Docusaurus application
-
-5. Deploy All you have to do now is to navigate to your application and click on **Deploy**
+2. Create a project.
+   - Click on **Create project** and give a name to your project.
+   - Click on **Next**.
+3. Create a new environment.
+   - Click on **Create environment** and give a name (e.g. staging, production).
+4. Add an application.
+   - Click on **Create an application**, give a name and select your GitHub or GitLab repository where your Docusaurus app is located.
+   - Define the main branch name and the root application path.
+   - Click on **Create**. After the application is created:
+   - Navigate to your application **Settings**
+   - Select **Port**
+   - Add port used by your Docusaurus application
+5. Deploy All you have to do now is to navigate to your application and click on **Deploy**.
 
 ![Deploy the app](https://hub.qovery.com/img/heroku/heroku-1.png)
 
-That's it. Watch the status and wait till the app is deployed.
-
-To open the application in your browser, click on **Action** and **Open** in your application overview
+That's it. Watch the status and wait till the app is deployed. To open the application in your browser, click on **Action** and **Open** in your application overview.
 
 ## Deploying to Hostman {#deploying-to-hostman}
 
 [Hostman](https://hostman.com/) allows you to host static websites for free. Hostman automates everything, you just need to connect your repository and follow easy steps:
 
-1. Create a service
-
-To deploy a Docusaurus static website, click Create in the top-left corner of your [Dashboard](https://dashboard.hostman.com/) and choose Front-end app or static website.
-
-2. Select the project to deploy
+1. Create a service.
 
-If you are logged in to Hostman with your GitHub, GitLab or Bitbucket account, at this point you will see the repository with your projects, including the private ones.
+   To deploy a Docusaurus static website, click **Create** in the top-left corner of your [Dashboard](https://dashboard.hostman.com/) and choose **Front-end app or static website**.
 
-Choose the project you want to deploy. It must contain the directory with the project’s files (usually it is website or my-website).
+2. Select the project to deploy.
 
-To access a different repository, click Connect another repository.
+   If you are logged in to Hostman with your GitHub, GitLab or Bitbucket account, at this point you will see the repository with your projects, including the private ones.
 
-If you didn’t use your Git account credentials to log in, you’ll be able to access the necessary account now, and then select the project.
+   Choose the project you want to deploy. It must contain the directory with the project’s files (usually it is website or my-website).
 
-3. Configure the build settings Next, the Website customization window will appear.
+   To access a different repository, click **Connect another repository**.
 
-Choose the Static website option from the list of frameworks.
+   If you didn’t use your Git account credentials to log in, you’ll be able to access the necessary account now, and then select the project.
 
-The Directory with app points at the directory that will contain the project's files after the build. You can leave it empty if during Step 2 you selected the repository with the contents of the website (or my_website) directory.
+3. Configure the build settings.
 
-The standard build command for Docusaurus will be:
+   Next, the **Website customization** window will appear. Choose the **Static website** option from the list of frameworks.
 
-```bash
-yarn run build
-```
+   The **Directory with app** points at the directory that will contain the project's files after the build. You can leave it empty if during Step 2 you selected the repository with the contents of the website (or `my_website`) directory.
 
-You can modify the build command if needed. You can enter multiple commands separated by &&.
+   The standard build command for Docusaurus will be:
 
-4. Deploy Click Deploy to start the build process.
+   ```bash npm2yarn
+   npm run build
+   ```
 
-Once it starts, you will enter the deployment log. If there are any issues with the code, you will get warning or error messages in the log, specifying the cause of the problem.
+   You can modify the build command if needed. You can enter multiple commands separated by `&&`.
 
-Usually the log contains all the debugging data you'll need, but we are also here to help you solve the issues, so do not hesitate to contact us via chat.
+4. Deploy.
 
-When the deployment is complete, you will receive an e-mail notification and also see a log entry.
+   Click **Deploy** to start the build process.
 
-All done!
+   Once it starts, you will enter the deployment log. If there are any issues with the code, you will get warning or error messages in the log, specifying the cause of the problem. Usually, the log contains all the debugging data you'll need.
 
-Your project is up and ready.
+   When the deployment is complete, you will receive an email notification and also see a log entry. All done! Your project is up and ready.
 
 ## Deploying to Surge {#deploying-to-surge}
 
@@ -535,22 +639,17 @@ Surge is a [static web hosting platform](https://surge.sh/help/getting-started-w
 Deploy your app in a matter of seconds using surge with the following steps:
 
 1. First, install Surge using npm by running the following command:
-
-```bash
-npm install --g surge
-```
-
+   ```bash npm2yarn
+   npm install -g surge
+   ```
 2. To build the static files of your site for production in the root directory of your project, run:
-
-```bash
-npm run build
-```
-
+   ```bash npm2yarn
+   npm run build
+   ```
 3. Then, run this command inside the root directory of your project:
-
-```bash
-surge build/
-```
+   ```bash
+   surge build/
+   ```
 
 First-time users of Surge would be prompted to create an account from the command line(happens only once).
 
@@ -579,19 +678,14 @@ You can deploy any other changes in the future with the command `surge`.
 ## Deploying to QuantCDN {#deploying-to-quantcdn}
 
 1. Install [Quant CLI](https://docs.quantcdn.io/docs/cli/get-started)
-
 2. Create a QuantCDN account by [signing up](https://dashboard.quantcdn.io/register)
-
 3. Initialize your project with `quant init` and fill in your credentials:
-
-```bash
-quant init
-```
-
-4. Deploy your site
-
-```bash
-quant deploy
-```
+   ```bash
+   quant init
+   ```
+4. Deploy your site.
+   ```bash
+   quant deploy
+   ```
 
 See [docs](https://docs.quantcdn.io/docs/cli/continuous-integration) and [blog](https://www.quantcdn.io/blog) for more examples and use cases for deploying to QuantCDN.

From 0fc7adfba9c4d47f5a727c728d997904fadbae2e Mon Sep 17 00:00:00 2001
From: Joshua Chen <sidachen2003@gmail.com>
Date: Sun, 7 Nov 2021 23:16:04 +0800
Subject: [PATCH 03/15] docs: document global variables in MDX scope (#5900)

* Adding a note for how to access frontMatter within pages

* Move documentation

Co-authored-by: cd rubin <github@earthling.za.net>
---
 .../markdown-features-react.mdx               | 47 +++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/website/docs/guides/markdown-features/markdown-features-react.mdx b/website/docs/guides/markdown-features/markdown-features-react.mdx
index 08aed08e3a77..8be1ae86fc77 100644
--- a/website/docs/guides/markdown-features/markdown-features-react.mdx
+++ b/website/docs/guides/markdown-features/markdown-features-react.mdx
@@ -5,6 +5,8 @@ description: Using the power of React in Docusaurus Markdown documents, thanks t
 slug: /markdown-features/react
 ---
 
+# MDX and React
+
 ```mdx-code-block
 import BrowserWindow from '@site/src/components/BrowserWindow';
 ```
@@ -169,3 +171,48 @@ This way, you can reuse contents among multiple pages and avoid duplicating mate
 The table-of-contents does not currently contain the imported Markdown headings. This is a technical limitation that we are trying to solve ([issue](https://github.com/facebook/docusaurus/issues/3915)).
 
 :::
+
+## Available exports
+
+Within the MDX page, the following variables are available as globals:
+
+- `frontMatter`: the front matter as a record of string keys and values;
+- `toc`: the table of contents, as a tree of headings. See also [Inline TOC](./markdown-features-inline-toc.mdx) for a more concrete use-case.
+- `contentTitle`: the Markdown title, which is the first `h1` heading in the Markdown text. It's `undefined` if there isn't one (e.g. title specified in the front matter).
+
+```jsx
+import TOCInline from '@theme/TOCInline';
+import CodeBlock from '@theme/CodeBlock';
+
+The table of contents for this page, serialized:
+
+<CodeBlock className="language-json">{JSON.stringify(toc, null, 2)}</CodeBlock>
+
+The front matter of this page:
+
+<ul>
+  {Object.entries(frontMatter).map(([key, value]) => <li key={key}><b>{key}</b>: {value}</li>)}
+</ul>
+
+<p>The title of this page is: <b>{contentTitle}</b></p>
+```
+
+```mdx-code-block
+import TOCInline from '@theme/TOCInline';
+
+<BrowserWindow>
+
+The table of contents for this page, serialized:
+
+<CodeBlock className="language-json">{JSON.stringify(toc, null, 2)}</CodeBlock>
+
+The front matter of this page:
+
+<ul>
+  {Object.entries(frontMatter).map(([key, value]) => <li key={key}><b>{key}</b>: {value}</li>)}
+</ul>
+
+<p>The title of this page is: <b>{contentTitle}</b></p>
+
+</BrowserWindow>
+```

From c8904f1615f72cf9ffbec7061b8716f0e4bac555 Mon Sep 17 00:00:00 2001
From: Joshua Chen <sidachen2003@gmail.com>
Date: Mon, 8 Nov 2021 13:17:52 +0800
Subject: [PATCH 04/15] fix(website): fix i18n routes for Canny board (#5902)

---
 website/src/featureRequests/FeatureRequestsPage.tsx  | 6 +++---
 website/src/featureRequests/FeatureRequestsPlugin.js | 7 ++++++-
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/website/src/featureRequests/FeatureRequestsPage.tsx b/website/src/featureRequests/FeatureRequestsPage.tsx
index 66ccd79d60b6..581aa46b4ef3 100644
--- a/website/src/featureRequests/FeatureRequestsPage.tsx
+++ b/website/src/featureRequests/FeatureRequestsPage.tsx
@@ -14,16 +14,16 @@ import styles from './styles.module.css';
 
 const BOARD_TOKEN = '054e0e53-d951-b14c-7e74-9eb8f9ed2f91';
 
-function FeatureRequests(): JSX.Element {
+function FeatureRequests({basePath}: {basePath: string}): JSX.Element {
   useEffect(() => {
     cannyScript();
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const {Canny} = window as any;
     Canny('render', {
       boardToken: BOARD_TOKEN,
-      basePath: '/feature-requests',
+      basePath,
     });
-  }, []);
+  }, [basePath]);
 
   return (
     <Layout title="Feedback" description="Docusaurus 2 Feature Requests page">
diff --git a/website/src/featureRequests/FeatureRequestsPlugin.js b/website/src/featureRequests/FeatureRequestsPlugin.js
index 1902657b7671..2aad9eb2dc96 100644
--- a/website/src/featureRequests/FeatureRequestsPlugin.js
+++ b/website/src/featureRequests/FeatureRequestsPlugin.js
@@ -15,10 +15,15 @@ function FeatureRequestsPlugin(context) {
   return {
     name: 'feature-requests-plugin',
     async contentLoaded({actions}) {
+      const basePath = normalizeUrl([context.baseUrl, '/feature-requests']);
+      await actions.createData('paths.json', JSON.stringify(basePath));
       actions.addRoute({
-        path: normalizeUrl([context.baseUrl, '/feature-requests']),
+        path: basePath,
         exact: false,
         component: '@site/src/featureRequests/FeatureRequestsPage',
+        modules: {
+          basePath: './feature-requests-plugin/default/paths.json',
+        },
       });
     },
   };

From 13d07eff138b9838cb0fbb7125290825424bdd7a Mon Sep 17 00:00:00 2001
From: Joshua Chen <sidachen2003@gmail.com>
Date: Mon, 8 Nov 2021 14:15:28 +0800
Subject: [PATCH 05/15] docs: refer to deployed branch as deployment rather
 than target (#5903)

---
 website/docs/deployment.mdx | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx
index bb4cb9cdef76..962d6052b334 100644
--- a/website/docs/deployment.mdx
+++ b/website/docs/deployment.mdx
@@ -82,9 +82,9 @@ Docusaurus provides an easy way to publish to [GitHub Pages](https://pages.githu
 
 ### Overview {#github-pages-overview}
 
-Usually, there are two repositories (at least, two branches) involved in a publishing process: the branch containing the source files, and the branch containing the build output to be served with GitHub Pages. In the following tutorial they will be referred to as **"source"** and **"target"**, respectively.
+Usually, there are two repositories (at least, two branches) involved in a publishing process: the branch containing the source files, and the branch containing the build output to be served with GitHub Pages. In the following tutorial they will be referred to as **"source"** and **"deployment"**, respectively.
 
-Each GitHub repository is associated with a GitHub Pages service. If the target repository is called `my-org/my-project` (where `my-org` is the organization name or username), the deployed site will appear at `https://my-org.github.io/my-project/`. Specially, if the target repository is called `my-org/my-org.github.io` (the _organization GitHub Pages repo_), the site will appear at `https://my-org.github.io/`.
+Each GitHub repository is associated with a GitHub Pages service. If the deployment repository is called `my-org/my-project` (where `my-org` is the organization name or username), the deployed site will appear at `https://my-org.github.io/my-project/`. Specially, if the deployment repository is called `my-org/my-org.github.io` (the _organization GitHub Pages repo_), the site will appear at `https://my-org.github.io/`.
 
 :::info
 
@@ -94,9 +94,9 @@ You may refer to GitHub Pages' documentation [User, Organization, and Project Pa
 
 :::
 
-GitHub Pages picks up deploy-ready files (the output from `docusaurus build`) from the default branch (`master` / `main`, usually) or the `gh-pages` branch, and either from the root or the `/docs` folder. You can configure that through `Settings > Pages` in your repository. This branch will be called the "target branch".
+GitHub Pages picks up deploy-ready files (the output from `docusaurus build`) from the default branch (`master` / `main`, usually) or the `gh-pages` branch, and either from the root or the `/docs` folder. You can configure that through `Settings > Pages` in your repository. This branch will be called the "deployment branch".
 
-We provide a `docusaurus deploy` command that helps you deploy your site from the source branch to the target branch in one command: clone, build, and commit.
+We provide a `docusaurus deploy` command that helps you deploy your site from the source branch to the deployment branch in one command: clone, build, and commit.
 
 ### `docusaurus.config.js` settings {#docusaurusconfigjs-settings}
 
@@ -104,9 +104,9 @@ First, modify your `docusaurus.config.js` and add the following params:
 
 | Name | Description |
 | --- | --- |
-| `organizationName` | The GitHub user or organization that owns the target repository. |
-| `projectName` | The name of the target repository. |
-| `deploymentBranch` | The name of target branch. Defaults to `'gh-pages'` for non-organization GitHub Pages repos (`projectName` not ending in `.github.io`). Otherwise, this needs to be explicit as a config field or environment variable. |
+| `organizationName` | The GitHub user or organization that owns the deployment repository. |
+| `projectName` | The name of the deployment repository. |
+| `deploymentBranch` | The name of deployment branch. Defaults to `'gh-pages'` for non-organization GitHub Pages repos (`projectName` not ending in `.github.io`). Otherwise, this needs to be explicit as a config field or environment variable. |
 
 These fields also have their environment variable counterparts, which have a higher priority: `ORGANIZATION_NAME`, `PROJECT_NAME`, and `DEPLOYMENT_BRANCH`.
 
@@ -142,7 +142,7 @@ Specify the Git user as an environment variable.
 
 | Name | Description |
 | --- | --- |
-| `GIT_USER` | The username for a GitHub account that **has push access to the target repo**. For your own repositories, this will usually be your GitHub username. |
+| `GIT_USER` | The username for a GitHub account that **has push access to the deployment repo**. For your own repositories, this will usually be your GitHub username. |
 
 Optional parameters, also set as environment variables:
 
@@ -201,17 +201,17 @@ Alternatively, you can use SSH (`USE_SSH=true`) to login.
 
 [GitHub Actions](https://help.github.com/en/actions) allow you to automate, customize, and execute your software development workflows right in your repository.
 
-The workflow examples below assume your website source resides in the `main` branch of your repository (the _source branch_ is `main`), under a folder called `website/`, and your [publishing source](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) is configured for the `gh-pages` branch (the _target branch_ is `gh-pages`).
+The workflow examples below assume your website source resides in the `main` branch of your repository (the _source branch_ is `main`), under a folder called `website/`, and your [publishing source](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) is configured for the `gh-pages` branch (the _deployment branch_ is `gh-pages`).
 
 Our goal is that:
 
 1. When a new pull request is made to `main` and updates `website/`, there's an action that ensures the site builds successfully, without actually deploying. This job will be called `test-deploy`.
 2. When a pull request is merged to the `main` branch or someone pushes to the `main` branch directly and `website/` is updated, it will be built and deployed to the `gh-pages` branch. After that, the new built output will be served on the GitHub Pages site. This job will be called `deploy`.
 
-Here are two approaches to deploying your docs with GitHub Actions. Based on the location of your target branch (`gh-pages`), choose the relevant tab below:
+Here are two approaches to deploying your docs with GitHub Actions. Based on the location of your deployment branch (`gh-pages`), choose the relevant tab below:
 
-- Source repo and target repo are the **same** repository.
-- The target repo is a **remote** repository, different from the source.
+- Source repo and deployment repo are the **same** repository.
+- The deployment repo is a **remote** repository, different from the source.
 
 ````mdx-code-block
 <Tabs>

From 334b4397e7f4367262a743907ad6dbbd9f77767e Mon Sep 17 00:00:00 2001
From: Joshua Chen <sidachen2003@gmail.com>
Date: Mon, 8 Nov 2021 15:33:06 +0800
Subject: [PATCH 06/15] refactor(content-docs): use shelljs instead of execa
 (#5904)

---
 .../package.json                              |  1 -
 .../src/__tests__/lastUpdate.test.ts          |  2 +-
 .../src/lastUpdate.ts                         | 19 ++++++-------------
 3 files changed, 7 insertions(+), 15 deletions(-)

diff --git a/packages/docusaurus-plugin-content-docs/package.json b/packages/docusaurus-plugin-content-docs/package.json
index 61849c6a1ca0..ee791cbb155f 100644
--- a/packages/docusaurus-plugin-content-docs/package.json
+++ b/packages/docusaurus-plugin-content-docs/package.json
@@ -34,7 +34,6 @@
     "chalk": "^4.1.2",
     "combine-promises": "^1.1.0",
     "escape-string-regexp": "^4.0.0",
-    "execa": "^5.0.0",
     "fs-extra": "^10.0.0",
     "globby": "^11.0.2",
     "import-fresh": "^3.2.2",
diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/lastUpdate.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/lastUpdate.test.ts
index 323ac109ec15..5c8f07e0e512 100644
--- a/packages/docusaurus-plugin-content-docs/src/__tests__/lastUpdate.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/__tests__/lastUpdate.test.ts
@@ -40,7 +40,7 @@ describe('lastUpdate', () => {
     expect(await getFileLastUpdate(nonExistingFilePath)).toBeNull();
     expect(consoleMock).toHaveBeenCalledTimes(1);
     expect(consoleMock.mock.calls[0][0].message).toContain(
-      `Command failed with exit code 128: git log -1 --format=%ct, %an ${nonExistingFileName}`,
+      `fatal: ambiguous argument '${nonExistingFilePath}': unknown revision or path not in the working tree.`,
     );
     expect(await getFileLastUpdate(null)).toBeNull();
     expect(await getFileLastUpdate(undefined)).toBeNull();
diff --git a/packages/docusaurus-plugin-content-docs/src/lastUpdate.ts b/packages/docusaurus-plugin-content-docs/src/lastUpdate.ts
index a7d07e9f9406..a5de58da6aed 100644
--- a/packages/docusaurus-plugin-content-docs/src/lastUpdate.ts
+++ b/packages/docusaurus-plugin-content-docs/src/lastUpdate.ts
@@ -6,12 +6,10 @@
  */
 
 import shell from 'shelljs';
-import execa from 'execa';
-import path from 'path';
 
 type FileLastUpdateData = {timestamp?: number; author?: string};
 
-const GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX = /^(\d+), (.+)$/;
+const GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX = /^(\d+),(.+)$/;
 
 let showedGitRequirementError = false;
 
@@ -44,16 +42,11 @@ export async function getFileLastUpdate(
       return null;
     }
 
-    const fileBasename = path.basename(filePath);
-    const fileDirname = path.dirname(filePath);
-    const {stdout} = await execa(
-      'git',
-      ['log', '-1', '--format=%ct, %an', fileBasename],
-      {
-        cwd: fileDirname,
-      },
-    );
-    return getTimestampAndAuthor(stdout);
+    const result = shell.exec(`git log -1 --format=%ct,%an ${filePath}`);
+    if (result.stderr) {
+      throw new Error(result.stderr);
+    }
+    return getTimestampAndAuthor(result.stdout.trim());
   } catch (error) {
     console.error(error);
   }

From a835c9bc48627f196b6a0e3622e95bc52ef17d4b Mon Sep 17 00:00:00 2001
From: Joshua Chen <sidachen2003@gmail.com>
Date: Mon, 8 Nov 2021 17:09:58 +0800
Subject: [PATCH 07/15] misc(plugin-docs): fix Windows test snapshot for git
 history retrieval (#5905)

* misc(plugin-docs): fix test snapshot

* Fix again
---
 .../src/__tests__/lastUpdate.test.ts                        | 2 +-
 packages/docusaurus-plugin-content-docs/src/lastUpdate.ts   | 6 ++++--
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/lastUpdate.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/lastUpdate.test.ts
index 5c8f07e0e512..36324d16c025 100644
--- a/packages/docusaurus-plugin-content-docs/src/__tests__/lastUpdate.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/__tests__/lastUpdate.test.ts
@@ -40,7 +40,7 @@ describe('lastUpdate', () => {
     expect(await getFileLastUpdate(nonExistingFilePath)).toBeNull();
     expect(consoleMock).toHaveBeenCalledTimes(1);
     expect(consoleMock.mock.calls[0][0].message).toContain(
-      `fatal: ambiguous argument '${nonExistingFilePath}': unknown revision or path not in the working tree.`,
+      ' with exit code 128',
     );
     expect(await getFileLastUpdate(null)).toBeNull();
     expect(await getFileLastUpdate(undefined)).toBeNull();
diff --git a/packages/docusaurus-plugin-content-docs/src/lastUpdate.ts b/packages/docusaurus-plugin-content-docs/src/lastUpdate.ts
index a5de58da6aed..3154d8843e12 100644
--- a/packages/docusaurus-plugin-content-docs/src/lastUpdate.ts
+++ b/packages/docusaurus-plugin-content-docs/src/lastUpdate.ts
@@ -43,8 +43,10 @@ export async function getFileLastUpdate(
     }
 
     const result = shell.exec(`git log -1 --format=%ct,%an ${filePath}`);
-    if (result.stderr) {
-      throw new Error(result.stderr);
+    if (result.code !== 0) {
+      throw new Error(
+        `Retrieval of git history failed at ${filePath} with exit code ${result.code}: ${result.stderr}`,
+      );
     }
     return getTimestampAndAuthor(result.stdout.trim());
   } catch (error) {

From f12c390a174613b63ad9b43bedb629981d02cc8a Mon Sep 17 00:00:00 2001
From: Joshua Chen <sidachen2003@gmail.com>
Date: Mon, 8 Nov 2021 21:03:21 +0800
Subject: [PATCH 08/15] fix(content-docs): do not echo git history to console
 (#5906)

---
 packages/docusaurus-plugin-content-docs/src/lastUpdate.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/docusaurus-plugin-content-docs/src/lastUpdate.ts b/packages/docusaurus-plugin-content-docs/src/lastUpdate.ts
index 3154d8843e12..c36d99efb10a 100644
--- a/packages/docusaurus-plugin-content-docs/src/lastUpdate.ts
+++ b/packages/docusaurus-plugin-content-docs/src/lastUpdate.ts
@@ -42,7 +42,9 @@ export async function getFileLastUpdate(
       return null;
     }
 
-    const result = shell.exec(`git log -1 --format=%ct,%an ${filePath}`);
+    const result = shell.exec(`git log -1 --format=%ct,%an ${filePath}`, {
+      silent: true,
+    });
     if (result.code !== 0) {
       throw new Error(
         `Retrieval of git history failed at ${filePath} with exit code ${result.code}: ${result.stderr}`,

From 8fba542d26c53c3cb7745baeec1cc584dfd50bd5 Mon Sep 17 00:00:00 2001
From: Joshua Chen <sidachen2003@gmail.com>
Date: Mon, 8 Nov 2021 22:04:39 +0800
Subject: [PATCH 09/15] chore(workflow): merge jobs into one workflow & give
 each job a name (#5907)

---
 .github/workflows/build-blog-only.yml         |  1 +
 .../{build-size-report.yml => build-perf.yml} | 29 +++++++++++++++--
 .github/workflows/build-time-perf.yml         | 31 -------------------
 .github/workflows/canary-release.yml          |  1 +
 .github/workflows/lighthouse-report.yml       |  3 +-
 .github/workflows/lint.yml                    |  1 +
 .github/workflows/tests-e2e.yml               |  2 ++
 .github/workflows/tests-windows.yml           | 30 ------------------
 .github/workflows/tests.yml                   | 26 ++++++++++++++++
 9 files changed, 60 insertions(+), 64 deletions(-)
 rename .github/workflows/{build-size-report.yml => build-perf.yml} (60%)
 delete mode 100644 .github/workflows/build-time-perf.yml
 delete mode 100644 .github/workflows/tests-windows.yml

diff --git a/.github/workflows/build-blog-only.yml b/.github/workflows/build-blog-only.yml
index da0ed5d2e783..766f097dbac8 100644
--- a/.github/workflows/build-blog-only.yml
+++ b/.github/workflows/build-blog-only.yml
@@ -9,6 +9,7 @@ on:
 
 jobs:
   build:
+    name: Build Blog-only
     timeout-minutes: 30
     runs-on: ubuntu-latest
     steps:
diff --git a/.github/workflows/build-size-report.yml b/.github/workflows/build-perf.yml
similarity index 60%
rename from .github/workflows/build-size-report.yml
rename to .github/workflows/build-perf.yml
index 50bbf710c9f6..e1edd0f4ba1e 100644
--- a/.github/workflows/build-size-report.yml
+++ b/.github/workflows/build-perf.yml
@@ -1,4 +1,4 @@
-name: Build Size Report
+name: Build Performance
 
 on:
   # Note! you can't safely use "pull_request_target" here
@@ -9,9 +9,12 @@ on:
   pull_request:
     branches:
       - main
+    paths-ignore:
+      - website/docs/**
 
 jobs:
-  build:
+  build-size:
+    name: Build Size Report
     timeout-minutes: 30
     runs-on: ubuntu-latest
     steps:
@@ -27,3 +30,25 @@ jobs:
           strip-hash: '\.([^;]\w{7})\.'
           minimum-change-threshold: 30
           compression: none
+  build-time:
+    name: Build Time Perf
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          cache: yarn
+      - name: Installation
+        run: yarn
+
+      # Ensure build with a cold cache does not increase too much
+      - name: Build (cold cache)
+        run: yarn workspace website build --locale en
+        timeout-minutes: 8
+
+      # Ensure build with a warm cache does not increase too much
+      - name: Build (warm cache)
+        run: yarn workspace website build --locale en
+        timeout-minutes: 2
+    # TODO post a Github comment with build with perf warnings?
diff --git a/.github/workflows/build-time-perf.yml b/.github/workflows/build-time-perf.yml
deleted file mode 100644
index b5e0e08ef9b6..000000000000
--- a/.github/workflows/build-time-perf.yml
+++ /dev/null
@@ -1,31 +0,0 @@
-name: Build Time Perf
-
-on:
-  pull_request:
-    branches:
-      - main
-    paths-ignore:
-      - website/docs/**
-
-jobs:
-  build:
-    timeout-minutes: 30
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
-        with:
-          cache: yarn
-      - name: Installation
-        run: yarn
-
-      # Ensure build with a cold cache does not increase too much
-      - name: Build (cold cache)
-        run: yarn workspace website build --locale en
-        timeout-minutes: 8
-
-      # Ensure build with a warm cache does not increase too much
-      - name: Build (warm cache)
-        run: yarn workspace website build --locale en
-        timeout-minutes: 2
-    # TODO post a Github comment with build with perf warnings?
diff --git a/.github/workflows/canary-release.yml b/.github/workflows/canary-release.yml
index 6572faadb85f..9fabecd0234d 100644
--- a/.github/workflows/canary-release.yml
+++ b/.github/workflows/canary-release.yml
@@ -9,6 +9,7 @@ on:
 
 jobs:
   publish-canary:
+    name: Publish Canary
     runs-on: ubuntu-latest
     strategy:
       matrix:
diff --git a/.github/workflows/lighthouse-report.yml b/.github/workflows/lighthouse-report.yml
index 71d2c041eced..e1ee61bc047f 100644
--- a/.github/workflows/lighthouse-report.yml
+++ b/.github/workflows/lighthouse-report.yml
@@ -6,7 +6,8 @@ on:
       - main
 
 jobs:
-  build:
+  lighthouse-report:
+    name: Lighthouse Report
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 8da4c7ebd436..72fb77da75ea 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -7,6 +7,7 @@ on:
 
 jobs:
   lint:
+    name: Lint
     timeout-minutes: 30
     runs-on: ubuntu-latest
     steps:
diff --git a/.github/workflows/tests-e2e.yml b/.github/workflows/tests-e2e.yml
index 27d967a6f4a3..0666a2e64a87 100644
--- a/.github/workflows/tests-e2e.yml
+++ b/.github/workflows/tests-e2e.yml
@@ -10,6 +10,7 @@ on:
 
 jobs:
   yarn-v1:
+    name: E2E Test with Yarn v1
     timeout-minutes: 30
     runs-on: ubuntu-latest
     strategy:
@@ -42,6 +43,7 @@ jobs:
           CI: true
 
   yarn-berry:
+    name: E2E Test with Yarn Berry
     timeout-minutes: 30
     runs-on: ubuntu-latest
     strategy:
diff --git a/.github/workflows/tests-windows.yml b/.github/workflows/tests-windows.yml
deleted file mode 100644
index 871f67a9e661..000000000000
--- a/.github/workflows/tests-windows.yml
+++ /dev/null
@@ -1,30 +0,0 @@
-name: Windows Tests
-
-on:
-  pull_request:
-    branches:
-      - main
-
-jobs:
-  build:
-    timeout-minutes: 30
-    runs-on: windows-latest
-    strategy:
-      matrix:
-        node: ['14', '16', '17']
-    steps:
-      - name: Support longpaths
-        run: git config --system core.longpaths true
-      - uses: actions/checkout@v2
-      - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@v2
-        with:
-          node-version: ${{ matrix.node }}
-      - name: Installation
-        run: yarn || yarn || yarn # 3 attempts to avoid timeout errors...
-      - name: Docusaurus Jest Tests
-        run: yarn test
-      - name: Docusaurus Build
-        run: yarn build:website --locale en
-        env:
-          CI: true
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 35705996cff2..e0c50ebd5d10 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -4,9 +4,12 @@ on:
   pull_request:
     branches:
       - main
+    paths-ignore:
+      - website/**
 
 jobs:
   test:
+    name: Tests
     timeout-minutes: 30
     runs-on: ubuntu-latest
     strategy:
@@ -25,3 +28,26 @@ jobs:
         run: yarn test
       - name: TypeCheck website
         run: yarn workspace website tsc
+  windows-test:
+    name: Windows Tests
+    timeout-minutes: 30
+    runs-on: windows-latest
+    strategy:
+      matrix:
+        node: ['14', '16', '17']
+    steps:
+      - name: Support longpaths
+        run: git config --system core.longpaths true
+      - uses: actions/checkout@v2
+      - name: Use Node.js ${{ matrix.node }}
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ matrix.node }}
+      - name: Installation
+        run: yarn || yarn || yarn # 3 attempts to avoid timeout errors...
+      - name: Docusaurus Jest Tests
+        run: yarn test
+      - name: Docusaurus Build
+        run: yarn build:website --locale en
+        env:
+          CI: true

From 1c024470e0e07a53f6291989fa9edfd5fbf2f1d2 Mon Sep 17 00:00:00 2001
From: Devtato <mstarzycki@gmail.com>
Date: Tue, 9 Nov 2021 18:25:43 +0100
Subject: [PATCH 10/15] feat(content-blog): allow sorting posts in ascending
 order (#5787)

---
 .../src/__tests__/index.test.ts                       | 11 +++++++++++
 .../docusaurus-plugin-content-blog/src/blogUtils.ts   |  3 +++
 .../src/pluginOptionSchema.ts                         |  4 ++++
 packages/docusaurus-plugin-content-blog/src/types.ts  |  1 +
 website/docs/api/plugins/plugin-content-blog.md       |  1 +
 5 files changed, 20 insertions(+)

diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts
index 0aa725b0bf94..35f7431905ad 100644
--- a/packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts
+++ b/packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts
@@ -394,4 +394,15 @@ describe('loadBlog', () => {
       truncated: false,
     });
   });
+
+  test('test ascending sort direction of blog post', async () => {
+    const siteDir = path.join(__dirname, '__fixtures__', 'website');
+    const normalOrder = await getBlogPosts(siteDir);
+    const reversedOrder = await getBlogPosts(siteDir, {
+      sortPosts: 'ascending',
+    });
+    expect(normalOrder.reverse().map((x) => x.metadata.date)).toEqual(
+      reversedOrder.map((x) => x.metadata.date),
+    );
+  });
 });
diff --git a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts
index 39c98ecea3cb..7d250d4d1d54 100644
--- a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts
+++ b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts
@@ -294,6 +294,9 @@ export async function generateBlogPosts(
     (a, b) => b.metadata.date.getTime() - a.metadata.date.getTime(),
   );
 
+  if (options.sortPosts === 'ascending') {
+    return blogPosts.reverse();
+  }
   return blogPosts;
 }
 
diff --git a/packages/docusaurus-plugin-content-blog/src/pluginOptionSchema.ts b/packages/docusaurus-plugin-content-blog/src/pluginOptionSchema.ts
index 00ede624e043..e231ea36bf2a 100644
--- a/packages/docusaurus-plugin-content-blog/src/pluginOptionSchema.ts
+++ b/packages/docusaurus-plugin-content-blog/src/pluginOptionSchema.ts
@@ -42,6 +42,7 @@ export const DEFAULT_OPTIONS: PluginOptions = {
   editLocalizedFiles: false,
   authorsMapPath: 'authors.yml',
   readingTime: ({content, defaultReadingTime}) => defaultReadingTime({content}),
+  sortPosts: 'descending',
 };
 
 export const PluginOptionSchema = Joi.object<PluginOptions>({
@@ -115,4 +116,7 @@ export const PluginOptionSchema = Joi.object<PluginOptions>({
   }).default(DEFAULT_OPTIONS.feedOptions),
   authorsMapPath: Joi.string().default(DEFAULT_OPTIONS.authorsMapPath),
   readingTime: Joi.function().default(() => DEFAULT_OPTIONS.readingTime),
+  sortPosts: Joi.string()
+    .valid('descending', 'ascending')
+    .default(DEFAULT_OPTIONS.sortPosts),
 });
diff --git a/packages/docusaurus-plugin-content-blog/src/types.ts b/packages/docusaurus-plugin-content-blog/src/types.ts
index e8990d5437d7..15d129bcca67 100644
--- a/packages/docusaurus-plugin-content-blog/src/types.ts
+++ b/packages/docusaurus-plugin-content-blog/src/types.ts
@@ -96,6 +96,7 @@ export type PluginOptions = RemarkAndRehypePluginOptions & {
   admonitions: Record<string, unknown>;
   authorsMapPath: string;
   readingTime: ReadingTimeFunctionOption;
+  sortPosts: 'ascending' | 'descending';
 };
 
 // Options, as provided in the user config (before normalization)
diff --git a/website/docs/api/plugins/plugin-content-blog.md b/website/docs/api/plugins/plugin-content-blog.md
index f769ab10b3f4..cc08420d03ae 100644
--- a/website/docs/api/plugins/plugin-content-blog.md
+++ b/website/docs/api/plugins/plugin-content-blog.md
@@ -59,6 +59,7 @@ Accepted fields:
 | `feedOptions.description` | `string` | <code>\`${siteConfig.title} Blog\`</code> | Description of the feed. |
 | `feedOptions.copyright` | `string` | `undefined` | Copyright message. |
 | `feedOptions.language` | `string` (See [documentation](http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes) for possible values) | `undefined` | Language metadata of the feed. |
+| `sortPosts` | <code>'descending' \| 'ascending' </code> | `'descending'` | Governs the direction of blog post sorting. |
 
 </small>
 

From eab8c7c010b224a7c8af54c8c36aee08ea6f7807 Mon Sep 17 00:00:00 2001
From: Joshua Chen <sidachen2003@gmail.com>
Date: Wed, 10 Nov 2021 02:32:55 +0800
Subject: [PATCH 11/15] feat(core): give more hints when plugins have duplicate
 IDs (#5899)

---
 .../__snapshots__/pluginIds.test.ts.snap         | 16 ++++++++++------
 .../docusaurus/src/server/plugins/pluginIds.ts   |  8 +++++++-
 2 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/packages/docusaurus/src/server/plugins/__tests__/__snapshots__/pluginIds.test.ts.snap b/packages/docusaurus/src/server/plugins/__tests__/__snapshots__/pluginIds.test.ts.snap
index fc9593b90802..3b6110ff3a7d 100644
--- a/packages/docusaurus/src/server/plugins/__tests__/__snapshots__/pluginIds.test.ts.snap
+++ b/packages/docusaurus/src/server/plugins/__tests__/__snapshots__/pluginIds.test.ts.snap
@@ -1,16 +1,20 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`ensureUniquePluginInstanceIds reject multi instance plugins with same id 1`] = `
-"Plugin \\"plugin-docs\\" is used 2 times with id sameId.
-To use the same plugin multiple times on a Docusaurus site, you need to assign a unique id to each plugin instance."
+"Plugin \\"plugin-docs\\" is used 2 times with ID \\"sameId\\".
+To use the same plugin multiple times on a Docusaurus site, you need to assign a unique ID to each plugin instance."
 `;
 
 exports[`ensureUniquePluginInstanceIds reject multi instance plugins without id 1`] = `
-"Plugin \\"plugin-docs\\" is used 2 times with id default.
-To use the same plugin multiple times on a Docusaurus site, you need to assign a unique id to each plugin instance."
+"Plugin \\"plugin-docs\\" is used 2 times with ID \\"default\\".
+To use the same plugin multiple times on a Docusaurus site, you need to assign a unique ID to each plugin instance.
+
+The plugin ID is \\"default\\" by default. It's possible that the preset you are using already includes a plugin instance, in which case you either want to disable the plugin in the preset (to use a single instance), or assign another ID to your extra plugin instance (to use multiple instances)."
 `;
 
 exports[`ensureUniquePluginInstanceIds reject multi instance plugins without id 2`] = `
-"Plugin \\"plugin-docs\\" is used 2 times with id default.
-To use the same plugin multiple times on a Docusaurus site, you need to assign a unique id to each plugin instance."
+"Plugin \\"plugin-docs\\" is used 2 times with ID \\"default\\".
+To use the same plugin multiple times on a Docusaurus site, you need to assign a unique ID to each plugin instance.
+
+The plugin ID is \\"default\\" by default. It's possible that the preset you are using already includes a plugin instance, in which case you either want to disable the plugin in the preset (to use a single instance), or assign another ID to your extra plugin instance (to use multiple instances)."
 `;
diff --git a/packages/docusaurus/src/server/plugins/pluginIds.ts b/packages/docusaurus/src/server/plugins/pluginIds.ts
index 1f4941a3ae95..ac0238ff3ccb 100644
--- a/packages/docusaurus/src/server/plugins/pluginIds.ts
+++ b/packages/docusaurus/src/server/plugins/pluginIds.ts
@@ -24,7 +24,13 @@ export function ensureUniquePluginInstanceIds(
       ([pluginId, pluginInstancesWithId]) => {
         if (pluginInstancesWithId.length !== 1) {
           throw new Error(
-            `Plugin "${pluginName}" is used ${pluginInstancesWithId.length} times with id ${pluginId}.\nTo use the same plugin multiple times on a Docusaurus site, you need to assign a unique id to each plugin instance.`,
+            `Plugin "${pluginName}" is used ${
+              pluginInstancesWithId.length
+            } times with ID "${pluginId}".\nTo use the same plugin multiple times on a Docusaurus site, you need to assign a unique ID to each plugin instance.${
+              pluginId === DEFAULT_PLUGIN_ID
+                ? `\n\nThe plugin ID is "${DEFAULT_PLUGIN_ID}" by default. It's possible that the preset you are using already includes a plugin instance, in which case you either want to disable the plugin in the preset (to use a single instance), or assign another ID to your extra plugin instance (to use multiple instances).`
+                : ''
+            }`,
           );
         }
       },

From c541e2d83c0066e92dd13f018698081bf78b387c Mon Sep 17 00:00:00 2001
From: Swalah Amani <mail@swalahamani.com>
Date: Wed, 10 Nov 2021 00:16:10 +0530
Subject: [PATCH 12/15] misc: replace all "Metadatas" with "Metadata" (#5871)

Co-authored-by: Josh-Cena <sidachen2003@gmail.com>
---
 .../docs/tutorial-basics/create-a-document.md |  2 +-
 .../docs/tutorial-basics/create-a-document.md |  2 +-
 .../docs/tutorial-basics/create-a-document.md |  2 +-
 .../docs/tutorial-basics/create-a-document.md |  2 +-
 .../writeRedirectFiles.test.ts.snap           | 10 +++---
 .../src/__tests__/writeRedirectFiles.test.ts  | 10 +++---
 .../src/__tests__/index.test.ts               |  6 ++--
 .../src/docFrontMatter.ts                     |  2 +-
 .../src/docs.ts                               |  2 +-
 .../src/sidebars/__tests__/generator.test.ts  |  7 ++--
 .../src/sidebars/generator.ts                 | 26 +++++++--------
 .../src/sidebars/types.ts                     |  4 +--
 .../src/translations.ts                       |  2 +-
 .../src/__tests__/index.test.ts               |  8 ++---
 .../src/theme/BlogListPage/index.tsx          |  2 +-
 .../src/theme/BlogTagsListPage/index.tsx      |  2 +-
 .../src/theme/BlogTagsPostsPage/index.tsx     |  2 +-
 .../src/theme/DocPage/index.tsx               |  2 +-
 .../src/theme/DocTagDocListPage/index.tsx     |  2 +-
 .../src/theme/DocTagsListPage/index.tsx       |  2 +-
 .../src/theme/LayoutHead/index.tsx            | 17 +++++-----
 .../index.tsx                                 |  4 +--
 .../docusaurus-theme-classic/src/types.d.ts   |  8 ++---
 .../src/validateThemeConfig.ts                | 13 +++++---
 .../utils/__tests__/codeBlockUtils.test.ts    |  4 +--
 .../src/utils/useThemeConfig.ts               |  2 +-
 .../index.js                                  |  4 +--
 .../hooks/useAlgoliaContextualFacetFilters.js |  2 +-
 .../src/__tests__/markdownParser.test.ts      |  4 +--
 .../docs/api/plugins/plugin-content-docs.md   |  2 +-
 .../docs/api/themes/theme-configuration.md    |  8 ++---
 website/docs/guides/docs/sidebar.md           |  6 ++--
 ...dx => markdown-features-head-metadata.mdx} | 32 +++++++++----------
 website/docs/seo.md                           |  6 ++--
 website/docusaurus.config.js                  |  2 +-
 website/sidebars.js                           |  2 +-
 36 files changed, 107 insertions(+), 106 deletions(-)
 rename packages/docusaurus-theme-classic/src/theme/{SearchMetadatas => SearchMetadata}/index.tsx (88%)
 rename packages/docusaurus-theme-search-algolia/src/theme/{SearchMetadatas => SearchMetadata}/index.js (89%)
 rename website/docs/guides/markdown-features/{markdown-features-head-metadatas.mdx => markdown-features-head-metadata.mdx} (55%)

diff --git a/examples/classic-typescript/docs/tutorial-basics/create-a-document.md b/examples/classic-typescript/docs/tutorial-basics/create-a-document.md
index b4a072ecddc1..feaced79d0a3 100644
--- a/examples/classic-typescript/docs/tutorial-basics/create-a-document.md
+++ b/examples/classic-typescript/docs/tutorial-basics/create-a-document.md
@@ -26,7 +26,7 @@ A new document is now available at `http://localhost:3000/docs/hello`.
 
 Docusaurus automatically **creates a sidebar** from the `docs` folder.
 
-Add metadatas to customize the sidebar label and position:
+Add metadata to customize the sidebar label and position:
 
 ```md title="docs/hello.md" {1-4}
 ---
diff --git a/examples/classic/docs/tutorial-basics/create-a-document.md b/examples/classic/docs/tutorial-basics/create-a-document.md
index b4a072ecddc1..feaced79d0a3 100644
--- a/examples/classic/docs/tutorial-basics/create-a-document.md
+++ b/examples/classic/docs/tutorial-basics/create-a-document.md
@@ -26,7 +26,7 @@ A new document is now available at `http://localhost:3000/docs/hello`.
 
 Docusaurus automatically **creates a sidebar** from the `docs` folder.
 
-Add metadatas to customize the sidebar label and position:
+Add metadata to customize the sidebar label and position:
 
 ```md title="docs/hello.md" {1-4}
 ---
diff --git a/examples/facebook/docs/tutorial-basics/create-a-document.md b/examples/facebook/docs/tutorial-basics/create-a-document.md
index b4a072ecddc1..feaced79d0a3 100644
--- a/examples/facebook/docs/tutorial-basics/create-a-document.md
+++ b/examples/facebook/docs/tutorial-basics/create-a-document.md
@@ -26,7 +26,7 @@ A new document is now available at `http://localhost:3000/docs/hello`.
 
 Docusaurus automatically **creates a sidebar** from the `docs` folder.
 
-Add metadatas to customize the sidebar label and position:
+Add metadata to customize the sidebar label and position:
 
 ```md title="docs/hello.md" {1-4}
 ---
diff --git a/packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-document.md b/packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-document.md
index b4a072ecddc1..feaced79d0a3 100644
--- a/packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-document.md
+++ b/packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-document.md
@@ -26,7 +26,7 @@ A new document is now available at `http://localhost:3000/docs/hello`.
 
 Docusaurus automatically **creates a sidebar** from the `docs` folder.
 
-Add metadatas to customize the sidebar label and position:
+Add metadata to customize the sidebar label and position:
 
 ```md title="docs/hello.md" {1-4}
 ---
diff --git a/packages/docusaurus-plugin-client-redirects/src/__tests__/__snapshots__/writeRedirectFiles.test.ts.snap b/packages/docusaurus-plugin-client-redirects/src/__tests__/__snapshots__/writeRedirectFiles.test.ts.snap
index 835742061507..a57e33c0c21f 100644
--- a/packages/docusaurus-plugin-client-redirects/src/__tests__/__snapshots__/writeRedirectFiles.test.ts.snap
+++ b/packages/docusaurus-plugin-client-redirects/src/__tests__/__snapshots__/writeRedirectFiles.test.ts.snap
@@ -1,6 +1,6 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`toRedirectFilesMetadata should create appropriate metadatas for empty baseUrl: fileContent baseUrl=empty 1`] = `
+exports[`toRedirectFilesMetadata should create appropriate metadata for empty baseUrl: fileContent baseUrl=empty 1`] = `
 Array [
   "<!DOCTYPE html>
 <html>
@@ -16,7 +16,7 @@ Array [
 ]
 `;
 
-exports[`toRedirectFilesMetadata should create appropriate metadatas for root baseUrl: fileContent baseUrl=/ 1`] = `
+exports[`toRedirectFilesMetadata should create appropriate metadata for root baseUrl: fileContent baseUrl=/ 1`] = `
 Array [
   "<!DOCTYPE html>
 <html>
@@ -32,7 +32,7 @@ Array [
 ]
 `;
 
-exports[`toRedirectFilesMetadata should create appropriate metadatas trailingSlash=false: fileContent 1`] = `
+exports[`toRedirectFilesMetadata should create appropriate metadata trailingSlash=false: fileContent 1`] = `
 Array [
   "<!DOCTYPE html>
 <html>
@@ -70,7 +70,7 @@ Array [
 ]
 `;
 
-exports[`toRedirectFilesMetadata should create appropriate metadatas trailingSlash=true: fileContent 1`] = `
+exports[`toRedirectFilesMetadata should create appropriate metadata trailingSlash=true: fileContent 1`] = `
 Array [
   "<!DOCTYPE html>
 <html>
@@ -108,7 +108,7 @@ Array [
 ]
 `;
 
-exports[`toRedirectFilesMetadata should create appropriate metadatas trailingSlash=undefined: fileContent 1`] = `
+exports[`toRedirectFilesMetadata should create appropriate metadata trailingSlash=undefined: fileContent 1`] = `
 Array [
   "<!DOCTYPE html>
 <html>
diff --git a/packages/docusaurus-plugin-client-redirects/src/__tests__/writeRedirectFiles.test.ts b/packages/docusaurus-plugin-client-redirects/src/__tests__/writeRedirectFiles.test.ts
index b715250baffc..1fafba797b5a 100644
--- a/packages/docusaurus-plugin-client-redirects/src/__tests__/writeRedirectFiles.test.ts
+++ b/packages/docusaurus-plugin-client-redirects/src/__tests__/writeRedirectFiles.test.ts
@@ -42,7 +42,7 @@ describe('createToUrl', () => {
 });
 
 describe('toRedirectFilesMetadata', () => {
-  test('should create appropriate metadatas trailingSlash=undefined', async () => {
+  test('should create appropriate metadata trailingSlash=undefined', async () => {
     const pluginContext = {
       outDir: '/tmp/someFixedOutDir',
       baseUrl: 'https://docusaurus.io',
@@ -69,7 +69,7 @@ describe('toRedirectFilesMetadata', () => {
     );
   });
 
-  test('should create appropriate metadatas trailingSlash=true', async () => {
+  test('should create appropriate metadata trailingSlash=true', async () => {
     const pluginContext = {
       outDir: '/tmp/someFixedOutDir',
       baseUrl: 'https://docusaurus.io',
@@ -96,7 +96,7 @@ describe('toRedirectFilesMetadata', () => {
     );
   });
 
-  test('should create appropriate metadatas trailingSlash=false', async () => {
+  test('should create appropriate metadata trailingSlash=false', async () => {
     const pluginContext = {
       outDir: '/tmp/someFixedOutDir',
       baseUrl: 'https://docusaurus.io',
@@ -124,7 +124,7 @@ describe('toRedirectFilesMetadata', () => {
     );
   });
 
-  test('should create appropriate metadatas for root baseUrl', async () => {
+  test('should create appropriate metadata for root baseUrl', async () => {
     const pluginContext = {
       outDir: '/tmp/someFixedOutDir',
       baseUrl: '/',
@@ -139,7 +139,7 @@ describe('toRedirectFilesMetadata', () => {
     );
   });
 
-  test('should create appropriate metadatas for empty baseUrl', async () => {
+  test('should create appropriate metadata for empty baseUrl', async () => {
     const pluginContext = {
       outDir: '/tmp/someFixedOutDir',
       baseUrl: '',
diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts
index a17d351bcdc4..cdc1402b45f5 100644
--- a/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts
@@ -1021,7 +1021,7 @@ describe('site with full autogenerated sidebar', () => {
     });
   });
 
-  test('docs in fully generated sidebar have correct metadatas', async () => {
+  test('docs in fully generated sidebar have correct metadata', async () => {
     const {content, siteDir} = await loadSite();
     const version = content.loadedVersions[0];
 
@@ -1518,11 +1518,11 @@ describe('site with partial autogenerated sidebars', () => {
     });
   });
 
-  test('docs in partially generated sidebar have correct metadatas', async () => {
+  test('docs in partially generated sidebar have correct metadata', async () => {
     const {content, siteDir} = await loadSite();
     const version = content.loadedVersions[0];
 
-    // Only looking at the docs of the autogen sidebar, others metadatas should not be affected
+    // Only looking at the docs of the autogen sidebar, others metadata should not be affected
 
     expect(getDocById(version, 'API/api-end')).toEqual({
       ...defaultDocMetadata,
diff --git a/packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts b/packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts
index 1a20d1485ad2..c03a76afbfc8 100644
--- a/packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts
+++ b/packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts
@@ -15,7 +15,7 @@ import {
 import {DocFrontMatter} from './types';
 
 // NOTE: we don't add any default value on purpose here
-// We don't want default values to magically appear in doc metadatas and props
+// We don't want default values to magically appear in doc metadata and props
 // While the user did not provide those values explicitly
 // We use default values in code instead
 const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
diff --git a/packages/docusaurus-plugin-content-docs/src/docs.ts b/packages/docusaurus-plugin-content-docs/src/docs.ts
index c2532d12ccc0..385cec73104e 100644
--- a/packages/docusaurus-plugin-content-docs/src/docs.ts
+++ b/packages/docusaurus-plugin-content-docs/src/docs.ts
@@ -284,7 +284,7 @@ export function processDocMetadata(args: {
   } catch (e) {
     console.error(
       chalk.red(
-        `Can't process doc metadatas for doc at path "${args.docFile.filePath}" in version "${args.versionMetadata.versionName}"`,
+        `Can't process doc metadata for doc at path "${args.docFile.filePath}" in version "${args.versionMetadata.versionName}"`,
       ),
     );
     throw e;
diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts
index 5e75012a9270..cd1089fba867 100644
--- a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts
@@ -5,10 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {
-  CategoryMetadatasFile,
-  DefaultSidebarItemsGenerator,
-} from '../generator';
+import {CategoryMetadataFile, DefaultSidebarItemsGenerator} from '../generator';
 import {Sidebar, SidebarItemsGenerator} from '../types';
 import fs from 'fs-extra';
 import {DefaultNumberPrefixParser} from '../../numberPrefix';
@@ -37,7 +34,7 @@ describe('DefaultSidebarItemsGenerator', () => {
   }
 
   function mockCategoryMetadataFiles(
-    categoryMetadataFiles: Record<string, Partial<CategoryMetadatasFile>>,
+    categoryMetadataFiles: Record<string, Partial<CategoryMetadataFile>>,
   ) {
     jest.spyOn(fs, 'pathExists').mockImplementation((metadataFilePath) => {
       return typeof categoryMetadataFiles[metadataFilePath] !== 'undefined';
diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts
index d5dde0d7f1ea..a936980a8387 100644
--- a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts
+++ b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts
@@ -27,7 +27,7 @@ const docIdPrefix = '$doc$/';
 export const CategoryMetadataFilenameBase = '_category_';
 export const CategoryMetadataFilenamePattern = '_category_.{json,yml,yaml}';
 
-export type CategoryMetadatasFile = {
+export type CategoryMetadataFile = {
   label?: string;
   position?: number;
   collapsed?: boolean;
@@ -50,7 +50,7 @@ type Dir = {
   [item: string]: Dir | null;
 };
 
-const CategoryMetadatasFileSchema = Joi.object<CategoryMetadatasFile>({
+const CategoryMetadataFileSchema = Joi.object<CategoryMetadataFile>({
   label: Joi.string(),
   position: Joi.number(),
   collapsed: Joi.boolean(),
@@ -62,14 +62,14 @@ const CategoryMetadatasFileSchema = Joi.object<CategoryMetadatasFile>({
 // Example use-case being able to disable number prefix parsing at the folder level, or customize the default route path segment for an intermediate directory...
 // TODO later if there is `CategoryFolder/index.md`, we may want to read the metadata as yaml on it
 // see https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
-async function readCategoryMetadatasFile(
+async function readCategoryMetadataFile(
   categoryDirPath: string,
-): Promise<CategoryMetadatasFile | null> {
-  async function tryReadFile(filePath: string): Promise<CategoryMetadatasFile> {
+): Promise<CategoryMetadataFile | null> {
+  async function tryReadFile(filePath: string): Promise<CategoryMetadataFile> {
     const contentString = await fs.readFile(filePath, {encoding: 'utf8'});
     const unsafeContent = Yaml.load(contentString);
     try {
-      return Joi.attempt(unsafeContent, CategoryMetadatasFileSchema);
+      return Joi.attempt(unsafeContent, CategoryMetadataFileSchema);
     } catch (e) {
       console.error(
         chalk.red(
@@ -81,7 +81,7 @@ async function readCategoryMetadatasFile(
   }
   // eslint-disable-next-line no-restricted-syntax
   for (const ext of ['.json', '.yml', '.yaml']) {
-    // Simpler to use only posix paths for mocking file metadatas in tests
+    // Simpler to use only posix paths for mocking file metadata in tests
     const filePath = posixPath(
       path.join(categoryDirPath, `${CategoryMetadataFilenameBase}${ext}`),
     );
@@ -184,16 +184,16 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
       folderName: string,
     ): Promise<WithPosition<SidebarItemCategory>> {
       const categoryPath = path.join(version.contentPath, autogenDir, fullPath);
-      const categoryMetadatas = await readCategoryMetadatasFile(categoryPath);
-      const className = categoryMetadatas?.className;
+      const categoryMetadata = await readCategoryMetadataFile(categoryPath);
+      const className = categoryMetadata?.className;
       const {filename, numberPrefix} = numberPrefixParser(folderName);
       return {
         type: 'category',
-        label: categoryMetadatas?.label ?? filename,
+        label: categoryMetadata?.label ?? filename,
         collapsible:
-          categoryMetadatas?.collapsible ?? options.sidebarCollapsible,
-        collapsed: categoryMetadatas?.collapsed ?? options.sidebarCollapsed,
-        position: categoryMetadatas?.position ?? numberPrefix,
+          categoryMetadata?.collapsible ?? options.sidebarCollapsible,
+        collapsed: categoryMetadata?.collapsed ?? options.sidebarCollapsed,
+        position: categoryMetadata?.position ?? numberPrefix,
         ...(className !== undefined && {className}),
         items: await Promise.all(
           Object.entries(dir).map(([key, content]) =>
diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts
index 59e4c73b3a00..ea7866ac5a70 100644
--- a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts
+++ b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts
@@ -124,8 +124,8 @@ export type PropSidebars = {
 };
 
 // Reduce API surface for options.sidebarItemsGenerator
-// The user-provided generator fn should receive only a subset of metadatas
-// A change to any of these metadatas can be considered as a breaking change
+// The user-provided generator fn should receive only a subset of metadata
+// A change to any of these metadata can be considered as a breaking change
 export type SidebarItemsGeneratorDoc = Pick<
   DocMetadataBase,
   'id' | 'frontMatter' | 'source' | 'sourceDirName' | 'sidebarPosition'
diff --git a/packages/docusaurus-plugin-content-docs/src/translations.ts b/packages/docusaurus-plugin-content-docs/src/translations.ts
index 138deca2c2fd..2e54490f425f 100644
--- a/packages/docusaurus-plugin-content-docs/src/translations.ts
+++ b/packages/docusaurus-plugin-content-docs/src/translations.ts
@@ -50,7 +50,7 @@ function getNormalizedSidebarName({
 }
 
 /*
-// Do we need to translate doc metadatas?
+// Do we need to translate doc metadata?
 // It seems translating frontmatter labels is good enough
 function getDocTranslations(doc: DocMetadata): TranslationFileContent {
   return {
diff --git a/packages/docusaurus-plugin-content-pages/src/__tests__/index.test.ts b/packages/docusaurus-plugin-content-pages/src/__tests__/index.test.ts
index 717a82e38b93..920dc6cf6f90 100644
--- a/packages/docusaurus-plugin-content-pages/src/__tests__/index.test.ts
+++ b/packages/docusaurus-plugin-content-pages/src/__tests__/index.test.ts
@@ -22,9 +22,9 @@ describe('docusaurus-plugin-content-pages', () => {
         path: pluginPath,
       }),
     );
-    const pagesMetadatas = await plugin.loadContent?.();
+    const pagesMetadata = await plugin.loadContent?.();
 
-    expect(pagesMetadatas).toEqual([
+    expect(pagesMetadata).toEqual([
       {
         type: 'jsx',
         permalink: '/',
@@ -89,7 +89,7 @@ describe('docusaurus-plugin-content-pages', () => {
         path: pluginPath,
       }),
     );
-    const pagesMetadatas = await plugin.loadContent?.();
+    const pagesMetadata = await plugin.loadContent?.();
 
     const frTranslationsPath = path.posix.join(
       '@site',
@@ -98,7 +98,7 @@ describe('docusaurus-plugin-content-pages', () => {
       'docusaurus-plugin-content-pages',
     );
 
-    expect(pagesMetadatas).toEqual([
+    expect(pagesMetadata).toEqual([
       {
         type: 'jsx',
         permalink: '/',
diff --git a/packages/docusaurus-theme-classic/src/theme/BlogListPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/BlogListPage/index.tsx
index 2179aeaca35d..93202f38766c 100644
--- a/packages/docusaurus-theme-classic/src/theme/BlogListPage/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/BlogListPage/index.tsx
@@ -29,7 +29,7 @@ function BlogListPage(props: Props): JSX.Element {
       description={blogDescription}
       wrapperClassName={ThemeClassNames.wrapper.blogPages}
       pageClassName={ThemeClassNames.page.blogListPage}
-      searchMetadatas={{
+      searchMetadata={{
         // assign unique search tag to exclude this page from search results!
         tag: 'blog_posts_list',
       }}
diff --git a/packages/docusaurus-theme-classic/src/theme/BlogTagsListPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/BlogTagsListPage/index.tsx
index 44ab055e06e8..eb8f3d940c53 100644
--- a/packages/docusaurus-theme-classic/src/theme/BlogTagsListPage/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/BlogTagsListPage/index.tsx
@@ -23,7 +23,7 @@ function BlogTagsListPage(props: Props): JSX.Element {
       title={title}
       wrapperClassName={ThemeClassNames.wrapper.blogPages}
       pageClassName={ThemeClassNames.page.blogTagsListPage}
-      searchMetadatas={{
+      searchMetadata={{
         // assign unique search tag to exclude this page from search results!
         tag: 'blog_tags_list',
       }}
diff --git a/packages/docusaurus-theme-classic/src/theme/BlogTagsPostsPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/BlogTagsPostsPage/index.tsx
index 0d33d755db92..2c8e46a4918e 100644
--- a/packages/docusaurus-theme-classic/src/theme/BlogTagsPostsPage/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/BlogTagsPostsPage/index.tsx
@@ -50,7 +50,7 @@ export default function BlogTagsPostsPage(props: Props): JSX.Element {
       title={title}
       wrapperClassName={ThemeClassNames.wrapper.blogPages}
       pageClassName={ThemeClassNames.page.blogTagPostListPage}
-      searchMetadatas={{
+      searchMetadata={{
         // assign unique search tag to exclude this page from search results!
         tag: 'blog_tags_posts',
       }}
diff --git a/packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx
index df3a2a29d206..6c66c5f6514c 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx
@@ -58,7 +58,7 @@ function DocPageContent({
     <Layout
       wrapperClassName={ThemeClassNames.wrapper.docsPages}
       pageClassName={ThemeClassNames.page.docsDocPage}
-      searchMetadatas={{
+      searchMetadata={{
         version,
         tag: docVersionSearchTag(pluginId, version),
       }}>
diff --git a/packages/docusaurus-theme-classic/src/theme/DocTagDocListPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocTagDocListPage/index.tsx
index 5a5dbe24f496..1021a1980553 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocTagDocListPage/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/DocTagDocListPage/index.tsx
@@ -59,7 +59,7 @@ export default function DocTagDocListPage({tag}: Props): JSX.Element {
       title={title}
       wrapperClassName={ThemeClassNames.wrapper.docsPages}
       pageClassName={ThemeClassNames.page.docsTagDocListPage}
-      searchMetadatas={{
+      searchMetadata={{
         // assign unique search tag to exclude this page from search results!
         tag: 'doc_tag_doc_list',
       }}>
diff --git a/packages/docusaurus-theme-classic/src/theme/DocTagsListPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocTagsListPage/index.tsx
index 7c5348f12a02..eec9e8afc998 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocTagsListPage/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/DocTagsListPage/index.tsx
@@ -22,7 +22,7 @@ function DocTagsListPage({tags}: Props): JSX.Element {
       title={title}
       wrapperClassName={ThemeClassNames.wrapper.docsPages}
       pageClassName={ThemeClassNames.page.docsTagsListPage}
-      searchMetadatas={{
+      searchMetadata={{
         // assign unique search tag to exclude this page from search results!
         tag: 'doc_tags_list',
       }}>
diff --git a/packages/docusaurus-theme-classic/src/theme/LayoutHead/index.tsx b/packages/docusaurus-theme-classic/src/theme/LayoutHead/index.tsx
index 59206c00d118..6f06ccea7e4b 100644
--- a/packages/docusaurus-theme-classic/src/theme/LayoutHead/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/LayoutHead/index.tsx
@@ -10,7 +10,7 @@ import Head from '@docusaurus/Head';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import type {Props} from '@theme/Layout';
-import SearchMetadatas from '@theme/SearchMetadatas';
+import SearchMetadata from '@theme/SearchMetadata';
 import Seo from '@theme/Seo';
 import {
   DEFAULT_SEARCH_TAG,
@@ -87,8 +87,8 @@ export default function LayoutHead(props: Props): JSX.Element {
     siteConfig: {favicon},
     i18n: {currentLocale, localeConfigs},
   } = useDocusaurusContext();
-  const {metadatas, image: defaultImage} = useThemeConfig();
-  const {title, description, image, keywords, searchMetadatas} = props;
+  const {metadata, image: defaultImage} = useThemeConfig();
+  const {title, description, image, keywords, searchMetadata} = props;
   const faviconUrl = useBaseUrl(favicon);
   const pageTitle = useTitleFormatter(title);
 
@@ -117,21 +117,22 @@ export default function LayoutHead(props: Props): JSX.Element {
 
       <AlternateLangHeaders />
 
-      <SearchMetadatas
+      <SearchMetadata
         tag={DEFAULT_SEARCH_TAG}
         locale={currentLocale}
-        {...searchMetadatas}
+        {...searchMetadata}
       />
 
       <Head
       // it's important to have an additional <Head> element here,
       // as it allows react-helmet to override values set in previous <Head>
-      // ie we can override default metadatas such as "twitter:card"
+      // ie we can override default metadata such as "twitter:card"
       // In same Head, the same meta would appear twice instead of overriding
       // See react-helmet doc
       >
-        {metadatas.map((metadata, i) => (
-          <meta key={`metadata_${i}`} {...metadata} />
+        {/* Yes, "metadatum" is the grammatically correct term */}
+        {metadata.map((metadatum, i) => (
+          <meta key={`metadata_${i}`} {...metadatum} />
         ))}
       </Head>
     </>
diff --git a/packages/docusaurus-theme-classic/src/theme/SearchMetadatas/index.tsx b/packages/docusaurus-theme-classic/src/theme/SearchMetadata/index.tsx
similarity index 88%
rename from packages/docusaurus-theme-classic/src/theme/SearchMetadatas/index.tsx
rename to packages/docusaurus-theme-classic/src/theme/SearchMetadata/index.tsx
index 5ad846997d37..00ab2092c543 100644
--- a/packages/docusaurus-theme-classic/src/theme/SearchMetadatas/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/SearchMetadata/index.tsx
@@ -8,12 +8,12 @@
 import React from 'react';
 
 import Head from '@docusaurus/Head';
-import type {Props} from '@theme/SearchMetadatas';
+import type {Props} from '@theme/SearchMetadata';
 
 // Note: we don't couple this to Algolia/DocSearch on purpose
 // We may want to support other search engine plugins too
 // Search plugins should swizzle/override this comp to add their behavior
-export default function SearchMetadatas({
+export default function SearchMetadata({
   locale,
   version,
   tag,
diff --git a/packages/docusaurus-theme-classic/src/types.d.ts b/packages/docusaurus-theme-classic/src/types.d.ts
index ccde4567c1e0..e009a75d283c 100644
--- a/packages/docusaurus-theme-classic/src/types.d.ts
+++ b/packages/docusaurus-theme-classic/src/types.d.ts
@@ -301,7 +301,7 @@ declare module '@theme/Layout' {
     readonly permalink?: string;
     readonly wrapperClassName?: string;
     readonly pageClassName?: string;
-    readonly searchMetadatas?: {
+    readonly searchMetadata?: {
       readonly version?: string;
       readonly tag?: string;
     };
@@ -320,15 +320,15 @@ declare module '@theme/LayoutHead' {
   export default LayoutHead;
 }
 
-declare module '@theme/SearchMetadatas' {
+declare module '@theme/SearchMetadata' {
   export interface Props {
     readonly locale?: string;
     readonly version?: string;
     readonly tag?: string;
   }
 
-  const SearchMetadatas: (props: Props) => JSX.Element;
-  export default SearchMetadatas;
+  const SearchMetadata: (props: Props) => JSX.Element;
+  export default SearchMetadata;
 }
 
 declare module '@theme/LastUpdated' {
diff --git a/packages/docusaurus-theme-classic/src/validateThemeConfig.ts b/packages/docusaurus-theme-classic/src/validateThemeConfig.ts
index 18e2146ddeab..6acbedc52384 100644
--- a/packages/docusaurus-theme-classic/src/validateThemeConfig.ts
+++ b/packages/docusaurus-theme-classic/src/validateThemeConfig.ts
@@ -32,7 +32,7 @@ const DEFAULT_COLOR_MODE_CONFIG = {
 const DEFAULT_CONFIG = {
   colorMode: DEFAULT_COLOR_MODE_CONFIG,
   docs: DEFAULT_DOCS_CONFIG,
-  metadatas: [],
+  metadata: [],
   prism: {
     additionalLanguages: [],
   },
@@ -46,7 +46,6 @@ const DEFAULT_CONFIG = {
     maxHeadingLevel: 3,
   },
 };
-exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
 
 const NavbarItemPosition = Joi.string().equal('left', 'right').default('left');
 
@@ -264,9 +263,13 @@ const ThemeConfigSchema = Joi.object({
   colorMode: ColorModeSchema,
   image: Joi.string(),
   docs: DocsSchema,
-  metadatas: Joi.array()
+  metadata: Joi.array()
     .items(HtmlMetadataSchema)
-    .default(DEFAULT_CONFIG.metadatas),
+    .default(DEFAULT_CONFIG.metadata),
+  metadatas: Joi.any().forbidden().messages({
+    'any.unknown':
+      'themeConfig.metadatas has been renamed as themeConfig.metadata. See https://github.com/facebook/docusaurus/pull/5871',
+  }),
   announcementBar: Joi.object({
     id: Joi.string().default('announcement-bar'),
     content: Joi.string().required(),
@@ -358,7 +361,7 @@ const ThemeConfigSchema = Joi.object({
   }).default(DEFAULT_CONFIG.tableOfContents),
 });
 
-export {ThemeConfigSchema};
+export {DEFAULT_CONFIG, ThemeConfigSchema};
 
 export function validateThemeConfig({
   validate,
diff --git a/packages/docusaurus-theme-common/src/utils/__tests__/codeBlockUtils.test.ts b/packages/docusaurus-theme-common/src/utils/__tests__/codeBlockUtils.test.ts
index 80e0f49fe58b..b5d3ade1c83e 100644
--- a/packages/docusaurus-theme-common/src/utils/__tests__/codeBlockUtils.test.ts
+++ b/packages/docusaurus-theme-common/src/utils/__tests__/codeBlockUtils.test.ts
@@ -28,13 +28,13 @@ describe('parseCodeBlockTitle', () => {
     expect(parseCodeBlockTitle(`{1,2-3}`)).toEqual(``);
   });
 
-  test('should parse with multiple metadatas title first', () => {
+  test('should parse with multiple metadata title first', () => {
     expect(parseCodeBlockTitle(`title="index.js" label="JavaScript"`)).toEqual(
       `index.js`,
     );
   });
 
-  test('should parse with multiple metadatas title last', () => {
+  test('should parse with multiple metadata title last', () => {
     expect(parseCodeBlockTitle(`label="JavaScript" title="index.js"`)).toEqual(
       `index.js`,
     );
diff --git a/packages/docusaurus-theme-common/src/utils/useThemeConfig.ts b/packages/docusaurus-theme-common/src/utils/useThemeConfig.ts
index e2cdbe28f78d..97bdefc5317d 100644
--- a/packages/docusaurus-theme-common/src/utils/useThemeConfig.ts
+++ b/packages/docusaurus-theme-common/src/utils/useThemeConfig.ts
@@ -113,7 +113,7 @@ export type ThemeConfig = {
   footer?: Footer;
   hideableSidebar: boolean;
   image?: string;
-  metadatas: Array<Record<string, string>>;
+  metadata: Array<Record<string, string>>;
   sidebarCollapsible: boolean;
   tableOfContents: TableOfContents;
 };
diff --git a/packages/docusaurus-theme-search-algolia/src/theme/SearchMetadatas/index.js b/packages/docusaurus-theme-search-algolia/src/theme/SearchMetadata/index.js
similarity index 89%
rename from packages/docusaurus-theme-search-algolia/src/theme/SearchMetadatas/index.js
rename to packages/docusaurus-theme-search-algolia/src/theme/SearchMetadata/index.js
index f83b7ba1cdc6..584ce2a9c3c2 100644
--- a/packages/docusaurus-theme-search-algolia/src/theme/SearchMetadatas/index.js
+++ b/packages/docusaurus-theme-search-algolia/src/theme/SearchMetadata/index.js
@@ -9,8 +9,8 @@ import React from 'react';
 
 import Head from '@docusaurus/Head';
 
-// Override default/agnostic SearchMetas to use Algolia-specific metadatas
-export default function AlgoliaSearchMetadatas({locale, version, tag}) {
+// Override default/agnostic SearchMetas to use Algolia-specific metadata
+export default function AlgoliaSearchMetadata({locale, version, tag}) {
   // Seems safe to consider here the locale is the language,
   // as the existing docsearch:language filter is afaik a regular string-based filter
   const language = locale;
diff --git a/packages/docusaurus-theme-search-algolia/src/theme/hooks/useAlgoliaContextualFacetFilters.js b/packages/docusaurus-theme-search-algolia/src/theme/hooks/useAlgoliaContextualFacetFilters.js
index c09ef21963ba..3ee15f665d16 100644
--- a/packages/docusaurus-theme-search-algolia/src/theme/hooks/useAlgoliaContextualFacetFilters.js
+++ b/packages/docusaurus-theme-search-algolia/src/theme/hooks/useAlgoliaContextualFacetFilters.js
@@ -11,7 +11,7 @@ import useContextualSearchFilters from '@theme/hooks/useContextualSearchFilters'
 export default function useAlgoliaContextualFacetFilters() {
   const {locale, tags} = useContextualSearchFilters();
 
-  // seems safe to convert locale->language, see AlgoliaSearchMetadatas comment
+  // seems safe to convert locale->language, see AlgoliaSearchMetadata comment
   const languageFilter = `language:${locale}`;
 
   const tagsFilter = tags.map((tag) => `docusaurus_tag:${tag}`);
diff --git a/packages/docusaurus-utils/src/__tests__/markdownParser.test.ts b/packages/docusaurus-utils/src/__tests__/markdownParser.test.ts
index c79d50b4d4b0..e2ed56f1d5f3 100644
--- a/packages/docusaurus-utils/src/__tests__/markdownParser.test.ts
+++ b/packages/docusaurus-utils/src/__tests__/markdownParser.test.ts
@@ -36,7 +36,7 @@ describe('createExcerpt', () => {
           Nunc porttitor libero nec vulputate venenatis. Nam nec rhoncus mauris. Morbi tempus est et nibh maximus, tempus venenatis arcu lobortis.
         `),
     ).toEqual(
-      // h1 title is skipped on purpose, because we don't want the page to have SEO metadatas title === description
+      // h1 title is skipped on purpose, because we don't want the page to have SEO metadata title === description
       'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum ex urna, molestie et sagittis ut, varius ac justo.',
     );
   });
@@ -53,7 +53,7 @@ describe('createExcerpt', () => {
           Nunc porttitor libero nec vulputate venenatis. Nam nec rhoncus mauris. Morbi tempus est et nibh maximus, tempus venenatis arcu lobortis.
         `),
     ).toEqual(
-      // h1 title is skipped on purpose, because we don't want the page to have SEO metadatas title === description
+      // h1 title is skipped on purpose, because we don't want the page to have SEO metadata title === description
       'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum ex urna, molestie et sagittis ut, varius ac justo.',
     );
   });
diff --git a/website/docs/api/plugins/plugin-content-docs.md b/website/docs/api/plugins/plugin-content-docs.md
index ab324d4a096f..eec6458b3795 100644
--- a/website/docs/api/plugins/plugin-content-docs.md
+++ b/website/docs/api/plugins/plugin-content-docs.md
@@ -246,7 +246,7 @@ Accepted fields:
 | `title` | `string` | Markdown title or `id` | The text title of your document. Used for the page metadata and as a fallback value in multiple places (sidebar, next/previous buttons...). Automatically added at the top of your doc if it does not contain any Markdown title. |
 | `pagination_label` | `string` | `sidebar_label` or `title` | The text used in the document next/previous buttons for this document. |
 | `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. |
-| `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadatas](/docs/sidebar#autogenerated-sidebar-metadatas). |
+| `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadata](/docs/sidebar#autogenerated-sidebar-metadata). |
 | `sidebar_class_name` | `string` | `undefined` | Gives the corresponding sidebar label a special class name when using autogenerated sidebars. |
 | `hide_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the frontmatter, and have no effect on a Markdown title at the top of your document. |
 | `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. |
diff --git a/website/docs/api/themes/theme-configuration.md b/website/docs/api/themes/theme-configuration.md
index 4b91fad475e7..637b4a6cd534 100644
--- a/website/docs/api/themes/theme-configuration.md
+++ b/website/docs/api/themes/theme-configuration.md
@@ -93,9 +93,9 @@ module.exports = {
 };
 ```
 
-### Metadatas {#metadatas}
+### Metadata {#metadata}
 
-You can configure additional html metadatas (and override existing ones).
+You can configure additional html metadata (and override existing ones).
 
 Accepted fields:
 
@@ -103,7 +103,7 @@ Accepted fields:
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
-| `metadatas` | `Metadata[]` | `[]` | Any field will be directly passed to the `<meta />` tag. Possible fields include `id`, `name`, `property`, `content`, `itemprop`, etc. |
+| `metadata` | `Metadata[]` | `[]` | Any field will be directly passed to the `<meta />` tag. Possible fields include `id`, `name`, `property`, `content`, `itemprop`, etc. |
 
 </small>
 
@@ -113,7 +113,7 @@ Example configuration:
 module.exports = {
   themeConfig: {
     // highlight-next-line
-    metadatas: [{name: 'twitter:card', content: 'summary'}],
+    metadata: [{name: 'twitter:card', content: 'summary'}],
   },
 };
 ```
diff --git a/website/docs/guides/docs/sidebar.md b/website/docs/guides/docs/sidebar.md
index dfc8c4175bef..bf5de846ed49 100644
--- a/website/docs/guides/docs/sidebar.md
+++ b/website/docs/guides/docs/sidebar.md
@@ -499,11 +499,11 @@ module.exports = {
 };
 ```
 
-#### Autogenerated sidebar metadatas {#autogenerated-sidebar-metadatas}
+#### Autogenerated sidebar metadata {#autogenerated-sidebar-metadata}
 
 By default, the sidebar slice will be generated in **alphabetical order** (using files and folders names).
 
-If the generated sidebar does not look good, you can assign additional metadatas to docs and categories.
+If the generated sidebar does not look good, you can assign additional metadata to docs and categories.
 
 **For docs**: use additional frontmatter:
 
@@ -566,7 +566,7 @@ By default, Docusaurus will **remove the number prefix** from the doc id, title,
 
 :::caution
 
-**Prefer using [additional metadatas](#autogenerated-sidebar-metadatas)**.
+**Prefer using [additional metadata](#autogenerated-sidebar-metadata)**.
 
 Updating a number prefix can be annoying, as it can require **updating multiple existing markdown links**:
 
diff --git a/website/docs/guides/markdown-features/markdown-features-head-metadatas.mdx b/website/docs/guides/markdown-features/markdown-features-head-metadata.mdx
similarity index 55%
rename from website/docs/guides/markdown-features/markdown-features-head-metadatas.mdx
rename to website/docs/guides/markdown-features/markdown-features-head-metadata.mdx
index 4d4c0e6fad1a..c48caf9fccca 100644
--- a/website/docs/guides/markdown-features/markdown-features-head-metadatas.mdx
+++ b/website/docs/guides/markdown-features/markdown-features-head-metadata.mdx
@@ -1,34 +1,34 @@
 ---
-id: head-metadatas
-title: Head Metadatas
-description: Declaring page-specific head metadatas through MDX
-slug: /markdown-features/head-metadatas
+id: head-metadata
+title: Head Metadata
+description: Declaring page-specific head metadata through MDX
+slug: /markdown-features/head-metadata
 ---
 
-# Head Metadatas
+# Head Metadata
 
-Docusaurus automatically sets useful page metadatas in `<html>`, `<head>` and `<body>` for you.
+Docusaurus automatically sets useful page metadata in `<html>`, `<head>` and `<body>` for you.
 
-It is possible to add extra metadatas (or override existing ones) by using the `<head>` tag in Markdown files:
+It is possible to add extra metadata (or override existing ones) by using the `<head>` tag in Markdown files:
 
-```md title="markdown-features-head-metadatas.mdx"
+```md title="markdown-features-head-metadata.mdx"
 ---
-id: head-metadatas
-title: Head Metadatas
+id: head-metadata
+title: Head Metadata
 ---
 
 <!-- highlight-start -->
 <head>
   <html className="some-extra-html-class" />
   <body className="other-extra-body-class" />
-  <title>Head Metadatas customized title!</title>
+  <title>Head Metadata customized title!</title>
   <meta charSet="utf-8" />
   <meta name="twitter:card" content="summary" />
-  <link rel="canonical" href="https://docusaurus.io/docs/markdown-features/head-metadatas" />
+  <link rel="canonical" href="https://docusaurus.io/docs/markdown-features/head-metadata" />
 </head>
 <!-- highlight-end -->
 
-# Head Metadatas
+# Head Metadata
 
 My text
 ```
@@ -37,10 +37,10 @@ My text
 <head>
   <html className="some-extra-html-class" />
   <body className="other-extra-body-class" />
-  <title>Head Metadatas customized title!</title>
+  <title>Head Metadata customized title!</title>
   <meta charSet="utf-8" />
   <meta name="twitter:card" content="summary" />
-  <link rel="canonical" href="https://docusaurus.io/docs/markdown-features/head-metadatas" />
+  <link rel="canonical" href="https://docusaurus.io/docs/markdown-features/head-metadata" />
 </head>
 ```
 
@@ -48,7 +48,7 @@ My text
 
 This `<head>` declaration has been added to the current Markdown doc, as a demo.
 
-Open your browser DevTools and check how this page's metadatas have been affected.
+Open your browser DevTools and check how this page's metadata have been affected.
 
 :::
 
diff --git a/website/docs/seo.md b/website/docs/seo.md
index 15cbd88a99c7..6fe946bb9149 100644
--- a/website/docs/seo.md
+++ b/website/docs/seo.md
@@ -11,12 +11,12 @@ Docusaurus supports search engine optimization in a variety of ways.
 
 ## Global metadata {#global-metadata}
 
-Provide global meta attributes for the entire site through the [site configuration](./configuration.md#site-metadata). The metadatas will all be rendered in the HTML `<head>` using the key-value pairs as the prop name and value.
+Provide global meta attributes for the entire site through the [site configuration](./configuration.md#site-metadata). The metadata will all be rendered in the HTML `<head>` using the key-value pairs as the prop name and value.
 
 ```js title="docusaurus.config.js"
 module.exports = {
   themeConfig: {
-    metadatas: [{name: 'keywords', content: 'cooking, blog'}],
+    metadata: [{name: 'keywords', content: 'cooking, blog'}],
     // This would become <meta name="keywords" content="cooking, blog"> in the generated HTML
   },
 };
@@ -28,7 +28,7 @@ To read more about types of meta tags, visit [the MDN docs](https://developer.mo
 
 ## Single page metadata {#single-page-metadata}
 
-Similar to [global metadata](#global-metadata), Docusaurus also allows for the addition of meta-information to individual pages. Follow [this guide](./guides/markdown-features/markdown-features-head-metadatas.mdx) for configuring the `<head>` tag. In short:
+Similar to [global metadata](#global-metadata), Docusaurus also allows for the addition of meta-information to individual pages. Follow [this guide](./guides/markdown-features/markdown-features-head-metadata.mdx) for configuring the `<head>` tag. In short:
 
 ```md title="my-markdown-page.md"
 # A cooking guide
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index 033433424b07..573d49905184 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -327,7 +327,7 @@ const config = {
         additionalLanguages: ['java'],
       },
       image: 'img/docusaurus-soc.png',
-      // metadatas: [{name: 'twitter:card', content: 'summary'}],
+      // metadata: [{name: 'twitter:card', content: 'summary'}],
       gtag: !isDeployPreview
         ? {
             trackingID: 'UA-141789564-1',
diff --git a/website/sidebars.js b/website/sidebars.js
index 56fc549a5f18..549aeace2fe5 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -52,7 +52,7 @@ const sidebars = {
             'guides/markdown-features/assets',
             'guides/markdown-features/plugins',
             'guides/markdown-features/math-equations',
-            'guides/markdown-features/head-metadatas',
+            'guides/markdown-features/head-metadata',
           ],
         },
         'styling-layout',

From 4478dd965904d509bc04f3aa1459b883be8e1b8f Mon Sep 17 00:00:00 2001
From: Joshua Chen <sidachen2003@gmail.com>
Date: Wed, 10 Nov 2021 14:08:50 +0800
Subject: [PATCH 13/15] docs: make API sidebar partially autogenerated (#5917)

* docs: make API sidebar autogenerated

* fix paths
---
 website/docs/api/docusaurus.config.js.md      |  1 +
 website/docs/{ => api}/lifecycle-apis.md      |  2 ++
 website/docs/api/plugins/_category_.yml       |  2 ++
 website/docs/api/plugins/overview.md          |  1 +
 .../api/plugins/plugin-client-redirects.md    |  1 +
 .../docs/api/plugins/plugin-content-blog.md   |  1 +
 .../docs/api/plugins/plugin-content-docs.md   |  1 +
 .../docs/api/plugins/plugin-content-pages.md  |  1 +
 website/docs/api/plugins/plugin-debug.md      |  1 +
 .../api/plugins/plugin-google-analytics.md    |  1 +
 .../docs/api/plugins/plugin-google-gtag.md    |  1 +
 .../docs/api/plugins/plugin-ideal-image.md    |  1 +
 website/docs/api/plugins/plugin-pwa.md        |  1 +
 website/docs/api/plugins/plugin-sitemap.md    |  1 +
 website/docs/api/themes/_category_.yml        |  2 ++
 website/docs/api/themes/overview.md           |  1 +
 website/docs/api/themes/theme-classic.md      |  1 +
 .../docs/api/themes/theme-configuration.md    |  1 +
 .../docs/api/themes/theme-live-codeblock.md   |  1 +
 .../docs/api/themes/theme-search-algolia.md   |  1 +
 website/docs/typescript-support.md            |  2 +-
 website/docs/using-plugins.md                 |  4 +--
 website/docs/using-themes.md                  | 10 +++----
 website/sidebars.js                           | 30 ++-----------------
 24 files changed, 33 insertions(+), 36 deletions(-)
 rename website/docs/{ => api}/lifecycle-apis.md (99%)
 create mode 100644 website/docs/api/plugins/_category_.yml
 create mode 100644 website/docs/api/themes/_category_.yml

diff --git a/website/docs/api/docusaurus.config.js.md b/website/docs/api/docusaurus.config.js.md
index 92fe87b4e7f2..13df482c5d0d 100644
--- a/website/docs/api/docusaurus.config.js.md
+++ b/website/docs/api/docusaurus.config.js.md
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 0
 id: docusaurus.config.js
 description: API reference for Docusaurus configuration file.
 slug: /api/docusaurus-config
diff --git a/website/docs/lifecycle-apis.md b/website/docs/api/lifecycle-apis.md
similarity index 99%
rename from website/docs/lifecycle-apis.md
rename to website/docs/api/lifecycle-apis.md
index 8dd9d25772bd..9f6aeab8e3be 100644
--- a/website/docs/lifecycle-apis.md
+++ b/website/docs/api/lifecycle-apis.md
@@ -1,6 +1,8 @@
 ---
+sidebar_position: 1
 id: lifecycle-apis
 title: Lifecycle APIs
+slug: /lifecycle-apis
 toc_max_heading_level: 4
 ---
 
diff --git a/website/docs/api/plugins/_category_.yml b/website/docs/api/plugins/_category_.yml
new file mode 100644
index 000000000000..3339c70225d9
--- /dev/null
+++ b/website/docs/api/plugins/_category_.yml
@@ -0,0 +1,2 @@
+label: Plugins
+position: 2
diff --git a/website/docs/api/plugins/overview.md b/website/docs/api/plugins/overview.md
index bbacce004782..31897e73e682 100644
--- a/website/docs/api/plugins/overview.md
+++ b/website/docs/api/plugins/overview.md
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 0
 id: plugins-overview
 title: 'Docusaurus plugins'
 sidebar_label: Plugins overview
diff --git a/website/docs/api/plugins/plugin-client-redirects.md b/website/docs/api/plugins/plugin-client-redirects.md
index 722662c9033c..fca62c455542 100644
--- a/website/docs/api/plugins/plugin-client-redirects.md
+++ b/website/docs/api/plugins/plugin-client-redirects.md
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 4
 id: plugin-client-redirects
 title: '📦 plugin-client-redirects'
 slug: '/api/plugins/@docusaurus/plugin-client-redirects'
diff --git a/website/docs/api/plugins/plugin-content-blog.md b/website/docs/api/plugins/plugin-content-blog.md
index cc08420d03ae..4952487a31bc 100644
--- a/website/docs/api/plugins/plugin-content-blog.md
+++ b/website/docs/api/plugins/plugin-content-blog.md
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 2
 id: plugin-content-blog
 title: '📦 plugin-content-blog'
 slug: '/api/plugins/@docusaurus/plugin-content-blog'
diff --git a/website/docs/api/plugins/plugin-content-docs.md b/website/docs/api/plugins/plugin-content-docs.md
index eec6458b3795..8eb28ade59e3 100644
--- a/website/docs/api/plugins/plugin-content-docs.md
+++ b/website/docs/api/plugins/plugin-content-docs.md
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 1
 id: plugin-content-docs
 title: '📦 plugin-content-docs'
 slug: '/api/plugins/@docusaurus/plugin-content-docs'
diff --git a/website/docs/api/plugins/plugin-content-pages.md b/website/docs/api/plugins/plugin-content-pages.md
index 27e3b0c9b9eb..2059121458c8 100644
--- a/website/docs/api/plugins/plugin-content-pages.md
+++ b/website/docs/api/plugins/plugin-content-pages.md
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 3
 id: plugin-content-pages
 title: '📦 plugin-content-pages'
 slug: '/api/plugins/@docusaurus/plugin-content-pages'
diff --git a/website/docs/api/plugins/plugin-debug.md b/website/docs/api/plugins/plugin-debug.md
index c307099525cc..43f57305b543 100644
--- a/website/docs/api/plugins/plugin-debug.md
+++ b/website/docs/api/plugins/plugin-debug.md
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 5
 id: plugin-debug
 title: '📦 plugin-debug'
 slug: '/api/plugins/@docusaurus/plugin-debug'
diff --git a/website/docs/api/plugins/plugin-google-analytics.md b/website/docs/api/plugins/plugin-google-analytics.md
index 738c5f6e34d4..79764187cfdf 100644
--- a/website/docs/api/plugins/plugin-google-analytics.md
+++ b/website/docs/api/plugins/plugin-google-analytics.md
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 6
 id: plugin-google-analytics
 title: '📦 plugin-google-analytics'
 slug: '/api/plugins/@docusaurus/plugin-google-analytics'
diff --git a/website/docs/api/plugins/plugin-google-gtag.md b/website/docs/api/plugins/plugin-google-gtag.md
index 53b760c36c40..d5487338dd22 100644
--- a/website/docs/api/plugins/plugin-google-gtag.md
+++ b/website/docs/api/plugins/plugin-google-gtag.md
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 7
 id: plugin-google-gtag
 title: '📦 plugin-google-gtag'
 slug: '/api/plugins/@docusaurus/plugin-google-gtag'
diff --git a/website/docs/api/plugins/plugin-ideal-image.md b/website/docs/api/plugins/plugin-ideal-image.md
index 737d4ee417f2..363946e69865 100644
--- a/website/docs/api/plugins/plugin-ideal-image.md
+++ b/website/docs/api/plugins/plugin-ideal-image.md
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 8
 id: plugin-ideal-image
 title: '📦 plugin-ideal-image'
 slug: '/api/plugins/@docusaurus/plugin-ideal-image'
diff --git a/website/docs/api/plugins/plugin-pwa.md b/website/docs/api/plugins/plugin-pwa.md
index 7894d3ec2f54..1a7ab67bbe01 100644
--- a/website/docs/api/plugins/plugin-pwa.md
+++ b/website/docs/api/plugins/plugin-pwa.md
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 9
 id: plugin-pwa
 title: '📦 plugin-pwa'
 slug: '/api/plugins/@docusaurus/plugin-pwa'
diff --git a/website/docs/api/plugins/plugin-sitemap.md b/website/docs/api/plugins/plugin-sitemap.md
index 4631b9fc9dad..5e61a00b7619 100644
--- a/website/docs/api/plugins/plugin-sitemap.md
+++ b/website/docs/api/plugins/plugin-sitemap.md
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 10
 id: plugin-sitemap
 title: '📦 plugin-sitemap'
 slug: '/api/plugins/@docusaurus/plugin-sitemap'
diff --git a/website/docs/api/themes/_category_.yml b/website/docs/api/themes/_category_.yml
new file mode 100644
index 000000000000..a016263a4b9e
--- /dev/null
+++ b/website/docs/api/themes/_category_.yml
@@ -0,0 +1,2 @@
+label: Themes
+position: 3
diff --git a/website/docs/api/themes/overview.md b/website/docs/api/themes/overview.md
index 8a2ee6b50f84..6047040db0d7 100644
--- a/website/docs/api/themes/overview.md
+++ b/website/docs/api/themes/overview.md
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 0
 id: themes-overview
 title: 'Docusaurus themes'
 sidebar_label: Themes overview
diff --git a/website/docs/api/themes/theme-classic.md b/website/docs/api/themes/theme-classic.md
index 3b5a3a764cba..e99a320f135b 100644
--- a/website/docs/api/themes/theme-classic.md
+++ b/website/docs/api/themes/theme-classic.md
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 2
 id: theme-classic
 title: '📦 theme-classic'
 slug: '/api/themes/@docusaurus/theme-classic'
diff --git a/website/docs/api/themes/theme-configuration.md b/website/docs/api/themes/theme-configuration.md
index 637b4a6cd534..d2884b5cfb37 100644
--- a/website/docs/api/themes/theme-configuration.md
+++ b/website/docs/api/themes/theme-configuration.md
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 1
 id: theme-configuration
 title: 'Theme configuration'
 slug: '/api/themes/configuration'
diff --git a/website/docs/api/themes/theme-live-codeblock.md b/website/docs/api/themes/theme-live-codeblock.md
index 568d18d08e35..71e04a33ae09 100644
--- a/website/docs/api/themes/theme-live-codeblock.md
+++ b/website/docs/api/themes/theme-live-codeblock.md
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 3
 id: theme-live-codeblock
 title: '📦 theme-live-codeblock'
 slug: '/api/themes/@docusaurus/theme-live-codeblock'
diff --git a/website/docs/api/themes/theme-search-algolia.md b/website/docs/api/themes/theme-search-algolia.md
index 753d8ca66e6f..e0cee6d8f992 100644
--- a/website/docs/api/themes/theme-search-algolia.md
+++ b/website/docs/api/themes/theme-search-algolia.md
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 4
 id: theme-search-algolia
 title: '📦 theme-search-algolia'
 slug: '/api/themes/@docusaurus/theme-search-algolia'
diff --git a/website/docs/typescript-support.md b/website/docs/typescript-support.md
index 7a8db83a8e4d..e4be4222e0a5 100644
--- a/website/docs/typescript-support.md
+++ b/website/docs/typescript-support.md
@@ -134,4 +134,4 @@ For themes that supports TypeScript theme components, you can add the `--typescr
 npm run swizzle @docusaurus/theme-classic Footer -- --typescript
 ```
 
-At this moment, the only official Docusaurus theme that supports TypeScript theme components is `@docusaurus/theme-classic`. If you are a Docusaurus theme package author who wants to add TypeScript support, see the [Lifecycle APIs docs](./lifecycle-apis.md#gettypescriptthemepath).
+At this moment, the only official Docusaurus theme that supports TypeScript theme components is `@docusaurus/theme-classic`. If you are a Docusaurus theme package author who wants to add TypeScript support, see the [Lifecycle APIs docs](./api/lifecycle-apis.md#gettypescriptthemepath).
diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md
index 308a8c826654..5e597bc95026 100644
--- a/website/docs/using-plugins.md
+++ b/website/docs/using-plugins.md
@@ -121,7 +121,7 @@ Docusaurus' implementation of the plugins system provides us with a convenient w
 
 A plugin is a function that takes two parameters: `context` and `options`.
 
-It returns a plugin instance object, containing plugin [lifecycle APIs](./lifecycle-apis.md).
+It returns a plugin instance object, containing plugin [lifecycle APIs](./api/lifecycle-apis.md).
 
 It can be defined as a function or a module.
 
@@ -206,4 +206,4 @@ interface LoadContext {
 
 #### Return value {#return-value}
 
-The returned object value should implement the [lifecycle APIs](lifecycle-apis.md).
+The returned object value should implement the [lifecycle APIs](./api/lifecycle-apis.md).
diff --git a/website/docs/using-themes.md b/website/docs/using-themes.md
index 772e9da92890..85633ea5513d 100644
--- a/website/docs/using-themes.md
+++ b/website/docs/using-themes.md
@@ -210,13 +210,13 @@ website
 
 There are two lifecycle methods that are essential to theme implementation:
 
-- [`getThemePath()`](lifecycle-apis.md#getthemepath)
-- [`getClientModules()`](lifecycle-apis.md#getclientmodules)
+- [`getThemePath()`](./api/lifecycle-apis.md#getthemepath)
+- [`getClientModules()`](./api/lifecycle-apis.md#getclientmodules)
 
 These lifecycle methods are not essential but recommended:
 
-- [`validateThemeConfig({themeConfig, validate})`](lifecycle-apis.md#validatethemeconfigthemeconfig-validate)
-- [`validateOptions({options, validate})`](lifecycle-apis.md#validateoptionsoptions-validate)
+- [`validateThemeConfig({themeConfig, validate})`](./api/lifecycle-apis.md#validatethemeconfigthemeconfig-validate)
+- [`validateOptions({options, validate})`](./api/lifecycle-apis.md#validateoptionsoptions-validate)
 
 <!--
 
@@ -231,7 +231,7 @@ Related pieces
 ---
 
 - [Advanced Guides – Themes](using-themes.md)
-- [Lifecycle APIs](lifecycle-apis.md)
+- [Lifecycle APIs](./api/lifecycle-apis.md)
 
 References
 ---
diff --git a/website/sidebars.js b/website/sidebars.js
index 549aeace2fe5..387133a62932 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -109,35 +109,9 @@ const sidebars = {
   api: [
     'cli',
     'docusaurus-core',
-    'api/docusaurus.config.js',
-    'lifecycle-apis',
     {
-      type: 'category',
-      label: 'Plugins',
-      items: [
-        'api/plugins/plugins-overview',
-        'api/plugins/plugin-content-docs',
-        'api/plugins/plugin-content-blog',
-        'api/plugins/plugin-content-pages',
-        'api/plugins/plugin-client-redirects',
-        'api/plugins/plugin-debug',
-        'api/plugins/plugin-google-analytics',
-        'api/plugins/plugin-google-gtag',
-        'api/plugins/plugin-ideal-image',
-        'api/plugins/plugin-pwa',
-        'api/plugins/plugin-sitemap',
-      ],
-    },
-    {
-      type: 'category',
-      label: 'Themes',
-      items: [
-        'api/themes/themes-overview',
-        'api/themes/theme-configuration',
-        'api/themes/theme-classic',
-        'api/themes/theme-live-codeblock',
-        'api/themes/theme-search-algolia',
-      ],
+      type: 'autogenerated',
+      dirName: 'api',
     },
   ],
 };

From 7a07963c422992a0de401b375d619561a404c3b6 Mon Sep 17 00:00:00 2001
From: Joshua Chen <sidachen2003@gmail.com>
Date: Wed, 10 Nov 2021 17:36:39 +0800
Subject: [PATCH 14/15] misc(workflow): E2E tests should not be run with
 website changes (#5919)

---
 .github/workflows/tests-e2e.yml | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/tests-e2e.yml b/.github/workflows/tests-e2e.yml
index 0666a2e64a87..550632065b97 100644
--- a/.github/workflows/tests-e2e.yml
+++ b/.github/workflows/tests-e2e.yml
@@ -1,16 +1,20 @@
-name: Tests E2E
+name: E2E Tests
 
 on:
   push:
     branches:
       - main
+    paths-ignore:
+      - website/**
   pull_request:
     branches:
       - main
+    paths-ignore:
+      - website/**
 
 jobs:
   yarn-v1:
-    name: E2E Test with Yarn v1
+    name: E2E — Yarn v1
     timeout-minutes: 30
     runs-on: ubuntu-latest
     strategy:
@@ -43,7 +47,7 @@ jobs:
           CI: true
 
   yarn-berry:
-    name: E2E Test with Yarn Berry
+    name: E2E — Yarn Berry
     timeout-minutes: 30
     runs-on: ubuntu-latest
     strategy:

From ecce576bbc26e55b90c0ebf48db30434c99dcf3e Mon Sep 17 00:00:00 2001
From: Joshua Chen <sidachen2003@gmail.com>
Date: Wed, 10 Nov 2021 18:38:23 +0800
Subject: [PATCH 15/15] docs: new APITable comp to render large tables (#5891)

---
 .../docs/api/plugins/plugin-content-blog.md   | 10 +-
 .../docs/api/plugins/plugin-content-docs.md   | 10 +-
 .../docs/api/plugins/plugin-content-pages.md  |  6 +-
 .../docs/api/themes/theme-configuration.md    | 74 ++++++++-------
 website/src/components/APITable/index.tsx     | 93 +++++++++++++++++++
 .../src/components/APITable/styles.module.css | 22 +++++
 .../api/plugins/plugin-content-blog.md        | 10 +-
 .../api/plugins/plugin-content-docs.md        | 10 +-
 .../api/plugins/plugin-content-pages.md       |  6 +-
 .../api/themes/theme-configuration.md         | 74 ++++++++-------
 .../api/plugins/plugin-content-blog.md        | 10 +-
 .../api/plugins/plugin-content-docs.md        | 10 +-
 .../api/plugins/plugin-content-pages.md       |  6 +-
 .../api/themes/theme-configuration.md         | 74 ++++++++-------
 14 files changed, 277 insertions(+), 138 deletions(-)
 create mode 100644 website/src/components/APITable/index.tsx
 create mode 100644 website/src/components/APITable/styles.module.css

diff --git a/website/docs/api/plugins/plugin-content-blog.md b/website/docs/api/plugins/plugin-content-blog.md
index 4952487a31bc..06d7bdca5b5f 100644
--- a/website/docs/api/plugins/plugin-content-blog.md
+++ b/website/docs/api/plugins/plugin-content-blog.md
@@ -5,6 +5,8 @@ title: '📦 plugin-content-blog'
 slug: '/api/plugins/@docusaurus/plugin-content-blog'
 ---
 
+import APITable from '@site/src/components/APITable';
+
 Provides the [Blog](blog.mdx) feature and is the default blog plugin for Docusaurus.
 
 ## Installation {#installation}
@@ -25,7 +27,7 @@ You can configure this plugin through the [preset options](#ex-config-preset).
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -62,7 +64,7 @@ Accepted fields:
 | `feedOptions.language` | `string` (See [documentation](http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes) for possible values) | `undefined` | Language metadata of the feed. |
 | `sortPosts` | <code>'descending' \| 'ascending' </code> | `'descending'` | Governs the direction of blog post sorting. |
 
-</small>
+</APITable>
 
 ```typescript
 type EditUrlFunction = (params: {
@@ -193,7 +195,7 @@ Markdown documents can use the following Markdown FrontMatter metadata fields, e
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -214,7 +216,7 @@ Accepted fields:
 | `image` | `string` | `undefined` | Cover or thumbnail image that will be used when displaying the link to your post. |
 | `slug` | `string` | File path | Allows to customize the blog post url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-blog-post`, `slug: /my/path/to/blog/post`, slug: `/`. |
 
-</small>
+</APITable>
 
 ```typescript
 type Tag = string | {label: string; permalink: string};
diff --git a/website/docs/api/plugins/plugin-content-docs.md b/website/docs/api/plugins/plugin-content-docs.md
index 8eb28ade59e3..7dd96d96f2bf 100644
--- a/website/docs/api/plugins/plugin-content-docs.md
+++ b/website/docs/api/plugins/plugin-content-docs.md
@@ -5,6 +5,8 @@ title: '📦 plugin-content-docs'
 slug: '/api/plugins/@docusaurus/plugin-content-docs'
 ---
 
+import APITable from '@site/src/components/APITable';
+
 Provides the [Docs](../../guides/docs/docs-introduction.md) functionality and is the default docs plugin for Docusaurus.
 
 ## Installation {#installation}
@@ -25,7 +27,7 @@ You can configure this plugin through the [preset options](#ex-config-preset).
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -58,7 +60,7 @@ Accepted fields:
 | `versions` | `Versions` | `{}` | Independent customization of each version's properties. |
 | `onlyIncludeVersions` | `string[]` | All versions available | Only include a subset of all available versions. <br /> Tip: limit to 2 or 3 versions to improve startup and build time in dev and deploy previews. |
 
-</small>
+</APITable>
 
 ```typescript
 type EditUrlFunction = (params: {
@@ -239,7 +241,7 @@ Markdown documents can use the following Markdown FrontMatter metadata fields, e
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -263,7 +265,7 @@ Accepted fields:
 | `slug` | `string` | File path | Allows to customize the document url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`. |
 | `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your docs. |
 
-</small>
+</APITable>
 
 ```typescript
 type Tag = string | {label: string; permalink: string};
diff --git a/website/docs/api/plugins/plugin-content-pages.md b/website/docs/api/plugins/plugin-content-pages.md
index 2059121458c8..971ab7c92533 100644
--- a/website/docs/api/plugins/plugin-content-pages.md
+++ b/website/docs/api/plugins/plugin-content-pages.md
@@ -5,6 +5,8 @@ title: '📦 plugin-content-pages'
 slug: '/api/plugins/@docusaurus/plugin-content-pages'
 ---
 
+import APITable from '@site/src/components/APITable';
+
 The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. This plugin provides [creating pages](guides/creating-pages.md) functionality.
 
 ## Installation {#installation}
@@ -25,7 +27,7 @@ You can configure this plugin through the [preset options](#ex-config-preset).
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -39,7 +41,7 @@ Accepted fields:
 | `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. |
 | `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. |
 
-</small>
+</APITable>
 
 ## Example configuration {#ex-config}
 
diff --git a/website/docs/api/themes/theme-configuration.md b/website/docs/api/themes/theme-configuration.md
index d2884b5cfb37..efde10ef935b 100644
--- a/website/docs/api/themes/theme-configuration.md
+++ b/website/docs/api/themes/theme-configuration.md
@@ -6,6 +6,8 @@ slug: '/api/themes/configuration'
 toc_max_heading_level: 4
 ---
 
+import APITable from '@site/src/components/APITable';
+
 This configuration applies to all [main themes](./overview.md).
 
 ## Common {#common}
@@ -18,7 +20,7 @@ It is possible to customize the color mode support within the `colorMode` object
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -31,7 +33,7 @@ Accepted fields:
 | `switchConfig.lightIcon` | `string` | `'🌞'` | Icon for the switch while in light mode. |
 | `switchConfig.lightIconStyle` | JSX style object | `{}` | CSS to apply to light icon. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -75,13 +77,13 @@ You can configure a default image that will be used for your meta tag, in partic
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `image` | `string` | `undefined` | The meta image URL for the site. Relative to your site's "static" directory. Cannot be SVGs. Can be external URLs too. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -100,13 +102,13 @@ You can configure additional html metadata (and override existing ones).
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `metadata` | `Metadata[]` | `[]` | Any field will be directly passed to the `<meta />` tag. Possible fields include `id`, `name`, `property`, `content`, `itemprop`, etc. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -125,7 +127,7 @@ Sometimes you want to announce something in your website. Just for such a case,
 
 Accepted fields:
 
-<small>
+<APITable name="announcement-bar">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -135,7 +137,7 @@ Accepted fields:
 | `textColor` | `string` | `'#000'` | Announcement text color. |
 | `isCloseable` | `boolean` | `true` | Whether this announcement can be dismissed with a '×' button. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -160,7 +162,7 @@ module.exports = {
 
 Accepted fields:
 
-<small>
+<APITable name="navbar">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -170,7 +172,7 @@ Accepted fields:
 | `hideOnScroll` | `boolean` | `false` | Whether the navbar is hidden when the user scrolls down. |
 | `style` | <code>'primary' \| 'dark'</code> | Same as theme | Sets the navbar style, ignoring the dark/light theme. |
 
-</small>
+</APITable>
 
 ### Navbar logo {#navbar-logo}
 
@@ -180,7 +182,7 @@ To improve dark mode support, you can also set a different logo for this mode.
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-logo">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -192,7 +194,7 @@ Accepted fields:
 | `height` | <code>string \| number</code> | `undefined` | Specifies the `height` attribute. |
 | `target` | `string` | Calculated based on `href` (external links will open in a new tab, all others in the current one). | The `target` attribute of the link; controls whether the link is opened in a new tab, the current one, or otherwise. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -267,7 +269,7 @@ Outbound (external) links automatically get `target="_blank" rel="noopener noref
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-link">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -281,7 +283,7 @@ Accepted fields:
 | `activeBaseRegex` | `string` | `undefined` | Alternative to `activeBasePath` if required. |
 | `className` | `string` | `''` | Custom CSS class (for styling any item). |
 
-</small>
+</APITable>
 
 :::note
 
@@ -327,7 +329,7 @@ Note that the dropdown base item is a clickable link as well, so this item can r
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-dropdown">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -336,7 +338,7 @@ Accepted fields:
 | `items` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | **Required** | The items to be contained in the dropdown. |
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -376,7 +378,7 @@ If you want to link to a specific doc, this special navbar item type will render
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-doc-link">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -386,7 +388,7 @@ Accepted fields:
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 | `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc belongs to. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -417,7 +419,7 @@ The user will be able to switch from one version to another, while staying on th
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-docs-version-dropdown">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -428,7 +430,7 @@ Accepted fields:
 | `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc versioning belongs to. |
 | `dropdownActiveClassDisabled` | `boolean` | `false` | Do not add the link active class when browsing docs. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -457,7 +459,7 @@ If you use docs with versioning, this special navbar item type will link to the
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-docs-version">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -467,7 +469,7 @@ Accepted fields:
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 | `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc versioning belongs to. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -498,7 +500,7 @@ The user will be able to switch from one locale to another, while staying on the
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-locale-dropdown">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -507,7 +509,7 @@ Accepted fields:
 | `dropdownItemsBefore` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the beginning of the dropdown. |
 | `dropdownItemsAfter` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the end of the dropdown. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -540,14 +542,14 @@ If you use the [search](../../search.md), the search bar will be the rightmost e
 
 However, with this special navbar item type, you can change the default location.
 
-<small>
+<APITable name="navbar-search">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `type` | `'search'` | **Required** | Sets the type of this item to a search bar. |
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 
-</small>
+</APITable>
 
 ```js title="docusaurus.config.js"
 module.exports = {
@@ -604,7 +606,7 @@ Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-r
 
 Accepted fields:
 
-<small>
+<APITable name="codeblock">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -612,7 +614,7 @@ Accepted fields:
 | `darkTheme` | `PrismTheme` | `palenight` | The Prism theme to use for dark-theme code blocks. |
 | `defaultLanguage` | `string` | `undefined` | The side of the navbar this item should appear on. |
 
-</small>
+</APITable>
 
 ### Theme {#theme}
 
@@ -662,7 +664,7 @@ You can add logo and a copyright to the footer via `themeConfig.footer`. Logo ca
 
 Accepted fields:
 
-<small>
+<APITable name="footer">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -671,7 +673,7 @@ Accepted fields:
 | `style` | <code>'dark' \| 'light'</code> | `'light'` | The color theme of the footer component. |
 | `items` | `FooterItem[]` | `[]` | The link groups to be present. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -700,18 +702,18 @@ You can add links to the footer via `themeConfig.footer.links`.
 
 Accepted fields of each link section:
 
-<small>
+<APITable name="footer-links">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `title` | `string` | `undefined` | Label of the section of these links. |
 | `items` | `FooterLink[]` | `[]` | Links in this section. |
 
-</small>
+</APITable>
 
 Accepted fields of each item in `items`:
 
-<small>
+<APITable name="footer-items">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -720,7 +722,7 @@ Accepted fields of each item in `items`:
 | `href` | `string` | **Required** | A full-page navigation, used for navigating outside of the website. **Only one of `to` or `href` should be used.** |
 | `html` | `string` | `undefined` | Renders the html pass-through instead of a simple link. In case `html` is used, no other options should be provided. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -776,14 +778,14 @@ module.exports = {
 
 You can adjust the default table of contents via `themeConfig.tableOfContents`.
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `minHeadingLevel` | `number` | `2` | The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value. |
 | `maxHeadingLevel` | `number` | `3` | Max heading level displayed in the TOC. Should be an integer between 2 and 6. |
 
-</small>
+</APITable>
 
 Example configuration:
 
diff --git a/website/src/components/APITable/index.tsx b/website/src/components/APITable/index.tsx
new file mode 100644
index 000000000000..81cf86731aea
--- /dev/null
+++ b/website/src/components/APITable/index.tsx
@@ -0,0 +1,93 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React, {
+  Children,
+  ComponentProps,
+  ReactElement,
+  ReactNode,
+  isValidElement,
+  useRef,
+  useEffect,
+  forwardRef,
+} from 'react';
+import {useHistory} from '@docusaurus/router';
+import styles from './styles.module.css';
+
+interface Props {
+  readonly children: ReactElement<ComponentProps<'table'>>;
+  readonly name?: string;
+}
+
+// ReactNode equivalent of HTMLElement#innerText
+function getText(node: ReactElement): string {
+  let curNode: ReactNode = node;
+  while (isValidElement(curNode)) {
+    [curNode] = Children.toArray(curNode.props.children);
+  }
+  return curNode as string;
+}
+
+const APITableRow = forwardRef(
+  (
+    {
+      name,
+      children,
+    }: {name: string | undefined; children: ReactElement<ComponentProps<'tr'>>},
+    ref: React.RefObject<HTMLTableRowElement>,
+  ) => {
+    const entryName = getText(children);
+    const anchor = name ? `#${name}-${entryName}` : `#${entryName}`;
+    const history = useHistory();
+    return (
+      <tr
+        id={entryName}
+        tabIndex={0}
+        ref={history.location.hash === anchor ? ref : undefined}
+        onClick={() => {
+          history.push(anchor);
+        }}
+        onKeyDown={(e: React.KeyboardEvent) => {
+          if (e.key === 'Enter') {
+            history.push(anchor);
+          }
+        }}>
+        {children.props.children}
+      </tr>
+    );
+  },
+);
+
+/*
+ * Note: this is not a quite robust component since it makes a lot of
+ * assumptions about how the children looks; however, those assumptions
+ * should be generally correct in the MDX context.
+ */
+export default function APITable({children, name}: Props): JSX.Element {
+  const [thead, tbody] = Children.toArray(
+    children.props.children,
+  ) as ReactElement[];
+  const highlightedRow = useRef<HTMLTableRowElement>(null);
+  useEffect(() => {
+    highlightedRow.current?.focus();
+  }, [highlightedRow]);
+  const rows = Children.map(
+    tbody.props.children,
+    (row: ReactElement<ComponentProps<'tr'>>) => (
+      <APITableRow name={name} ref={highlightedRow}>
+        {row}
+      </APITableRow>
+    ),
+  );
+
+  return (
+    <table className={styles.apiTable}>
+      {thead}
+      <tbody>{rows}</tbody>
+    </table>
+  );
+}
diff --git a/website/src/components/APITable/styles.module.css b/website/src/components/APITable/styles.module.css
new file mode 100644
index 000000000000..1f85c6670549
--- /dev/null
+++ b/website/src/components/APITable/styles.module.css
@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.apiTable {
+  font-size: small;
+}
+
+.apiTable tbody tr {
+  transition: box-shadow 0.2s;
+}
+
+.apiTable tbody tr:focus,
+.apiTable tbody tr:hover {
+  outline: none;
+  box-shadow: 0px 0px 7px 0px inset var(--ifm-color-warning);
+  cursor: pointer;
+  transition: box-shadow 0.2s;
+}
diff --git a/website/versioned_docs/version-2.0.0-beta.8/api/plugins/plugin-content-blog.md b/website/versioned_docs/version-2.0.0-beta.8/api/plugins/plugin-content-blog.md
index f769ab10b3f4..c54bd3164ca4 100644
--- a/website/versioned_docs/version-2.0.0-beta.8/api/plugins/plugin-content-blog.md
+++ b/website/versioned_docs/version-2.0.0-beta.8/api/plugins/plugin-content-blog.md
@@ -4,6 +4,8 @@ title: '📦 plugin-content-blog'
 slug: '/api/plugins/@docusaurus/plugin-content-blog'
 ---
 
+import APITable from '@site/src/components/APITable';
+
 Provides the [Blog](blog.mdx) feature and is the default blog plugin for Docusaurus.
 
 ## Installation {#installation}
@@ -24,7 +26,7 @@ You can configure this plugin through the [preset options](#ex-config-preset).
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -60,7 +62,7 @@ Accepted fields:
 | `feedOptions.copyright` | `string` | `undefined` | Copyright message. |
 | `feedOptions.language` | `string` (See [documentation](http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes) for possible values) | `undefined` | Language metadata of the feed. |
 
-</small>
+</APITable>
 
 ```typescript
 type EditUrlFunction = (params: {
@@ -191,7 +193,7 @@ Markdown documents can use the following Markdown FrontMatter metadata fields, e
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -212,7 +214,7 @@ Accepted fields:
 | `image` | `string` | `undefined` | Cover or thumbnail image that will be used when displaying the link to your post. |
 | `slug` | `string` | File path | Allows to customize the blog post url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-blog-post`, `slug: /my/path/to/blog/post`, slug: `/`. |
 
-</small>
+</APITable>
 
 ```typescript
 type Tag = string | {label: string; permalink: string};
diff --git a/website/versioned_docs/version-2.0.0-beta.8/api/plugins/plugin-content-docs.md b/website/versioned_docs/version-2.0.0-beta.8/api/plugins/plugin-content-docs.md
index ab324d4a096f..3b92343ab507 100644
--- a/website/versioned_docs/version-2.0.0-beta.8/api/plugins/plugin-content-docs.md
+++ b/website/versioned_docs/version-2.0.0-beta.8/api/plugins/plugin-content-docs.md
@@ -4,6 +4,8 @@ title: '📦 plugin-content-docs'
 slug: '/api/plugins/@docusaurus/plugin-content-docs'
 ---
 
+import APITable from '@site/src/components/APITable';
+
 Provides the [Docs](../../guides/docs/docs-introduction.md) functionality and is the default docs plugin for Docusaurus.
 
 ## Installation {#installation}
@@ -24,7 +26,7 @@ You can configure this plugin through the [preset options](#ex-config-preset).
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -57,7 +59,7 @@ Accepted fields:
 | `versions` | `Versions` | `{}` | Independent customization of each version's properties. |
 | `onlyIncludeVersions` | `string[]` | All versions available | Only include a subset of all available versions. <br /> Tip: limit to 2 or 3 versions to improve startup and build time in dev and deploy previews. |
 
-</small>
+</APITable>
 
 ```typescript
 type EditUrlFunction = (params: {
@@ -238,7 +240,7 @@ Markdown documents can use the following Markdown FrontMatter metadata fields, e
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -262,7 +264,7 @@ Accepted fields:
 | `slug` | `string` | File path | Allows to customize the document url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`. |
 | `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your docs. |
 
-</small>
+</APITable>
 
 ```typescript
 type Tag = string | {label: string; permalink: string};
diff --git a/website/versioned_docs/version-2.0.0-beta.8/api/plugins/plugin-content-pages.md b/website/versioned_docs/version-2.0.0-beta.8/api/plugins/plugin-content-pages.md
index 27e3b0c9b9eb..89e30a87789f 100644
--- a/website/versioned_docs/version-2.0.0-beta.8/api/plugins/plugin-content-pages.md
+++ b/website/versioned_docs/version-2.0.0-beta.8/api/plugins/plugin-content-pages.md
@@ -4,6 +4,8 @@ title: '📦 plugin-content-pages'
 slug: '/api/plugins/@docusaurus/plugin-content-pages'
 ---
 
+import APITable from '@site/src/components/APITable';
+
 The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. This plugin provides [creating pages](guides/creating-pages.md) functionality.
 
 ## Installation {#installation}
@@ -24,7 +26,7 @@ You can configure this plugin through the [preset options](#ex-config-preset).
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -38,7 +40,7 @@ Accepted fields:
 | `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. |
 | `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. |
 
-</small>
+</APITable>
 
 ## Example configuration {#ex-config}
 
diff --git a/website/versioned_docs/version-2.0.0-beta.8/api/themes/theme-configuration.md b/website/versioned_docs/version-2.0.0-beta.8/api/themes/theme-configuration.md
index af90e16d4bd1..4bc16ec1a093 100644
--- a/website/versioned_docs/version-2.0.0-beta.8/api/themes/theme-configuration.md
+++ b/website/versioned_docs/version-2.0.0-beta.8/api/themes/theme-configuration.md
@@ -5,6 +5,8 @@ slug: '/api/themes/configuration'
 toc_max_heading_level: 4
 ---
 
+import APITable from '@site/src/components/APITable';
+
 This configuration applies to all [main themes](./overview.md).
 
 ## Common {#common}
@@ -17,7 +19,7 @@ It is possible to customize the color mode support within the `colorMode` object
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -30,7 +32,7 @@ Accepted fields:
 | `switchConfig.lightIcon` | `string` | `'🌞'` | Icon for the switch while in light mode. |
 | `switchConfig.lightIconStyle` | JSX style object | `{}` | CSS to apply to light icon. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -74,13 +76,13 @@ You can configure a default image that will be used for your meta tag, in partic
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `image` | `string` | `undefined` | The meta image URL for the site. Relative to your site's "static" directory. Cannot be SVGs. Can be external URLs too. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -99,13 +101,13 @@ You can configure additional html metadatas (and override existing ones).
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `metadatas` | `Metadata[]` | `[]` | Any field will be directly passed to the `<meta />` tag. Possible fields include `id`, `name`, `property`, `content`, `itemprop`, etc. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -124,7 +126,7 @@ Sometimes you want to announce something in your website. Just for such a case,
 
 Accepted fields:
 
-<small>
+<APITable name="announcement-bar">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -134,7 +136,7 @@ Accepted fields:
 | `textColor` | `string` | `'#000'` | Announcement text color. |
 | `isCloseable` | `boolean` | `true` | Whether this announcement can be dismissed with a '×' button. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -159,7 +161,7 @@ module.exports = {
 
 Accepted fields:
 
-<small>
+<APITable name="navbar">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -169,7 +171,7 @@ Accepted fields:
 | `hideOnScroll` | `boolean` | `false` | Whether the navbar is hidden when the user scrolls down. |
 | `style` | <code>'primary' \| 'dark'</code> | Same as theme | Sets the navbar style, ignoring the dark/light theme. |
 
-</small>
+</APITable>
 
 ### Navbar logo {#navbar-logo}
 
@@ -179,7 +181,7 @@ To improve dark mode support, you can also set a different logo for this mode.
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-logo">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -189,7 +191,7 @@ Accepted fields:
 | `href` | `string` | `siteConfig.baseUrl` | Link to navigate to when the logo is clicked. |
 | `target` | `string` | Calculated based on `href` (external links will open in a new tab, all others in the current one). | The `target` attribute of the link; controls whether the link is opened in a new tab, the current one, or otherwise. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -262,7 +264,7 @@ Outbound (external) links automatically get `target="_blank" rel="noopener noref
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-link">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -276,7 +278,7 @@ Accepted fields:
 | `activeBaseRegex` | `string` | `undefined` | Alternative to `activeBasePath` if required. |
 | `className` | `string` | `''` | Custom CSS class (for styling any item). |
 
-</small>
+</APITable>
 
 :::note
 
@@ -322,7 +324,7 @@ Note that the dropdown base item is a clickable link as well, so this item can r
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-dropdown">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -331,7 +333,7 @@ Accepted fields:
 | `items` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | **Required** | The items to be contained in the dropdown. |
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -371,7 +373,7 @@ If you want to link to a specific doc, this special navbar item type will render
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-doc-link">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -381,7 +383,7 @@ Accepted fields:
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 | `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc belongs to. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -412,7 +414,7 @@ The user will be able to switch from one version to another, while staying on th
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-docs-version-dropdown">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -423,7 +425,7 @@ Accepted fields:
 | `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc versioning belongs to. |
 | `dropdownActiveClassDisabled` | `boolean` | `false` | Do not add the link active class when browsing docs. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -452,7 +454,7 @@ If you use docs with versioning, this special navbar item type will link to the
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-docs-version">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -462,7 +464,7 @@ Accepted fields:
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 | `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc versioning belongs to. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -493,7 +495,7 @@ The user will be able to switch from one locale to another, while staying on the
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-locale-dropdown">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -502,7 +504,7 @@ Accepted fields:
 | `dropdownItemsBefore` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the beginning of the dropdown. |
 | `dropdownItemsAfter` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the end of the dropdown. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -535,14 +537,14 @@ If you use the [search](../../search.md), the search bar will be the rightmost e
 
 However, with this special navbar item type, you can change the default location.
 
-<small>
+<APITable name="navbar-search">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `type` | `'search'` | **Required** | Sets the type of this item to a search bar. |
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 
-</small>
+</APITable>
 
 ```js title="docusaurus.config.js"
 module.exports = {
@@ -599,7 +601,7 @@ Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-r
 
 Accepted fields:
 
-<small>
+<APITable name="codeblock">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -607,7 +609,7 @@ Accepted fields:
 | `darkTheme` | `PrismTheme` | `palenight` | The Prism theme to use for dark-theme code blocks. |
 | `defaultLanguage` | `string` | `undefined` | The side of the navbar this item should appear on. |
 
-</small>
+</APITable>
 
 ### Theme {#theme}
 
@@ -657,7 +659,7 @@ You can add logo and a copyright to the footer via `themeConfig.footer`. Logo ca
 
 Accepted fields:
 
-<small>
+<APITable name="footer">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -666,7 +668,7 @@ Accepted fields:
 | `style` | <code>'dark' \| 'light'</code> | `'light'` | The color theme of the footer component. |
 | `items` | `FooterItem[]` | `[]` | The link groups to be present. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -693,18 +695,18 @@ You can add links to the footer via `themeConfig.footer.links`.
 
 Accepted fields of each link section:
 
-<small>
+<APITable name="footer-links">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `title` | `string` | `undefined` | Label of the section of these links. |
 | `items` | `FooterLink[]` | `[]` | Links in this section. |
 
-</small>
+</APITable>
 
 Accepted fields of each item in `items`:
 
-<small>
+<APITable name="footer-items">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -713,7 +715,7 @@ Accepted fields of each item in `items`:
 | `href` | `string` | **Required** | A full-page navigation, used for navigating outside of the website. **Only one of `to` or `href` should be used.** |
 | `html` | `string` | `undefined` | Renders the html pass-through instead of a simple link. In case `html` is used, no other options should be provided. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -769,14 +771,14 @@ module.exports = {
 
 You can adjust the default table of contents via `themeConfig.tableOfContents`.
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `minHeadingLevel` | `number` | `2` | The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value. |
 | `maxHeadingLevel` | `number` | `3` | Max heading level displayed in the TOC. Should be an integer between 2 and 6. |
 
-</small>
+</APITable>
 
 Example configuration:
 
diff --git a/website/versioned_docs/version-2.0.0-beta.9/api/plugins/plugin-content-blog.md b/website/versioned_docs/version-2.0.0-beta.9/api/plugins/plugin-content-blog.md
index f769ab10b3f4..c54bd3164ca4 100644
--- a/website/versioned_docs/version-2.0.0-beta.9/api/plugins/plugin-content-blog.md
+++ b/website/versioned_docs/version-2.0.0-beta.9/api/plugins/plugin-content-blog.md
@@ -4,6 +4,8 @@ title: '📦 plugin-content-blog'
 slug: '/api/plugins/@docusaurus/plugin-content-blog'
 ---
 
+import APITable from '@site/src/components/APITable';
+
 Provides the [Blog](blog.mdx) feature and is the default blog plugin for Docusaurus.
 
 ## Installation {#installation}
@@ -24,7 +26,7 @@ You can configure this plugin through the [preset options](#ex-config-preset).
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -60,7 +62,7 @@ Accepted fields:
 | `feedOptions.copyright` | `string` | `undefined` | Copyright message. |
 | `feedOptions.language` | `string` (See [documentation](http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes) for possible values) | `undefined` | Language metadata of the feed. |
 
-</small>
+</APITable>
 
 ```typescript
 type EditUrlFunction = (params: {
@@ -191,7 +193,7 @@ Markdown documents can use the following Markdown FrontMatter metadata fields, e
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -212,7 +214,7 @@ Accepted fields:
 | `image` | `string` | `undefined` | Cover or thumbnail image that will be used when displaying the link to your post. |
 | `slug` | `string` | File path | Allows to customize the blog post url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-blog-post`, `slug: /my/path/to/blog/post`, slug: `/`. |
 
-</small>
+</APITable>
 
 ```typescript
 type Tag = string | {label: string; permalink: string};
diff --git a/website/versioned_docs/version-2.0.0-beta.9/api/plugins/plugin-content-docs.md b/website/versioned_docs/version-2.0.0-beta.9/api/plugins/plugin-content-docs.md
index ab324d4a096f..3b92343ab507 100644
--- a/website/versioned_docs/version-2.0.0-beta.9/api/plugins/plugin-content-docs.md
+++ b/website/versioned_docs/version-2.0.0-beta.9/api/plugins/plugin-content-docs.md
@@ -4,6 +4,8 @@ title: '📦 plugin-content-docs'
 slug: '/api/plugins/@docusaurus/plugin-content-docs'
 ---
 
+import APITable from '@site/src/components/APITable';
+
 Provides the [Docs](../../guides/docs/docs-introduction.md) functionality and is the default docs plugin for Docusaurus.
 
 ## Installation {#installation}
@@ -24,7 +26,7 @@ You can configure this plugin through the [preset options](#ex-config-preset).
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -57,7 +59,7 @@ Accepted fields:
 | `versions` | `Versions` | `{}` | Independent customization of each version's properties. |
 | `onlyIncludeVersions` | `string[]` | All versions available | Only include a subset of all available versions. <br /> Tip: limit to 2 or 3 versions to improve startup and build time in dev and deploy previews. |
 
-</small>
+</APITable>
 
 ```typescript
 type EditUrlFunction = (params: {
@@ -238,7 +240,7 @@ Markdown documents can use the following Markdown FrontMatter metadata fields, e
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -262,7 +264,7 @@ Accepted fields:
 | `slug` | `string` | File path | Allows to customize the document url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`. |
 | `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your docs. |
 
-</small>
+</APITable>
 
 ```typescript
 type Tag = string | {label: string; permalink: string};
diff --git a/website/versioned_docs/version-2.0.0-beta.9/api/plugins/plugin-content-pages.md b/website/versioned_docs/version-2.0.0-beta.9/api/plugins/plugin-content-pages.md
index 27e3b0c9b9eb..89e30a87789f 100644
--- a/website/versioned_docs/version-2.0.0-beta.9/api/plugins/plugin-content-pages.md
+++ b/website/versioned_docs/version-2.0.0-beta.9/api/plugins/plugin-content-pages.md
@@ -4,6 +4,8 @@ title: '📦 plugin-content-pages'
 slug: '/api/plugins/@docusaurus/plugin-content-pages'
 ---
 
+import APITable from '@site/src/components/APITable';
+
 The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. This plugin provides [creating pages](guides/creating-pages.md) functionality.
 
 ## Installation {#installation}
@@ -24,7 +26,7 @@ You can configure this plugin through the [preset options](#ex-config-preset).
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -38,7 +40,7 @@ Accepted fields:
 | `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. |
 | `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. |
 
-</small>
+</APITable>
 
 ## Example configuration {#ex-config}
 
diff --git a/website/versioned_docs/version-2.0.0-beta.9/api/themes/theme-configuration.md b/website/versioned_docs/version-2.0.0-beta.9/api/themes/theme-configuration.md
index 4b91fad475e7..013acbabba21 100644
--- a/website/versioned_docs/version-2.0.0-beta.9/api/themes/theme-configuration.md
+++ b/website/versioned_docs/version-2.0.0-beta.9/api/themes/theme-configuration.md
@@ -5,6 +5,8 @@ slug: '/api/themes/configuration'
 toc_max_heading_level: 4
 ---
 
+import APITable from '@site/src/components/APITable';
+
 This configuration applies to all [main themes](./overview.md).
 
 ## Common {#common}
@@ -17,7 +19,7 @@ It is possible to customize the color mode support within the `colorMode` object
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -30,7 +32,7 @@ Accepted fields:
 | `switchConfig.lightIcon` | `string` | `'🌞'` | Icon for the switch while in light mode. |
 | `switchConfig.lightIconStyle` | JSX style object | `{}` | CSS to apply to light icon. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -74,13 +76,13 @@ You can configure a default image that will be used for your meta tag, in partic
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `image` | `string` | `undefined` | The meta image URL for the site. Relative to your site's "static" directory. Cannot be SVGs. Can be external URLs too. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -99,13 +101,13 @@ You can configure additional html metadatas (and override existing ones).
 
 Accepted fields:
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `metadatas` | `Metadata[]` | `[]` | Any field will be directly passed to the `<meta />` tag. Possible fields include `id`, `name`, `property`, `content`, `itemprop`, etc. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -124,7 +126,7 @@ Sometimes you want to announce something in your website. Just for such a case,
 
 Accepted fields:
 
-<small>
+<APITable name="announcement-bar">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -134,7 +136,7 @@ Accepted fields:
 | `textColor` | `string` | `'#000'` | Announcement text color. |
 | `isCloseable` | `boolean` | `true` | Whether this announcement can be dismissed with a '×' button. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -159,7 +161,7 @@ module.exports = {
 
 Accepted fields:
 
-<small>
+<APITable name="navbar">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -169,7 +171,7 @@ Accepted fields:
 | `hideOnScroll` | `boolean` | `false` | Whether the navbar is hidden when the user scrolls down. |
 | `style` | <code>'primary' \| 'dark'</code> | Same as theme | Sets the navbar style, ignoring the dark/light theme. |
 
-</small>
+</APITable>
 
 ### Navbar logo {#navbar-logo}
 
@@ -179,7 +181,7 @@ To improve dark mode support, you can also set a different logo for this mode.
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-logo">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -191,7 +193,7 @@ Accepted fields:
 | `height` | <code>string \| number</code> | `undefined` | Specifies the `height` attribute. |
 | `target` | `string` | Calculated based on `href` (external links will open in a new tab, all others in the current one). | The `target` attribute of the link; controls whether the link is opened in a new tab, the current one, or otherwise. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -266,7 +268,7 @@ Outbound (external) links automatically get `target="_blank" rel="noopener noref
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-link">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -280,7 +282,7 @@ Accepted fields:
 | `activeBaseRegex` | `string` | `undefined` | Alternative to `activeBasePath` if required. |
 | `className` | `string` | `''` | Custom CSS class (for styling any item). |
 
-</small>
+</APITable>
 
 :::note
 
@@ -326,7 +328,7 @@ Note that the dropdown base item is a clickable link as well, so this item can r
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-dropdown">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -335,7 +337,7 @@ Accepted fields:
 | `items` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | **Required** | The items to be contained in the dropdown. |
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -375,7 +377,7 @@ If you want to link to a specific doc, this special navbar item type will render
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-doc-link">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -385,7 +387,7 @@ Accepted fields:
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 | `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc belongs to. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -416,7 +418,7 @@ The user will be able to switch from one version to another, while staying on th
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-docs-version-dropdown">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -427,7 +429,7 @@ Accepted fields:
 | `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc versioning belongs to. |
 | `dropdownActiveClassDisabled` | `boolean` | `false` | Do not add the link active class when browsing docs. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -456,7 +458,7 @@ If you use docs with versioning, this special navbar item type will link to the
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-docs-version">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -466,7 +468,7 @@ Accepted fields:
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 | `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc versioning belongs to. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -497,7 +499,7 @@ The user will be able to switch from one locale to another, while staying on the
 
 Accepted fields:
 
-<small>
+<APITable name="navbar-locale-dropdown">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -506,7 +508,7 @@ Accepted fields:
 | `dropdownItemsBefore` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the beginning of the dropdown. |
 | `dropdownItemsAfter` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the end of the dropdown. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -539,14 +541,14 @@ If you use the [search](../../search.md), the search bar will be the rightmost e
 
 However, with this special navbar item type, you can change the default location.
 
-<small>
+<APITable name="navbar-search">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `type` | `'search'` | **Required** | Sets the type of this item to a search bar. |
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 
-</small>
+</APITable>
 
 ```js title="docusaurus.config.js"
 module.exports = {
@@ -603,7 +605,7 @@ Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-r
 
 Accepted fields:
 
-<small>
+<APITable name="codeblock">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -611,7 +613,7 @@ Accepted fields:
 | `darkTheme` | `PrismTheme` | `palenight` | The Prism theme to use for dark-theme code blocks. |
 | `defaultLanguage` | `string` | `undefined` | The side of the navbar this item should appear on. |
 
-</small>
+</APITable>
 
 ### Theme {#theme}
 
@@ -661,7 +663,7 @@ You can add logo and a copyright to the footer via `themeConfig.footer`. Logo ca
 
 Accepted fields:
 
-<small>
+<APITable name="footer">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -670,7 +672,7 @@ Accepted fields:
 | `style` | <code>'dark' \| 'light'</code> | `'light'` | The color theme of the footer component. |
 | `items` | `FooterItem[]` | `[]` | The link groups to be present. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -699,18 +701,18 @@ You can add links to the footer via `themeConfig.footer.links`.
 
 Accepted fields of each link section:
 
-<small>
+<APITable name="footer-links">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `title` | `string` | `undefined` | Label of the section of these links. |
 | `items` | `FooterLink[]` | `[]` | Links in this section. |
 
-</small>
+</APITable>
 
 Accepted fields of each item in `items`:
 
-<small>
+<APITable name="footer-items">
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -719,7 +721,7 @@ Accepted fields of each item in `items`:
 | `href` | `string` | **Required** | A full-page navigation, used for navigating outside of the website. **Only one of `to` or `href` should be used.** |
 | `html` | `string` | `undefined` | Renders the html pass-through instead of a simple link. In case `html` is used, no other options should be provided. |
 
-</small>
+</APITable>
 
 Example configuration:
 
@@ -775,14 +777,14 @@ module.exports = {
 
 You can adjust the default table of contents via `themeConfig.tableOfContents`.
 
-<small>
+<APITable>
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `minHeadingLevel` | `number` | `2` | The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value. |
 | `maxHeadingLevel` | `number` | `3` | Max heading level displayed in the TOC. Should be an integer between 2 and 6. |
 
-</small>
+</APITable>
 
 Example configuration: