Merge branch 'main' into slorber/defer-poc

.cspell.json

@@ -0,0 +1,36 @@
+{
+  "version": "0.2",
+  "gitignoreRoot": ".",
+  "useGitignore": true,
+  "dictionaries": [
+    "css",
+    "html",
+    "fonts",
+    "typescript",
+    "softwareTerms",
+    "companies",
+    "lorem-ipsum",
+    "project-words"
+  ],
+  "dictionaryDefinitions": [
+    {
+      "name": "project-words",
+      "path": "./project-words.txt",
+      "noSuggest": true
+    }
+  ],
+  "ignorePaths": [
+    "CHANGELOG.md",
+    "examples",
+    "packages/docusaurus-theme-translations/locales",
+    "__tests__",
+    "package.json",
+    "yarn.lock",
+    "project-words.txt",
+    "website/src/data/users.tsx",
+    "*.xyz",
+    "*.docx",
+    "versioned_docs"
+  ],
+  "ignoreRegExpList": ["Email", "Urls", "#[\\w-]*"]
+}

.eslintignore

@@ -6,16 +6,14 @@ build
 coverage
 jest.config.js
 jest.transform.js
-scripts
 examples/
 
 packages/lqip-loader/lib/
 packages/docusaurus/lib/
 packages/docusaurus-*/lib/*
 packages/docusaurus-*/lib-next/
-packages/docusaurus-plugin-pwa/copyUntypedFiles.js
-packages/docusaurus-plugin-ideal-image/copyUntypedFiles.js
-packages/docusaurus-theme-search-algolia/copyUntypedFiles.js
+packages/stylelint-copyright/lib/
+copyUntypedFiles.mjs
 
 packages/create-docusaurus/lib/*
 packages/create-docusaurus/templates/facebook/.eslintrc.js

.eslintrc.js

@@ -29,6 +29,7 @@ module.exports = {
     'plugin:@typescript-eslint/eslint-recommended',
     'plugin:@typescript-eslint/recommended',
     'plugin:react-hooks/recommended',
+    'plugin:jest/recommended',
     'airbnb',
     'prettier',
   ],
@@ -39,7 +40,8 @@ module.exports = {
       },
     },
   },
-  plugins: ['react-hooks', 'header'],
+  reportUnusedDisableDirectives: true,
+  plugins: ['react-hooks', 'header', 'jest'],
   rules: {
     'react-hooks/rules-of-hooks': ERROR,
     'react-hooks/exhaustive-deps': ERROR,
@@ -49,14 +51,7 @@ module.exports = {
     'import/no-unresolved': [
       ERROR,
       {
-        ignore: [
-          '^@theme',
-          '^@docusaurus',
-          '^@generated',
-          '^@site',
-          'unist',
-          'mdast',
-        ],
+        ignore: ['^@theme', '^@docusaurus', '^@generated', '^@site'],
       },
     ],
     'import/extensions': OFF,
@@ -81,9 +76,7 @@ module.exports = {
     'no-param-reassign': [WARNING, {props: false}],
     'no-underscore-dangle': OFF,
     curly: [WARNING, 'all'],
-    'react/jsx-closing-bracket-location': OFF, // Conflicts with Prettier.
     'react/jsx-filename-extension': OFF,
-    'react/jsx-one-expression-per-line': OFF,
     'react/no-array-index-key': OFF, // Sometimes its ok, e.g. non-changing data.
     'react/prop-types': OFF,
     'react/destructuring-assignment': OFF, // Too many lines.
@@ -99,7 +92,10 @@ module.exports = {
     ],
     'react/no-unstable-nested-components': [WARNING, {allowAsProps: true}],
     '@typescript-eslint/no-inferrable-types': OFF,
-    'import/first': OFF,
+    '@typescript-eslint/consistent-type-imports': [
+      WARNING,
+      {disallowTypeAnnotations: false},
+    ],
     'import/order': OFF,
     'import/prefer-default-export': OFF,
     'lines-between-class-members': OFF,
@@ -129,7 +125,7 @@ module.exports = {
     'array-callback-return': WARNING,
     camelcase: WARNING,
     'no-restricted-syntax': WARNING,
-    'no-unused-expressions': WARNING,
+    'no-unused-expressions': [WARNING, {allowTaggedTemplates: true}],
     'global-require': WARNING,
     'prefer-destructuring': WARNING,
     yoda: WARNING,
@@ -149,6 +145,7 @@ module.exports = {
         allowSingleExtends: true,
       },
     ],
+    '@typescript-eslint/method-signature-style': ERROR,
     'no-restricted-imports': [
       ERROR,
       {
@@ -167,15 +164,27 @@ module.exports = {
               'head',
               'tail',
               'initial',
-              'last',
             ],
             message: 'These APIs have their ES counterparts.',
           },
         ],
       },
     ],
+    'jest/prefer-expect-resolves': WARNING,
+    'jest/expect-expect': OFF,
+    'jest/valid-title': OFF,
   },
   overrides: [
+    {
+      files: [
+        'packages/docusaurus-theme-*/src/theme/**/*.js',
+        'packages/docusaurus-theme-*/src/theme/**/*.ts',
+        'packages/docusaurus-theme-*/src/theme/**/*.tsx',
+      ],
+      rules: {
+        'import/no-named-export': ERROR,
+      },
+    },
     {
       files: [
         'packages/create-docusaurus/templates/**/*.js',
@@ -201,7 +210,7 @@ module.exports = {
       },
     },
     {
-      files: ['*.js'],
+      files: ['*.js', '*.mjs', '.cjs'],
       rules: {
         // Make JS code directly runnable in Node.
         '@typescript-eslint/no-var-requires': OFF,

.github/ISSUE_TEMPLATE/bug.yml

@@ -1,6 +1,6 @@
 name: 🐛 Bug Report
 description: Submit a bug report to help us improve
-labels: [bug, needs triage]
+labels: [bug, 'status: needs triage']
 body:
   - type: markdown
     attributes:

.github/ISSUE_TEMPLATE/documentation.yml

@@ -1,6 +1,6 @@
 name: 📚 Documentation
 description: Report an issue related to documentation
-labels: [documentation, needs triage]
+labels: [documentation, 'status: needs triage']
 body:
   - type: markdown
     attributes:

.github/ISSUE_TEMPLATE/feature.yml

@@ -1,6 +1,6 @@
 name: 💅 Feature design / RFC
 description: Submit a detailed feature request with a concrete proposal, including an exhaustive API / UI design
-labels: [feature, needs triage]
+labels: [feature, 'status: needs triage']
 body:
   - type: markdown
     attributes:

.github/ISSUE_TEMPLATE/proposal.yml

@@ -1,6 +1,6 @@
 name: 💥 Proposal
 description: Propose a non-trivial change to Docusaurus
-labels: [proposal, needs triage]
+labels: [proposal, 'status: needs triage']
 body:
   - type: markdown
     attributes:

.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: '/'
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 99
+  - package-ecosystem: npm
+    directory: '/'
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 99

.github/workflows/build-blog-only.yml

@@ -16,6 +16,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v2
         with:
+          node-version: '16'
           cache: yarn
       - name: Installation
         run: yarn

.github/workflows/build-perf.yml

@@ -21,6 +21,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v2
         with:
+          node-version: '16'
           cache: yarn
       - uses: preactjs/compressed-size-action@v2
         with:

.github/workflows/canary-release.yml

@@ -11,17 +11,14 @@ jobs:
   publish-canary:
     name: Publish Canary
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [14.x]
     steps:
       - uses: actions/checkout@v2
         with:
           fetch-depth: 0 # Needed to get the commit number with "git rev-list --count HEAD"
-      - name: Use Node.js ${{ matrix.node-version }}
+      - name: Set up Node
         uses: actions/setup-node@v2
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: '16'
           cache: yarn
       - name: Prepare git
         run: |

.github/workflows/cspell-problem-matcher.json

@@ -0,0 +1,16 @@
+{
+  "problemMatcher": [
+    {
+      "owner": "cspell",
+      "pattern": [
+        {
+          "regexp": "^(.*):(\\d+):(\\d+)\\s+\\-\\s+(.*)$",
+          "file": 1,
+          "line": 2,
+          "column": 3,
+          "message": 4
+        }
+      ]
+    }
+  ]
+}

.github/workflows/lighthouse-report.yml

@@ -19,18 +19,18 @@ jobs:
           max_timeout: 600
       - name: Audit URLs using Lighthouse
         id: lighthouse_audit
-        uses: treosh/lighthouse-ci-action@v3
+        uses: treosh/lighthouse-ci-action@8.2.0
         with:
           urls: |
             https://deploy-preview-$PR_NUMBER--docusaurus-2.netlify.app/
-          configPath: ./.github/workflows/lighthousesrc.json
+          configPath: ./.github/workflows/lighthouserc.json
           uploadArtifacts: true
           temporaryPublicStorage: true
         env:
           PR_NUMBER: ${{ github.event.pull_request.number}}
       - name: Format lighthouse score
         id: format_lighthouse_score
-        uses: actions/github-script@v3
+        uses: actions/github-script@v5
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
@@ -55,7 +55,7 @@ jobs:
 
       - name: Add Lighthouse stats as comment
         id: comment_to_pr
-        uses: marocchino/sticky-pull-request-comment@v2.0.0
+        uses: marocchino/sticky-pull-request-comment@v2.2.0
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           number: ${{ github.event.pull_request.number }}

.github/workflows/lighthouserc.json

@@ -1,5 +1,10 @@
 {
   "ci": {
+    "assert": {
+      "assertions": {
+        "categories:accessibility": ["error", {"minScore": 1}]
+      }
+    },
     "collect": {
       "settings": {
         "skipAudits": [

.github/workflows/lint.yml

@@ -14,6 +14,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v2
         with:
+          node-version: '16'
           cache: yarn
       - name: Installation
         run: yarn
@@ -21,8 +22,8 @@ jobs:
       - name: Check immutable yarn.lock
         run: git diff --exit-code
       - name: Lint
-        run: yarn lint:ci
+        run: |
+          echo "::add-matcher::.github/workflows/cspell-problem-matcher.json"
+          yarn lint:ci
       - name: Prettier Code
-        run: yarn prettier:diff
-      - name: Prettier Docs
-        run: yarn prettier-docs:diff
+        run: yarn format:diff

.github/workflows/showcase-test.yml

@@ -0,0 +1,25 @@
+name: Showcase Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - website/src/data/**
+
+jobs:
+  validate-config:
+    name: Validate Showcase Config
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Node
+        uses: actions/setup-node@v2
+        with:
+          node-version: '16'
+          cache: yarn
+      - name: Installation
+        run: yarn
+      - name: Test
+        run: yarn test website/src/data/__tests__/user.test.ts

.github/workflows/tests-e2e.yml

@@ -30,21 +30,22 @@ jobs:
       - name: Installation
         run: yarn
       - name: Generate test-website project against main branch
-        run: |
-          KEEP_CONTAINER=true yarn test:build:website -s
-          mv test-website ../test-website
+        run: yarn test:build:website -s
+        env:
+          KEEP_CONTAINER: true
       - name: Install test-website project with Yarn v1
-        run: cd ../test-website && yarn install
+        run: yarn install
+        working-directory: ../test-website
         env:
           npm_config_registry: http://localhost:4873
       - name: Start test-website project
-        run: cd ../test-website && yarn start --no-open
+        run: yarn start --no-open
+        working-directory: ../test-website
         env:
           E2E_TEST: true
       - name: Build test-website project
-        run: cd ../test-website && yarn build
-        env:
-          CI: true
+        run: yarn build
+        working-directory: ../test-website
 
   yarn-berry:
     name: E2E — Yarn Berry
@@ -52,45 +53,113 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: ['14']
         nodeLinker: [pnp, node-modules]
     steps:
       - uses: actions/checkout@v2
-      - name: Use Node.js ${{ matrix.node }}
+      - name: Use Node.js 16
         uses: actions/setup-node@v2
         with:
-          node-version: ${{ matrix.node }}
+          node-version: '16'
           cache: yarn
       - name: Installation
         run: yarn
-
       - name: Generate test-website project against main branch
-        run: |
-          KEEP_CONTAINER=true yarn test:build:website -s
-          mv test-website ../test-website
+        run: yarn test:build:website -s
+        env:
+          KEEP_CONTAINER: true
       - name: Install test-website project with Yarn Berry and nodeLinker = ${{ matrix.nodeLinker }}
         run: |
-          cd ../test-website
-
-          # we have to switch to berry first before setting the version we want
           yarn set version berry
-          # temporary using canary for #5342
+          # https://github.com/facebook/docusaurus/pull/6350#issuecomment-1013214763
+          # Remove this after Yarn 3.2
           yarn set version canary
 
           yarn config set nodeLinker ${{ matrix.nodeLinker }}
-          yarn config set pnpMode loose
           yarn config set npmRegistryServer http://localhost:4873
           yarn config set unsafeHttpWhitelist --json '["localhost"]'
           yarn config set enableGlobalCache true
 
+          # Make PnP as strict as possible
+          # https://yarnpkg.com/features/pnp#fallback-mode
+          yarn config set pnpFallbackMode none
+
+          # Patch package so that peer deps are provided. This has been fixed in terser by making acorn a direct dependency
+          # TODO watch out for the next terser release. Commit: https://github.com/terser/terser/commit/05b23eeb682d732484ad51b19bf528258fd5dc2a
+          yarn config set packageExtensions --json '{"terser-webpack-plugin@*": {"dependencies": {"acorn": "^8.6.0"}}, "html-minifier-terser@*": {"dependencies": {"acorn": "^8.6.0"}}}'
+
           yarn install
+        working-directory: ../test-website
         env:
           YARN_ENABLE_IMMUTABLE_INSTALLS: false # Yarn berry should create the lockfile, despite CI env
       - name: Start test-website project
-        run: cd ../test-website && yarn start --no-open
+        run: yarn start --no-open
+        working-directory: ../test-website
         env:
           E2E_TEST: true
       - name: Build test-website project
-        run: cd ../test-website && yarn build
+        run: yarn build
+        working-directory: ../test-website
+
+  npm:
+    name: E2E — NPM
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js 16
+        uses: actions/setup-node@v2
+        with:
+          node-version: '16'
+          cache: yarn
+      - name: Installation
+        run: yarn
+      - name: Generate test-website project against main branch
+        run: yarn test:build:website -s
         env:
-          CI: true
+          KEEP_CONTAINER: true
+      - name: Install test-website project with NPM
+        run: npm install
+        working-directory: ../test-website
+        env:
+          npm_config_registry: http://localhost:4873
+      - name: Start test-website project
+        run: npm run start -- --no-open
+        working-directory: ../test-website
+        env:
+          E2E_TEST: true
+      - name: Build test-website project
+        run: npm run build
+        working-directory: ../test-website
+
+  pnpm:
+    name: E2E — PNPM
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js 16
+        uses: actions/setup-node@v2
+        with:
+          node-version: '16'
+          cache: yarn
+      - name: Installation
+        run: yarn
+      - name: Generate test-website project against main branch
+        run: yarn test:build:website -s
+        env:
+          KEEP_CONTAINER: true
+      - name: Install test-website project with PNPM
+        run: |
+          curl -f https://get.pnpm.io/v6.16.js | node - add --global pnpm
+          pnpm install
+        working-directory: ../test-website
+        env:
+          npm_config_registry: http://localhost:4873
+      - name: Start test-website project
+        run: pnpm run start -- --no-open
+        working-directory: ../test-website
+        env:
+          E2E_TEST: true
+      - name: Build test-website project
+        run: pnpm run build
+        working-directory: ../test-website

.github/workflows/tests-windows.yml

@@ -0,0 +1,38 @@
+name: Windows Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths-ignore:
+      - website/**
+
+jobs:
+  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: Create a deep path
+        # https://github.com/facebook/docusaurus/pull/4899
+        # https://github.com/facebook/docusaurus/issues/5793
+        run: |
+          mkdir -p "website/_dogfooding/_pages tests/deep-file-path-test/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar"
+          cd "$_"
+          echo "# hello" > test-file.md
+      - name: Docusaurus Build
+        run: yarn build:website --locale en

.github/workflows/tests.yml

@@ -27,27 +27,4 @@ jobs:
       - name: Test
         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
+        run: yarn workspace website typecheck

.gitignore

@@ -23,6 +23,7 @@ packages/create-docusaurus/lib/
 packages/lqip-loader/lib/
 packages/docusaurus/lib/
 packages/docusaurus-*/lib/*
+packages/stylelint-copyright/lib/
 packages/docusaurus-*/lib-next/
 
 website/netlifyDeployPreview/*

.nvmrc

@@ -1 +1 @@
-14.16.0
+14.17.0

.prettierignore

@@ -10,10 +10,12 @@ packages/docusaurus-*/lib/*
 packages/docusaurus-*/lib-next/
 packages/create-docusaurus/lib/*
 packages/create-docusaurus/templates/*/docusaurus.config.js
+packages/stylelint-copyright/lib/
 __fixtures__
 
 website/i18n
 website/versions.json
 website/docusaurus.config.js
+website/versioned_sidebars/*.json
 
 examples/

.stylelintignore

@@ -1,2 +1,10 @@
+build
+coverage
+examples/
+
+packages/lqip-loader/lib/
+packages/docusaurus/lib/
+packages/docusaurus-*/lib/*
+packages/docusaurus-*/lib-next/
+packages/create-docusaurus/lib/*
 packages/create-docusaurus/templates/
-examples

.stylelintrc.js

@@ -6,8 +6,31 @@
  */
 
 module.exports = {
+  extends: ['stylelint-config-standard', 'stylelint-config-prettier'],
   plugins: ['stylelint-copyright'],
   rules: {
-    'docusaurus/copyright-header': true,
+    'docusaurus/copyright-header': [
+      true,
+      {
+        header: `*
+ * 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.`,
+      },
+    ],
+    'selector-pseudo-class-no-unknown': [
+      true,
+      {
+        // :global is a CSS modules feature to escape from class name hashing
+        ignorePseudoClasses: ['global'],
+      },
+    ],
+    'selector-class-pattern': null,
+    'custom-property-empty-line-before': null,
+    'selector-id-pattern': null,
+    'declaration-empty-line-before': null,
+    'comment-empty-line-before': null,
+    'value-keyword-case': ['lower', {camelCaseSvgKeywords: true}],
   },
 };

CHANGELOG.md

@@ -1,5 +1,361 @@
 # Docusaurus 2 Changelog
 
+## 2.0.0-beta.14 (2021-12-21)
+
+#### :rocket: New Feature
+
+- `docusaurus-theme-classic`, `docusaurus-theme-common`
+  - [#6132](https://github.com/facebook/docusaurus/pull/6132) feat(theme-classic): new configuration syntax for a simple footer ([@christopherklint97](https://github.com/christopherklint97))
+  - [#6125](https://github.com/facebook/docusaurus/pull/6125) feat(theme-common): stable classname for code blocks ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-theme-classic`
+  - [#5848](https://github.com/facebook/docusaurus/pull/5848) feat(theme-classic): standalone Admonition component ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#6082](https://github.com/facebook/docusaurus/pull/6082) feat(theme-classic): allow passing additional attributes to tab headings ([@Drylozu](https://github.com/Drylozu))
+- `docusaurus-plugin-content-blog`
+  - [#6126](https://github.com/facebook/docusaurus/pull/6126) feat(content-blog): support json feed ([@notzheng](https://github.com/notzheng))
+- `docusaurus`
+  - [#6107](https://github.com/facebook/docusaurus/pull/6107) feat(core): allow plugins to customize/override Webpack devServer config ([@slorber](https://github.com/slorber))
+
+#### :bug: Bug Fix
+
+- `docusaurus-migrate`
+  - [#6146](https://github.com/facebook/docusaurus/pull/6146) fix(migrate): do not modify non-MD files ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-theme-classic`
+  - [#6128](https://github.com/facebook/docusaurus/pull/6128) fix: do not use aria-hidden in heading anchor links ([@lex111](https://github.com/lex111))
+- `docusaurus-plugin-content-docs`
+  - [#6124](https://github.com/facebook/docusaurus/pull/6124) fix(content-docs): restore behavior when pagination front matter is null ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#6085](https://github.com/facebook/docusaurus/pull/6085) fix(content-docs): getMainDocId should return doc with both versioned or unversioned id ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-classic`, `docusaurus-utils-validation`
+  - [#6097](https://github.com/facebook/docusaurus/pull/6097) fix: declare missing dependencies ([@merceyz](https://github.com/merceyz))
+- `docusaurus-plugin-google-analytics`, `docusaurus-plugin-google-gtag`, `docusaurus-plugin-pwa`, `docusaurus-remark-plugin-npm2yarn`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia`, `lqip-loader`
+  - [#6094](https://github.com/facebook/docusaurus/pull/6094) fix: add missing dependencies on tslib ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-theme-translations`
+  - [#6088](https://github.com/facebook/docusaurus/pull/6088) fix(theme-translations): publish theme-translation lib, including typedef ([@slorber](https://github.com/slorber))
+
+#### :nail_care: Polish
+
+- `docusaurus-theme-classic`
+  - [#6053](https://github.com/facebook/docusaurus/pull/6053) feat(theme-classic): allow stylizing doc paginator arrows ([@noomorph](https://github.com/noomorph))
+  - [#6121](https://github.com/facebook/docusaurus/pull/6121) fix(theme-classic): add outline to focused code blocks ([@christopherklint97](https://github.com/christopherklint97))
+  - [#6118](https://github.com/facebook/docusaurus/pull/6118) refactor: remove some useless code ([@lex111](https://github.com/lex111))
+- `create-docusaurus`, `docusaurus-logger`, `docusaurus-mdx-loader`, `docusaurus-migrate`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-theme-search-algolia`, `docusaurus-theme-translations`, `docusaurus-utils-validation`, `docusaurus-utils`, `docusaurus`
+  - [#5994](https://github.com/facebook/docusaurus/pull/5994) refactor: unify log format with new logger utility ([@Josh-Cena](https://github.com/Josh-Cena))
+- `create-docusaurus`
+  - [#6119](https://github.com/facebook/docusaurus/pull/6119) fix(create-docusaurus): make initial editUrl functional ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#6095](https://github.com/facebook/docusaurus/pull/6095) fix(create-docusaurus): give a clearer message when installation failed ([@Josh-Cena](https://github.com/Josh-Cena))
+
+#### :memo: Documentation
+
+- [#6142](https://github.com/facebook/docusaurus/pull/6142) docs: normalize usage of placeholders ([@Josh-Cena](https://github.com/Josh-Cena))
+- [#5918](https://github.com/facebook/docusaurus/pull/5918) docs: refactor & refine lifecycle API docs ([@Josh-Cena](https://github.com/Josh-Cena))
+- [#6138](https://github.com/facebook/docusaurus/pull/6138) docs: add Smart Docs to showcase ([@wowtvds](https://github.com/wowtvds))
+- [#6137](https://github.com/facebook/docusaurus/pull/6137) docs: add ToolJet to showcase ([@withshubh](https://github.com/withshubh))
+- [#6141](https://github.com/facebook/docusaurus/pull/6141) docs: add WoodpeckerCI to showcase ([@6543](https://github.com/6543))
+- [#6135](https://github.com/facebook/docusaurus/pull/6135) docs: mention admonition quirks with Prettier ([@yangshun](https://github.com/yangshun))
+- [#6131](https://github.com/facebook/docusaurus/pull/6131) docs: elaborate on "docs-only" and "blog-only" ([@himanshu007-creator](https://github.com/himanshu007-creator))
+- [#6134](https://github.com/facebook/docusaurus/pull/6134) docs: update link to init template README.md ([@cmpadden](https://github.com/cmpadden))
+- [#6130](https://github.com/facebook/docusaurus/pull/6130) docs: refactor docs sidebar doc ([@Josh-Cena](https://github.com/Josh-Cena))
+- [#6129](https://github.com/facebook/docusaurus/pull/6129) docs: refactor styling/theming docs ([@Josh-Cena](https://github.com/Josh-Cena))
+- [#6112](https://github.com/facebook/docusaurus/pull/6112) docs: mention that SEO through front matter is better than head tag ([@Josh-Cena](https://github.com/Josh-Cena))
+- [#6120](https://github.com/facebook/docusaurus/pull/6120) refactor(website): make deploy preview open next version docs by default ([@Josh-Cena](https://github.com/Josh-Cena))
+- [#6111](https://github.com/facebook/docusaurus/pull/6111) docs: add Molecule website to showcase ([@wewoor](https://github.com/wewoor))
+- [#6089](https://github.com/facebook/docusaurus/pull/6089) docs: add Enarx website to showcase ([@HarshCasper](https://github.com/HarshCasper))
+- [#6090](https://github.com/facebook/docusaurus/pull/6090) docs: add sapphire to showcase ([@favna](https://github.com/favna))
+- [#6091](https://github.com/facebook/docusaurus/pull/6091) docs(showcase): "much more pages" => "many more pages" ([@favna](https://github.com/favna))
+
+#### :house: Internal
+
+- `docusaurus-theme-classic`
+  - [#6144](https://github.com/facebook/docusaurus/pull/6144) fix(theme-classic): fix translation when footer has no links ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-plugin-content-docs`
+  - [#6143](https://github.com/facebook/docusaurus/pull/6143) test: fix async tests resolved in random order ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#6123](https://github.com/facebook/docusaurus/pull/6123) test: use snapshots for sidebar tests ([@Josh-Cena](https://github.com/Josh-Cena))
+- Other
+  - [#6122](https://github.com/facebook/docusaurus/pull/6122) fix(website): fix yarn build:website:fast ([@slorber](https://github.com/slorber))
+  - [#6080](https://github.com/facebook/docusaurus/pull/6080) chore: add NPM and PNPM to E2E tests ([@Josh-Cena](https://github.com/Josh-Cena))
+- `create-docusaurus`, `docusaurus-cssnano-preset`, `docusaurus-mdx-loader`, `docusaurus-migrate`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-debug`, `docusaurus-plugin-google-analytics`, `docusaurus-plugin-google-gtag`, `docusaurus-plugin-ideal-image`, `docusaurus-plugin-pwa`, `docusaurus-plugin-sitemap`, `docusaurus-preset-classic`, `docusaurus-remark-plugin-npm2yarn`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia`, `docusaurus-theme-translations`, `docusaurus-types`, `docusaurus-utils-common`, `docusaurus-utils-validation`, `docusaurus-utils`, `docusaurus`, `lqip-loader`
+  - [#6092](https://github.com/facebook/docusaurus/pull/6092) misc: ignore some files during npm publish ([@Josh-Cena](https://github.com/Josh-Cena))
+
+#### Committers: 17
+
+- 6543 ([@6543](https://github.com/6543))
+- Alexey Pyltsyn ([@lex111](https://github.com/lex111))
+- Christopher Klint ([@christopherklint97](https://github.com/christopherklint97))
+- Harsh Mishra ([@HarshCasper](https://github.com/HarshCasper))
+- Himanshu ([@himanshu007-creator](https://github.com/himanshu007-creator))
+- Jeroen Claassens ([@favna](https://github.com/favna))
+- Joshua Chen ([@Josh-Cena](https://github.com/Josh-Cena))
+- Kristoffer K. ([@merceyz](https://github.com/merceyz))
+- Shubhendra Singh Chauhan ([@withshubh](https://github.com/withshubh))
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+- Wout Vandesompele ([@wowtvds](https://github.com/wowtvds))
+- Yangshun Tay ([@yangshun](https://github.com/yangshun))
+- Yaroslav Serhieiev ([@noomorph](https://github.com/noomorph))
+- Ziv ([@wewoor](https://github.com/wewoor))
+- [@Drylozu](https://github.com/Drylozu)
+- colton ([@cmpadden](https://github.com/cmpadden))
+- 不郑 ([@notzheng](https://github.com/notzheng))
+
+## 2.0.0-beta.13 (2021-12-10)
+
+Good npm publish, same code as beta.11
+
+## 2.0.0-beta.12 (2021-12-10)
+
+Bad npm publish, use beta.13 instead
+
+## 2.0.0-beta.11 (2021-12-10)
+
+#### :bug: Bug Fix
+
+- `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-debug`, `docusaurus-plugin-google-analytics`, `docusaurus-plugin-google-gtag`, `docusaurus-plugin-ideal-image`, `docusaurus-plugin-pwa`, `docusaurus-plugin-sitemap`, `docusaurus-preset-classic`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia`
+  - [#6078](https://github.com/facebook/docusaurus/pull/6078) fix: move docusaurus core back to hard dependencies ([@pranabdas](https://github.com/pranabdas))
+
+#### Committers: 2
+
+- Pranab Das ([@pranabdas](https://github.com/pranabdas))
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+
+## 2.0.0-beta.10 (2021-12-09)
+
+#### :rocket: New Feature
+
+- `create-docusaurus`, `docusaurus-types`, `docusaurus`
+  - [#5930](https://github.com/facebook/docusaurus/pull/5930) feat: shorthands for themes/plugins/presets configuration ([@fsmaia](https://github.com/fsmaia))
+- `docusaurus-mdx-loader`, `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-translations`, `docusaurus-utils`, `docusaurus`
+  - [#5830](https://github.com/facebook/docusaurus/pull/5830) feat(content-docs): sidebar category linking to document or auto-generated index page ([@slorber](https://github.com/slorber))
+- `docusaurus-mdx-loader`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-remark-plugin-npm2yarn`, `docusaurus-types`, `docusaurus`
+  - [#4095](https://github.com/facebook/docusaurus/pull/4095) feat(core): allow sourcing from multiple static directories ([@oriooctopus](https://github.com/oriooctopus))
+- `create-docusaurus`
+  - [#3458](https://github.com/facebook/docusaurus/pull/3458) feat(create-docusaurus): allow using local folder as template ([@afshinm](https://github.com/afshinm))
+- `docusaurus-plugin-content-blog`
+  - [#5787](https://github.com/facebook/docusaurus/pull/5787) feat(content-blog): allow sorting posts in ascending order ([@cerkiewny](https://github.com/cerkiewny))
+- `docusaurus-module-type-aliases`, `docusaurus-theme-classic`, `docusaurus`
+  - [#3104](https://github.com/facebook/docusaurus/pull/3104) feat(core): Add React ErrorBoundary component + theme default boundaries ([@spyke01](https://github.com/spyke01))
+
+#### :boom: Breaking Change
+
+- `docusaurus-plugin-content-blog`
+  - [#6061](https://github.com/facebook/docusaurus/pull/6061) fix(content-blog): make post ID unique ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-migrate`, `docusaurus-plugin-content-docs`
+  - [#6065](https://github.com/facebook/docusaurus/pull/6065) refactor: remove deprecated docs homePageId option ([@lex111](https://github.com/lex111))
+- `docusaurus-plugin-content-docs`
+  - [#6056](https://github.com/facebook/docusaurus/pull/6056) refactor: remove unused metadata field for homepage ([@lex111](https://github.com/lex111))
+- `docusaurus-mdx-loader`, `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-translations`, `docusaurus-utils`, `docusaurus`
+  - [#5830](https://github.com/facebook/docusaurus/pull/5830) feat(content-docs): sidebar category linking to document or auto-generated index page ([@slorber](https://github.com/slorber))
+- `docusaurus-module-type-aliases`, `docusaurus-plugin-google-analytics`, `docusaurus-plugin-google-gtag`, `docusaurus-preset-classic`
+  - [#5832](https://github.com/facebook/docusaurus/pull/5832) refactor(ganalytics, gtag): move options out of themeConfig ([@Josh-Cena](https://github.com/Josh-Cena))
+- `create-docusaurus`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-search-algolia`, `docusaurus-utils`
+  - [#5871](https://github.com/facebook/docusaurus/pull/5871) misc: replace all "Metadatas" with "Metadata" ([@swalahamani](https://github.com/swalahamani))
+
+#### :bug: Bug Fix
+
+- `docusaurus-theme-common`
+  - [#6070](https://github.com/facebook/docusaurus/pull/6070) fix(theme-common): useLocationChange fire un-necessarily twice ([@slorber](https://github.com/slorber))
+  - [#6040](https://github.com/facebook/docusaurus/pull/6040) fix: browser storage (localStorage) is unreliable: api should fail-safe ([@slorber](https://github.com/slorber))
+- `create-docusaurus`, `docusaurus-mdx-loader`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-debug`, `docusaurus-plugin-google-analytics`, `docusaurus-plugin-google-gtag`, `docusaurus-plugin-ideal-image`, `docusaurus-plugin-pwa`, `docusaurus-plugin-sitemap`, `docusaurus-preset-classic`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia`, `docusaurus-theme-translations`, `docusaurus-utils-validation`, `docusaurus-utils`, `docusaurus`
+  - [#6047](https://github.com/facebook/docusaurus/pull/6047) fix: make Docusaurus PnP strict mode compatible ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-theme-classic`, `docusaurus`
+  - [#6052](https://github.com/facebook/docusaurus/pull/6052) fix(core): fix error boundary import disrupting CSS order ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-plugin-content-blog`
+  - [#6061](https://github.com/facebook/docusaurus/pull/6061) fix(content-blog): make post ID unique ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus`
+  - [#5983](https://github.com/facebook/docusaurus/pull/5983) fix(core): do not apply theme-init alias to user component ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#5798](https://github.com/facebook/docusaurus/pull/5798) fix(cli): update notifier should be shown if current is less than latest ([@semoal](https://github.com/semoal))
+  - [#5864](https://github.com/facebook/docusaurus/pull/5864) fix: respect base URL when serving content by webpack dev server ([@lex111](https://github.com/lex111))
+- `docusaurus-module-type-aliases`
+  - [#5945](https://github.com/facebook/docusaurus/pull/5945) fix(module-type-aliases): add svg declaration ([@MisterFISHUP](https://github.com/MisterFISHUP))
+- `docusaurus-theme-classic`
+  - [#5873](https://github.com/facebook/docusaurus/pull/5873) fix(theme-classic): fix announcementBar css ([@slorber](https://github.com/slorber))
+
+#### :nail_care: Polish
+
+- `docusaurus-theme-classic`
+  - [#6003](https://github.com/facebook/docusaurus/pull/6003) fix(theme-classic): make nav dropdowns focusable ([@robinmetral](https://github.com/robinmetral))
+  - [#6000](https://github.com/facebook/docusaurus/pull/6000) fix(theme-classic): make hash link in heading not selectable ([@JararvisQ](https://github.com/JararvisQ))
+  - [#5944](https://github.com/facebook/docusaurus/pull/5944) fix: translate all remaining english sentence in French ([@StanKocken](https://github.com/StanKocken))
+- `docusaurus-theme-classic`, `docusaurus`
+  - [#6048](https://github.com/facebook/docusaurus/pull/6048) refactor: capitalize locales when creating i18n config ([@lex111](https://github.com/lex111))
+- `docusaurus-theme-translations`
+  - [#5976](https://github.com/facebook/docusaurus/pull/5976) feat(theme-translations): add extra Korean translation, fix typo ([@revi](https://github.com/revi))
+  - [#6060](https://github.com/facebook/docusaurus/pull/6060) chore(theme-translations): complete Chinese translations ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-migrate`, `docusaurus-plugin-content-docs`
+  - [#6065](https://github.com/facebook/docusaurus/pull/6065) refactor: remove deprecated docs homePageId option ([@lex111](https://github.com/lex111))
+- `docusaurus-plugin-content-docs`
+  - [#6056](https://github.com/facebook/docusaurus/pull/6056) refactor: remove unused metadata field for homepage ([@lex111](https://github.com/lex111))
+- `docusaurus-theme-classic`, `docusaurus-theme-common`
+  - [#6049](https://github.com/facebook/docusaurus/pull/6049) refactor: simplify Toggle component ([@lex111](https://github.com/lex111))
+- `docusaurus-theme-classic`, `docusaurus-theme-search-algolia`, `docusaurus-theme-translations`, `docusaurus-types`
+  - [#5981](https://github.com/facebook/docusaurus/pull/5981) refactor: minor ESLint improvements ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-plugin-pwa`
+  - [#5995](https://github.com/facebook/docusaurus/pull/5995) chore(plugin-pwa): change core-js version in package.json to v3 ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-plugin-pwa`, `docusaurus-theme-classic`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia`, `docusaurus-theme-translations`, `docusaurus-utils`
+  - [#5849](https://github.com/facebook/docusaurus/pull/5849) refactor: define own translations in other themes ([@lex111](https://github.com/lex111))
+- `docusaurus-plugin-google-analytics`, `docusaurus-plugin-google-gtag`, `docusaurus-types`
+  - [#5959](https://github.com/facebook/docusaurus/pull/5959) refactor(types): correct HtmlTags types ([@armano2](https://github.com/armano2))
+- `docusaurus`
+  - [#5829](https://github.com/facebook/docusaurus/pull/5829) refactor: optimize clone and checkout in deploy command ([@sivapalan](https://github.com/sivapalan))
+  - [#5899](https://github.com/facebook/docusaurus/pull/5899) feat(core): give more hints when plugins have duplicate IDs ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-module-type-aliases`, `docusaurus-plugin-google-analytics`, `docusaurus-plugin-google-gtag`, `docusaurus-preset-classic`
+  - [#5832](https://github.com/facebook/docusaurus/pull/5832) refactor(ganalytics, gtag): move options out of themeConfig ([@Josh-Cena](https://github.com/Josh-Cena))
+- `create-docusaurus`, `docusaurus`
+  - [#5840](https://github.com/facebook/docusaurus/pull/5840) feat: allow GIT_USER env var to be unset if SSH is used ([@wpyoga](https://github.com/wpyoga))
+- `create-docusaurus`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-search-algolia`, `docusaurus-utils`
+  - [#5871](https://github.com/facebook/docusaurus/pull/5871) misc: replace all "Metadatas" with "Metadata" ([@swalahamani](https://github.com/swalahamani))
+
+#### :memo: Documentation
+
+- Other
+  - [#6063](https://github.com/facebook/docusaurus/pull/6063) docs: add moja global to showcase ([@sohamsshah](https://github.com/sohamsshah))
+  - [#6069](https://github.com/facebook/docusaurus/pull/6069) docs: update CONTRIBUTING for website ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#6062](https://github.com/facebook/docusaurus/pull/6062) refactor(website): improve wording in comments of showcase data ([@sohamsshah](https://github.com/sohamsshah))
+  - [#6045](https://github.com/facebook/docusaurus/pull/6045) docs: add "discord resources" to showcase ([@dexbiobot](https://github.com/dexbiobot))
+  - [#6026](https://github.com/facebook/docusaurus/pull/6026) docs(deployment): add cost-benefit analysis with different options ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#5955](https://github.com/facebook/docusaurus/pull/5955) docs: add Pearl UI website to showcase ([@agrawal-rohit](https://github.com/agrawal-rohit))
+  - [#5989](https://github.com/facebook/docusaurus/pull/5989) misc: update CONTRIBUTING to reflect status quo ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#5845](https://github.com/facebook/docusaurus/pull/5845) docs(admin): update repo testing instructions to reflect v2 ([@wpyoga](https://github.com/wpyoga))
+  - [#6019](https://github.com/facebook/docusaurus/pull/6019) docs: update Netlify url config option in deployment instructions ([@rsapkf](https://github.com/rsapkf))
+  - [#6015](https://github.com/facebook/docusaurus/pull/6015) docs: add Tremor website to showcase page ([@skoech](https://github.com/skoech))
+  - [#5997](https://github.com/facebook/docusaurus/pull/5997) refactor(website): various fixes and improvements on Showcase page ([@lex111](https://github.com/lex111))
+  - [#6008](https://github.com/facebook/docusaurus/pull/6008) docs: improve algolia integration instructions ([@shafy](https://github.com/shafy))
+  - [#6006](https://github.com/facebook/docusaurus/pull/6006) docs: improve explanation for url config in GH Pages ([@Martinsos](https://github.com/Martinsos))
+  - [#6001](https://github.com/facebook/docusaurus/pull/6001) docs: add Dime.Scheduler SDK to showcase ([@hbulens](https://github.com/hbulens))
+  - [#5984](https://github.com/facebook/docusaurus/pull/5984) docs: add PREFS website to showcase ([@Patitotective](https://github.com/Patitotective))
+  - [#5967](https://github.com/facebook/docusaurus/pull/5967) docs(website): Add docsearch migration blog post ([@slorber](https://github.com/slorber))
+  - [#5968](https://github.com/facebook/docusaurus/pull/5968) refactor(website): shadow on showcase toggle ([@dsmmcken](https://github.com/dsmmcken))
+  - [#5979](https://github.com/facebook/docusaurus/pull/5979) docs: update links to default translations dir ([@lex111](https://github.com/lex111))
+  - [#5969](https://github.com/facebook/docusaurus/pull/5969) refactor(website): polish on Showcase page ([@slorber](https://github.com/slorber))
+  - [#5966](https://github.com/facebook/docusaurus/pull/5966) docs: add Darklang to showcase ([@pbiggar](https://github.com/pbiggar))
+  - [#5970](https://github.com/facebook/docusaurus/pull/5970) docs: add Remirror to showcase ([@ronnyroeller](https://github.com/ronnyroeller))
+  - [#5971](https://github.com/facebook/docusaurus/pull/5971) docs: add Webiny docs to showcase page ([@swapnilmmane](https://github.com/swapnilmmane))
+  - [#5953](https://github.com/facebook/docusaurus/pull/5953) docs: fix BrowserOnly return statement ([@MorookaKotaro](https://github.com/MorookaKotaro))
+  - [#5949](https://github.com/facebook/docusaurus/pull/5949) docs: update Signoz showcase details ([@pal-sig](https://github.com/pal-sig))
+  - [#5948](https://github.com/facebook/docusaurus/pull/5948) fix(website): fix APITable anchor ID having extra hash ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#5947](https://github.com/facebook/docusaurus/pull/5947) fix(website): fix APITable anchor link ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#5925](https://github.com/facebook/docusaurus/pull/5925) docs: add Froggit site to showcase page ([@cchaudier](https://github.com/cchaudier))
+  - [#5928](https://github.com/facebook/docusaurus/pull/5928) docs: Add Shotstack showcase user ([@jeffski](https://github.com/jeffski))
+  - [#5934](https://github.com/facebook/docusaurus/pull/5934) docs: fix a typo in CHANGELOG ([@KonstHardy](https://github.com/KonstHardy))
+  - [#5921](https://github.com/facebook/docusaurus/pull/5921) docs: add Signoz site to showcase site ([@pal-sig](https://github.com/pal-sig))
+  - [#5891](https://github.com/facebook/docusaurus/pull/5891) docs: new APITable comp to render large tables ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#5917](https://github.com/facebook/docusaurus/pull/5917) docs: make API sidebar partially autogenerated ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#5903](https://github.com/facebook/docusaurus/pull/5903) docs: refer to deployed branch as deployment rather than target ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#5902](https://github.com/facebook/docusaurus/pull/5902) fix(website): fix i18n routes for Canny board ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#5900](https://github.com/facebook/docusaurus/pull/5900) docs: document global variables in MDX scope ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#4409](https://github.com/facebook/docusaurus/pull/4409) docs: add example for Github Pages deployment; rewrite deployment section ([@polarathene](https://github.com/polarathene))
+  - [#5888](https://github.com/facebook/docusaurus/pull/5888) docs: update GitHub deployment instructions ([@rootwork](https://github.com/rootwork))
+  - [#5895](https://github.com/facebook/docusaurus/pull/5895) docs: Add juffalow.com to Docusaurus showcase ([@juffalow](https://github.com/juffalow))
+  - [#5881](https://github.com/facebook/docusaurus/pull/5881) docs: fix wrong code sample in docusaurus-core ([@matthijsgroen](https://github.com/matthijsgroen))
+  - [#5875](https://github.com/facebook/docusaurus/pull/5875) docs: add patrikmasiar website showcase ([@patrikmasiar](https://github.com/patrikmasiar))
+  - [#5876](https://github.com/facebook/docusaurus/pull/5876) docs: '5 minutes tutorial' -> '5-minute tutorial' ([@molly](https://github.com/molly))
+  - [#5759](https://github.com/facebook/docusaurus/pull/5759) docs: create SEO documentation page ([@cerkiewny](https://github.com/cerkiewny))
+  - [#5869](https://github.com/facebook/docusaurus/pull/5869) docs: remove duplicated appId property ([@juzhiyuan](https://github.com/juzhiyuan))
+  - [#5868](https://github.com/facebook/docusaurus/pull/5868) docs: fix a typo in using-themes.md ([@fishmandev](https://github.com/fishmandev))
+  - [#5862](https://github.com/facebook/docusaurus/pull/5862) misc: show only latest archive alpha/beta versions dropdown ([@lex111](https://github.com/lex111))
+- `docusaurus`
+  - [#5742](https://github.com/facebook/docusaurus/pull/5742) feat(website): redesign of showcase page ([@chimailo](https://github.com/chimailo))
+
+#### :house: Internal
+
+- `create-docusaurus`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-ideal-image`, `docusaurus-plugin-pwa`, `docusaurus-theme-common`, `docusaurus-theme-translations`, `docusaurus-utils-validation`, `docusaurus`
+  - [#6071](https://github.com/facebook/docusaurus/pull/6071) refactor: add blank lines below all copyright headers ([@Josh-Cena](https://github.com/Josh-Cena))
+- Other
+  - [#6068](https://github.com/facebook/docusaurus/pull/6068) chore: add prefix to needs triage label; separate Windows test workflow ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#6031](https://github.com/facebook/docusaurus/pull/6031) chore: upgrade netlify-cli ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#6012](https://github.com/facebook/docusaurus/pull/6012) chore(website): enable strict compiler option ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#6002](https://github.com/facebook/docusaurus/pull/6002) chore(ci): add GitHub action for showcase testing ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#5977](https://github.com/facebook/docusaurus/pull/5977) chore: generate dogfooding test for long pathname during CI ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#5950](https://github.com/facebook/docusaurus/pull/5950) misc(codeowners): add @Josh-Cena to CODEOWNERS ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#5919](https://github.com/facebook/docusaurus/pull/5919) misc(workflow): E2E tests should not be run with website changes ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#5907](https://github.com/facebook/docusaurus/pull/5907) chore(workflow): merge jobs into one workflow & give each job a name ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#5889](https://github.com/facebook/docusaurus/pull/5889) chore(website): enable eslint in website ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#5870](https://github.com/facebook/docusaurus/pull/5870) chore(README): fix broken Github Actions Workflow Status icon ([@HemantSachdeva](https://github.com/HemantSachdeva))
+- `docusaurus-module-type-aliases`, `docusaurus-types`, `docusaurus`
+  - [#6064](https://github.com/facebook/docusaurus/pull/6064) refactor(core): fix types for client code ([@Josh-Cena](https://github.com/Josh-Cena))
+- `create-docusaurus`, `docusaurus-mdx-loader`, `docusaurus-migrate`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-ideal-image`, `docusaurus-plugin-pwa`, `docusaurus-plugin-sitemap`, `docusaurus-theme-translations`, `docusaurus-utils`, `docusaurus`
+  - [#6055](https://github.com/facebook/docusaurus/pull/6055) chore: clean up dev dependency declarations ([@Josh-Cena](https://github.com/Josh-Cena))
+- `create-docusaurus`, `docusaurus-plugin-ideal-image`, `docusaurus-theme-classic`
+  - [#6010](https://github.com/facebook/docusaurus/pull/6010) chore: upgrade prettier; rename prettier scripts as format ([@Josh-Cena](https://github.com/Josh-Cena))
+- `create-docusaurus`, `docusaurus`
+  - [#5958](https://github.com/facebook/docusaurus/pull/5958) chore: update @svgr/webpack to version 6 ([@ludofischer](https://github.com/ludofischer))
+- `docusaurus`
+  - [#5998](https://github.com/facebook/docusaurus/pull/5998) chore: upgrade webpack-dev-server to v4.5.0 ([@lex111](https://github.com/lex111))
+  - [#5965](https://github.com/facebook/docusaurus/pull/5965) fix(core): apply staticDirectories to base webpack config ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-mdx-loader`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-debug`, `docusaurus-plugin-ideal-image`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-utils-common`, `docusaurus-utils`, `docusaurus`
+  - [#5985](https://github.com/facebook/docusaurus/pull/5985) chore: cleanup dependency declaration in package.json ([@armano2](https://github.com/armano2))
+- `create-docusaurus`, `docusaurus-migrate`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-debug`, `docusaurus-plugin-google-gtag`, `docusaurus-plugin-sitemap`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia`, `docusaurus-utils`, `docusaurus`, `lqip-loader`, `stylelint-copyright`
+  - [#5963](https://github.com/facebook/docusaurus/pull/5963) chore: upgrade TypeScript & other ESLint related deps ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-plugin-content-docs`
+  - [#5962](https://github.com/facebook/docusaurus/pull/5962) refactor(content-docs): move isCategoriesShorthand to utils ([@armano2](https://github.com/armano2))
+  - [#5906](https://github.com/facebook/docusaurus/pull/5906) fix(content-docs): do not echo git history to console ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#5905](https://github.com/facebook/docusaurus/pull/5905) misc(plugin-docs): fix Windows test snapshot for git history retrieval ([@Josh-Cena](https://github.com/Josh-Cena))
+  - [#5904](https://github.com/facebook/docusaurus/pull/5904) refactor(content-docs): use shelljs instead of execa ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-plugin-ideal-image`
+  - [#5940](https://github.com/facebook/docusaurus/pull/5940) refactor(plugin-ideal-image): migrate package to TS ([@armano2](https://github.com/armano2))
+- `docusaurus-plugin-pwa`, `docusaurus-theme-classic`
+  - [#5941](https://github.com/facebook/docusaurus/pull/5941) refactor(plugin-pwa): migrate package to TS ([@armano2](https://github.com/armano2))
+- `docusaurus-plugin-ideal-image`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-search-algolia`
+  - [#5935](https://github.com/facebook/docusaurus/pull/5935) refactor(theme-search-algolia): migrate package to TS ([@armano2](https://github.com/armano2))
+- `docusaurus-mdx-loader`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`
+  - [#5946](https://github.com/facebook/docusaurus/pull/5946) refactor: move deps declarations into src ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-mdx-loader`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-debug`, `docusaurus-plugin-google-gtag`, `docusaurus-plugin-ideal-image`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-utils-common`, `docusaurus-utils`, `docusaurus`
+  - [#5914](https://github.com/facebook/docusaurus/pull/5914) refactor: improve setup of type declaration files ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-theme-classic`, `docusaurus-theme-common`
+  - [#5922](https://github.com/facebook/docusaurus/pull/5922) refactor(theme-classic): move some logic of CodeBlock to theme-common ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-remark-plugin-npm2yarn`
+  - [#5931](https://github.com/facebook/docusaurus/pull/5931) refactor(remark-plugin-npm2yarn): migrate package to TS ([@duanwilliam](https://github.com/duanwilliam))
+- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-utils`
+  - [#5806](https://github.com/facebook/docusaurus/pull/5806) refactor: use js-yaml to parse both JSON and YAML ([@Josh-Cena](https://github.com/Josh-Cena))
+
+#### Committers: 48
+
+- Afshin Mehrabani ([@afshinm](https://github.com/afshinm))
+- Alexey Pyltsyn ([@lex111](https://github.com/lex111))
+- Armano ([@armano2](https://github.com/armano2))
+- Brennan Kinney ([@polarathene](https://github.com/polarathene))
+- Can Olcer ([@shafy](https://github.com/shafy))
+- Christophe Chaudier ([@cchaudier](https://github.com/cchaudier))
+- Devtato ([@cerkiewny](https://github.com/cerkiewny))
+- Dmitriy Fishman ([@fishmandev](https://github.com/fishmandev))
+- Don ([@dsmmcken](https://github.com/dsmmcken))
+- FISH UP ([@MisterFISHUP](https://github.com/MisterFISHUP))
+- Fernando Maia ([@fsmaia](https://github.com/fsmaia))
+- Hemant Sachdeva ([@HemantSachdeva](https://github.com/HemantSachdeva))
+- Hendrik Bulens ([@hbulens](https://github.com/hbulens))
+- Ivan Boothe ([@rootwork](https://github.com/rootwork))
+- Jarar ([@JararvisQ](https://github.com/JararvisQ))
+- Jeff Shillitto ([@jeffski](https://github.com/jeffski))
+- Joshua Chen ([@Josh-Cena](https://github.com/Josh-Cena))
+- Konstantin Popov ([@KonstHardy](https://github.com/KonstHardy))
+- Ludovico Fischer ([@ludofischer](https://github.com/ludofischer))
+- Martin Šošić ([@Martinsos](https://github.com/Martinsos))
+- Matej Jellus ([@juffalow](https://github.com/juffalow))
+- Matthijs Groen ([@matthijsgroen](https://github.com/matthijsgroen))
+- Molly White ([@molly](https://github.com/molly))
+- Morooka Kotaro ([@MorookaKotaro](https://github.com/MorookaKotaro))
+- Oliver Ullman ([@oriooctopus](https://github.com/oriooctopus))
+- Paden Clayton ([@spyke01](https://github.com/spyke01))
+- Patitotective ([@Patitotective](https://github.com/Patitotective))
+- Patrik Mäsiar ([@patrikmasiar](https://github.com/patrikmasiar))
+- Paul Biggar ([@pbiggar](https://github.com/pbiggar))
+- Rey ([@rsapkf](https://github.com/rsapkf))
+- Robin Métral ([@robinmetral](https://github.com/robinmetral))
+- Rohit Agrawal ([@agrawal-rohit](https://github.com/agrawal-rohit))
+- Ronny Roeller ([@ronnyroeller](https://github.com/ronnyroeller))
+- Sergio Moreno ([@semoal](https://github.com/semoal))
+- Sharon Koech ([@skoech](https://github.com/skoech))
+- Shoaib Sajid ([@dexbiobot](https://github.com/dexbiobot))
+- Soham Shah ([@sohamsshah](https://github.com/sohamsshah))
+- Stan Kocken ([@StanKocken](https://github.com/StanKocken))
+- Swalah Amani ([@swalahamani](https://github.com/swalahamani))
+- Swapnil M Mane ([@swapnilmmane](https://github.com/swapnilmmane))
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+- Varun Sivapalan ([@sivapalan](https://github.com/sivapalan))
+- William Poetra Yoga ([@wpyoga](https://github.com/wpyoga))
+- Yongmin Hong ([@revi](https://github.com/revi))
+- [@duanwilliam](https://github.com/duanwilliam)
+- [@pal-sig](https://github.com/pal-sig)
+- chima ilo ([@chimailo](https://github.com/chimailo))
+- 琚致远 ([@juzhiyuan](https://github.com/juzhiyuan))
+
 ## 2.0.0-beta.9 (2021-11-02)
 
 #### :rocket: New Feature
@@ -1928,7 +2284,7 @@ Starting with this release for a proper work of i18n functionality, you need to
 - [@wolf20482](https://github.com/wolf20482)
 - moonrailgun ([@moonrailgun](https://github.com/moonrailgun))
 - Çağlar Turalı ([@caglarturali](https://github.com/caglarturali))
-- 琚致远 ([@juzhiyuan](https://github.com/juzhiyuan)) ✨ Done in 15.23s.
+- 琚致远 ([@juzhiyuan](https://github.com/juzhiyuan))
 
 ## 2.0.0-alpha.70 (2020-12-17)
 
@@ -2792,7 +3148,7 @@ Failed release
 - Méril ([@mpsq](https://github.com/mpsq))
 - Sébastien Lorber ([@slorber](https://github.com/slorber))
 - Teik Jun ([@teikjun](https://github.com/teikjun))
-- Xuqian ([@zxuqian](https://github.com/zxuqian)) ✨ Done in 3.58s.
+- Xuqian ([@zxuqian](https://github.com/zxuqian))
 
 ## 2.0.0-alpha.60 (2020-07-29)
 

CONTRIBUTING.md

@@ -18,25 +18,14 @@ There are many ways to contribute to Docusaurus, and many of them do not involve
 - Simply start using Docusaurus. Go through the [Getting Started](https://docusaurus.io/docs/installation) guide. Does everything work as expected? If not, we're always looking for improvements. Let us know by [opening an issue](#reporting-new-issues).
 - Look through the [open issues](https://github.com/facebook/docusaurus/issues). Provide workarounds, ask for clarification, or suggest labels. Help [triage issues](#triaging-issues-and-pull-requests).
 - If you find an issue you would like to fix, [open a pull request](#your-first-pull-request). Issues tagged as [_Good first issue_](https://github.com/facebook/docusaurus/labels/Good%20first%20issue) are a good place to get started.
-- Read through the [Docusaurus docs](https://docusaurus.io/docs/installation). If you find anything that is confusing or can be improved, you can make edits by clicking "Edit" at the top of most docs.
-- Take a look at the [features requested](https://github.com/facebook/docusaurus/labels/enhancement) by others in the community and consider opening a pull request if you see something you want to work on.
+- Read through the [Docusaurus docs](https://docusaurus.io/docs/installation). If you find anything that is confusing or can be improved, you can click "Edit this page" at the bottom of most docs, which takes you to the GitHub interface to make and propose changes.
+- Take a look at the [features requested](https://github.com/facebook/docusaurus/labels/feature) by others in the community and consider opening a pull request if you see something you want to work on.
 
 Contributions are very welcome. If you think you need help planning your contribution, please ping us on Twitter at [@docusaurus](https://twitter.com/docusaurus) and let us know you are looking for a bit of help.
 
-### Versioned Docs
-
-If you only want to make content changes you just need to know about versioned docs.
-
-- `website/docs` - The files in here are responsible for the "next" version at https://docusaurus.io/docs/next/installation.
-- `website/versioned_docs/version-X.Y.Z` - These are the docs for the X.Y.Z version at https://docusaurus.io/docs/X.Y.Z/installation.
-
-To make a fix to the published versions you must edit the corresponding markdown file in both folders. If you only made changes in `docs`, be sure to be viewing the `next` version to see the updates (ensure there's `next` in the URL).
-
-> Do not edit the auto-generated files within `versioned_docs/` or `versioned_sidebars/` unless you are sure it is necessary. For example, information about new features should not be documented in versioned docs. Edits made to older versions will not be propagated to newer versions of the docs.
-
 ### Join our Discord Channel
 
-We have the [`#contributors`](https://discord.gg/6g6ASPA) channel on [Discord](https://discord.gg/docusaurus) to discuss all things about Docusaurus development.
+We have the [`#contributors`](https://discord.gg/6g6ASPA) channel on [Discord](https://discord.gg/docusaurus) to discuss all things about Docusaurus development. You can also be of great help by helping other users in the help channel.
 
 ### Triaging Issues and Pull Requests
 
@@ -51,51 +40,42 @@ One great way you can contribute to the project without writing any code is to h
 
 Docusaurus uses [GitHub](https://github.com/facebook/docusaurus) as its source of truth. The core team will be working directly there. All changes will be public from the beginning.
 
-When a change made on GitHub is approved, it will be checked by our continuous integration system, CircleCI.
+All pull requests will be checked by the continuous integration system, GitHub actions. There are unit tests, end-to-end tests, performance tests, style tests, and much more.
 
 ### Branch Organization
 
 Docusaurus has one primary branch `main` and we use feature branches with deploy previews to deliver new features with pull requests.
 
-## Bugs
+## Proposing a Change
 
-We use [GitHub Issues](https://github.com/facebook/docusaurus/issues) for our public bugs. If you would like to report a problem, take a look around and see if someone already opened an issue about it. If you are certain this is a new, unreported bug, you can submit a [bug report](#reporting-new-issues).
+If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can also file an issue with the [feature template](https://github.com/facebook/docusaurus/issues/new?assignees=&labels=feature%2Cneeds+triage&template=feature.yml).
 
-If you have questions about using Docusaurus, contact the Docusaurus Twitter account at [@docusaurus](https://twitter.com/docusaurus), and we will do our best to answer your questions.
+If you intend to change the public API (e.g., something in `siteConfig.js`) or make any non-trivial changes to the implementation, we recommend filing an issue with the [proposal template](https://github.com/facebook/docusaurus/issues/new?assignees=&labels=proposal%2Cneeds+triage&template=proposal.yml). This lets us reach an agreement on your proposal before you put significant effort into it. These types of issues should be rare.
 
-You can also file issues as [feature requests or enhancements](https://github.com/facebook/docusaurus/labels/feature%20request). If you see anything you'd like to be implemented, create an issue with [feature template](https://raw.githubusercontent.com/facebook/docusaurus/main/.github/ISSUE_TEMPLATE/feature.md)
+If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend [filing an issue](https://github.com/facebook/docusaurus/issues/new?assignees=&labels=bug%2Cneeds+triage&template=bug.yml) detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue.
 
-## Reporting New Issues
+### Reporting New Issues
 
-When [opening a new issue](https://github.com/facebook/docusaurus/issues/new/choose), always make sure to fill out the issue template. **This step is very important!** Not doing so may result in your issue not managed in a timely fashion. Don't take this personally if this happens, and feel free to open a new issue once you've gathered all the information required by the template.
+When [opening a new issue](https://github.com/facebook/docusaurus/issues/new/choose), always make sure to fill out the issue template. **This step is very important!** Not doing so may result in your issue not being managed in a timely fashion. Don't take this personally if this happens, and feel free to open a new issue once you've gathered all the information required by the template.
 
 - **One issue, one bug:** Please report a single bug per issue.
 - **Provide reproduction steps:** List all the steps necessary to reproduce the issue. The person reading your bug report should be able to follow these steps to reproduce your issue with minimal effort.
 
+### Bugs
+
+We use [GitHub Issues](https://github.com/facebook/docusaurus/issues) for our public bugs. If you would like to report a problem, take a look around and see if someone already opened an issue about it. If you are certain this is a new, unreported bug, you can submit a [bug report](#reporting-new-issues).
+
 ### Security Bugs
 
 Facebook has a [bounty program](https://www.facebook.com/whitehat/) for the safe disclosure of security bugs. With that in mind, please do not file public issues; go through the process outlined on that page.
 
-## Installation
+### Feature requests
 
-1. Ensure you have [Yarn](https://yarnpkg.com/) installed.
-1. After cloning the repository, run `yarn install` in the root of the repository.
-1. To start a development server:
+You can also file issues as [feature requests or enhancements](https://github.com/facebook/docusaurus/labels/feature%20request) in the form of an **elaborated RFC**. If you see anything you'd like to be implemented, create an issue with [feature template](https://raw.githubusercontent.com/facebook/docusaurus/main/.github/ISSUE_TEMPLATE/feature.md)
 
-   - For Docusaurus 1 development, run `yarn start:v1`
-   - For Docusaurus 2 development, run `yarn start`
+### Questions
 
-## Online one-click setup for contributing
-
-You can use Gitpod (a free, online, VS Code-like IDE) for contributing. With a single click it will launch a workspace (for Docusaurus 2) and automatically:
-
-- clone the docusaurus repo.
-- install the dependencies.
-- run `yarn run start`
-
-So that you can start contributing straight away.
-
-[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/facebook/docusaurus)
+If you have questions about using Docusaurus, contact the Docusaurus Twitter account at [@docusaurus](https://twitter.com/docusaurus), and we will do our best to answer your questions.
 
 ## Pull Requests
 
@@ -107,15 +87,38 @@ Working on your first Pull Request? You can learn how from this free video serie
 
 [**How to Contribute to an Open Source Project on GitHub**](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github)
 
-We have a list of [beginner friendly issues](https://github.com/facebook/docusaurus/labels/good%20first%20issue) to help you get your feet wet in the Docusaurus codebase and familiar with our contribution process. This is a great place to get started.
+We have a list of [beginner-friendly issues](https://github.com/facebook/docusaurus/labels/good%20first%20issue) to help you get your feet wet in the Docusaurus codebase and familiar with our contribution process. This is a great place to get started.
 
-### Proposing a Change
+### Versioned Docs
 
-If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can also file an issue with the [feature template](https://github.com/facebook/docusaurus/issues/new?template=feature.md).
+If you only want to make content changes you just need to be aware of versioned docs.
 
-If you intend to change the public API (e.g., something in `siteConfig.js`) or make any non-trivial changes to the implementation, we recommend filing an issue with the [proposal template](https://github.com/facebook/docusaurus/issues/new?template=proposal.md) and including `[Proposal]` in the title. This lets us reach an agreement on your proposal before you put significant effort into it. These types of issues should be rare.
+- `website/docs` - The files here are responsible for the "next" version at https://docusaurus.io/docs/next/installation.
+- `website/versioned_docs/version-X.Y.Z` - These are the docs for the X.Y.Z version at https://docusaurus.io/docs/X.Y.Z/installation.
 
-If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend filing an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue.
+To make a fix to the published versions you must edit the corresponding markdown file in both folders. If you only made changes in `docs`, be sure to be viewing the `next` version to see the updates (ensure there's `next` in the URL).
+
+> Do not edit the auto-generated files within `versioned_docs/` or `versioned_sidebars/` unless you are sure it is necessary. For example, information about new features should not be documented in versioned docs. Edits made to older versions will not be propagated to newer versions of the docs.
+
+### Installation
+
+1. Ensure you have [Yarn](https://yarnpkg.com/) installed.
+1. After cloning the repository, run `yarn install` in the root of the repository.
+1. To start a development server, run `yarn workspace website start`.
+
+### Online one-click setup for contributing
+
+You can use Gitpod (a free, online, VS Code-like IDE) for contributing. With a single click, it will launch a workspace (for Docusaurus 2) and automatically:
+
+- clone the docusaurus repo.
+- install the dependencies.
+- run `yarn start`
+
+So that you can start contributing straight away.
+
+[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/facebook/docusaurus)
+
+You can also try using the new [github.dev](https://github.dev/facebook/docusaurus) feature. While you are browsing any file, changing the domain name from `github.com` to `github.dev` will turn your browser into an online editor. You can start making changes and send pull requests right away.
 
 ### Sending a Pull Request
 
@@ -124,7 +127,7 @@ Small pull requests are much easier to review and more likely to get merged. Mak
 Please make sure the following is done when submitting a pull request:
 
 1. Fork [the repository](https://github.com/facebook/docusaurus) and create your branch from `main`.
-1. Add the copyright notice to the top of any code new files you've added.
+1. Add the [copyright notice](#copyright-header-for-source-code) to the top of any code new files you've added.
 1. Describe your [**test plan**](#test-plan) in your pull request description. Make sure to [test your changes](https://github.com/facebook/docusaurus/blob/main/admin/testing-changes-on-Docusaurus-itself.md)!
 1. Make sure your code lints (`yarn prettier && yarn lint`).
 1. Make sure your Jest tests pass (`yarn test`).
@@ -134,11 +137,9 @@ All pull requests should be opened against the `main` branch.
 
 #### Test Plan
 
-A good test plan has the exact commands you ran and their output, provides screenshots or videos if the pull request changes UI.
+A good test plan has the exact commands you ran and their output and provides screenshots or videos if the pull request changes UI. If you've changed APIs, update the documentation.
 
-- If you've changed APIs, update the documentation.
-
-If you need help testing your changes locally, you can check out the doc on doing [local third party testing](./admin/local-third-party-project-testing.md).
+If you need help testing your changes locally, you can check out the doc on doing [local third-party testing](https://github.com/facebook/docusaurus/blob/main/admin/local-third-party-project-testing.md).
 
 #### Breaking Changes
 
@@ -170,6 +171,12 @@ Copy and paste this to the top of your new file(s):
 
 In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you've done this for another Facebook open source project, you're good to go. If you are submitting a pull request for the first time, the Facebook GitHub Bot will reply with a link to the CLA form. You may also [complete your CLA here](https://code.facebook.com/cla).
 
+After you have signed the CLA, the CLA bot would automatically update the PR status. There's no need to open a new PR.
+
+**CLAs are required for us to merge your pull request.** While we value your effort and are willing to wait for you to come back and address the reviews in case you are unavailable after sending the pull request, pull requests that are ready to merge but have CLA missing and no response from the author **will be closed within two weeks of opening**. If you have further questions about the CLA, please stay in touch with us.
+
+If it happens that you were unavailable and your PR gets closed, feel free to reopen once it's ready! We are still happy to review it, help you complete it, and eventually merge it.
+
 ### What Happens Next?
 
 The core Docusaurus team will be monitoring for pull requests. Do help us by keeping pull requests consistent by following the guidelines above.
@@ -186,37 +193,42 @@ See how a minor change to your commit message style can make you a better progra
 
 Format: `<type>(<scope>): <subject>`
 
-`<scope>` is optional
-
-## Example
-
-```
-feat: allow overriding of webpack config
-^--^  ^------------^
-|     |
-|     +-> Summary in present tense.
-|
-+-------> Type: chore, docs, feat, fix, refactor, style, or test.
-```
+`<scope>` is optional. If your change is specific to one/two packages, consider adding the scope. Scopes should be brief but recognizable, e.g. `content-docs`, `theme-classic`, `core`
 
 The various types of commits:
 
-- `feat`: (new feature for the user, not a new feature for build script)
-- `fix`: (bug fix for the user, not a fix to a build script)
-- `docs`: (changes to the documentation)
-- `style`: (formatting, missing semicolons, etc; no production code change)
-- `refactor`: (refactoring production code, eg. renaming a variable)
-- `test`: (adding missing tests, refactoring tests; no production code change)
-- `chore`: (updating grunt tasks etc; no production code change)
+- `feat`: a new API or behavior **for the end user**.
+- `fix`: a bug fix **for the end user**.
+- `docs`: a change to the website or other Markdown documents in our repo.
+- `refactor`: a change to production code that leads to no behavior difference, e.g. splitting files, renaming internal variables, improving code style...
+- `test`: adding missing tests, refactoring tests; no production code change.
+- `chore`: upgrading dependencies, releasing new versions... Chores that are **regularly done** for maintenance purposes.
+- `misc`: anything else that doesn't change production code, yet is not `test` or `chore`. e.g. updating GitHub actions workflow.
+
+Do not get too stressed about PR titles, however. The maintainers will help you get them right, and we also have a PR label system that doesn't equate with the commit message types. Your code is more important than conventions!
+
+### Example
+
+```
+feat(core): allow overriding of webpack config
+^--^^----^  ^------------^
+|   |       |
+|   |       +-> Summary in present tense.
+|   |
+|   +-> The package(s) that this change affected.
+|
++-------> Type: see below for the list we use.
+```
 
 Use lower case not title case!
 
-### Code Conventions
+## Code Conventions
 
-#### General
+### General
 
-- **Most important: Look around.** Match the style you see used in the rest of the project. This includes formatting, naming files, naming things in code, naming things in documentation.
+- **Most important: Look around.** Match the style you see used in the rest of the project. This includes formatting, naming files, naming things in code, naming things in documentation, etc.
 - "Attractive"
+- We do have Prettier (a formatter) and ESLint (a syntax linter) to catch most stylistic problems. If you are working locally, they should automatically fix some issues during every git commit.
 
 ### Documentation
 

__tests__/validate-package-json.test.ts

@@ -38,15 +38,15 @@ describe('packages', () => {
   test('should contain repository and directory for every package', async () => {
     const packageJsonFiles = await getPackagesJsonFiles();
 
-    packageJsonFiles.forEach((packageJsonFile) => {
-      if (packageJsonFile.content.private !== true) {
+    packageJsonFiles
+      .filter((packageJsonFile) => !packageJsonFile.content.private)
+      .forEach((packageJsonFile) => {
         expect(packageJsonFile.content.repository).toEqual({
           type: 'git',
           url: 'https://github.com/facebook/docusaurus.git',
           directory: packageJsonFile.file.replace(/\/package\.json$/, ''),
         });
-      }
-    });
+      });
   });
 
   /*
@@ -58,17 +58,19 @@ describe('packages', () => {
   test('should have publishConfig.access: "public" when name starts with @', async () => {
     const packageJsonFiles = await getPackagesJsonFiles();
 
-    packageJsonFiles.forEach((packageJsonFile) => {
-      if (packageJsonFile.content.name.startsWith('@')) {
-        // Unfortunately jest custom message do not exist in loops, so using an exception instead to show failing package file
-        // (see https://github.com/facebook/jest/issues/3293)
-        // expect(packageJsonFile.content.publishConfig?.access).toEqual('public');
-        if (packageJsonFile.content.publishConfig?.access !== 'public') {
-          throw new Error(
-            `Package ${packageJsonFile.file} does not have publishConfig.access: 'public'`,
-          );
+    packageJsonFiles
+      .filter((packageJsonFile) => packageJsonFile.content.name.startsWith('@'))
+      .forEach((packageJsonFile) => {
+        if (packageJsonFile) {
+          // Unfortunately jest custom message do not exist in loops, so using an exception instead to show failing package file
+          // (see https://github.com/facebook/jest/issues/3293)
+          // expect(packageJsonFile.content.publishConfig?.access).toEqual('public');
+          if (packageJsonFile.content.publishConfig?.access !== 'public') {
+            throw new Error(
+              `Package ${packageJsonFile.file} does not have publishConfig.access: 'public'`,
+            );
+          }
         }
-      }
-    });
+      });
   });
 });

admin/extending-remarkable.md

@@ -1,140 +0,0 @@
-Docusaurus uses [Remarkable](https://github.com/jonschlinkert/remarkable) to convert plain markdown text into HTML. This document covers how one may extend Remarkable to provide custom functionality. While the document focuses on extending Remarkable in implementation, the theory should apply in general to any markdown parser.
-
-## Why extend Remarkable?
-
-Users of GitHub Pages have come to expect certain features provided by GitHub Flavored Markdown. One such example would be heading anchors, where every sub-header has an associated anchor that matches the heading text. This makes it possible to link to a specific section in a document by passing a fragment that matches the heading. For example, to link to this very section, you may create a link like so:
-
-```md
-[Link to this section](#why-extend-remarkable)
-```
-
-## A Brief Overview of How A Markdown Parser/Renderer Works
-
-This is a summary of the basic concepts you'll need to understand in order to extend Remarkable, based on the [Remarkable docs](https://github.com/jonschlinkert/remarkable/tree/master/docs) as well as our own experience extending Remarkable to support GFM-style heading anchors.
-
-As the heading here implies, there's two main parts to how a markdown parser works: the parsing phase, and the rendering phase. During the parsing phase, a plain markdown document is parsed into a set of tokens that describe its structure. These tokens are then used by the renderer to output the actual HTML contents.
-
-### Parsing Markdown into Tokens
-
-Let's talk a bit more about what is done as part of the parsing stage. The result of this stage is a tree made up of tokens. There's three types of tokens: inline, block, and core.
-
-#### Inline tokens
-
-Inline tokens are tokens that have text as a child. They are leaf nodes, and do not support having additional tokens within. An example of this might be `_emphasized text_`, which might be represented as a token of type `em` with contents of `emphasized text`.
-
-#### Block tokens
-
-A block token is a bit more complex. It may wrap one or more tokens, and can span more than one line of text. An example of this is the heading token:
-
-```md
-### Hi there
-```
-
-The plain markdown text above would be parsed into three tokens:
-
-- `heading_open`: Marks the beginning of the heading. May have additional props, such as `hLevel: 3` (heading level) in this case.
-- `text`: Plain text token, with a value of "Hi there".
-- `heading_close`: Marks the end of the heading. In this case, it would also have a `hLevel: 3` prop.
-
-This is a basic example, because it contains a `text` token within the opening and closing tags. A common block encountered in markdown is the paragraph, which might be tokenized into a series of tokens such as `paragraph_open`, one or more `text` tokens, `link` tokens (if links are present within the text, for example), and, eventually, a `paragraph_close` token.
-
-#### Core tokens
-
-These are outside of the initial scope of this article for now. Core tokens may be [reference-style links](https://github.github.com/gfm/#link-reference-definitions), which can appear anywhere in a markdown document.
-
-### Rendering Tokens into HTML
-
-After we have parsed everything into tokens, we go to the rendering phase. This is where we convert our `heading_open`, `text`, and `heading_close` tokens from earlier into `<h3>Hi there</h3>`. This should be self-explanatory.
-
-## Creating a Remarkable Extension
-
-Now that you have a better idea of how parsing/rendering works, we can proceed to create an extension that renders heading anchors. First we need to determine if we need to extend the parser, or the renderer. In this case, we're only interested in changing how a heading is rendered to HTML, so we'll just need to override the heading renderers.
-
-The default heading renderers may look like this (you can refer to the Remarkable source code here):
-
-```js
-md.renderer.rules.heading_open = function (tokens, idx /*, options, env */) {
-  return '<h' + tokens[idx].hLevel + '>';
-};
-
-md.renderer.rules.heading_close = function (tokens, idx /*, options, env */) {
-  return '</h' + tokens[idx].hLevel + '>\n';
-};
-```
-
-That's pretty straightforward: whenever these tokens are found, we render a `<hN>` or `</hN>` HTML tag, where N is the `hLevel` for this heading. That would result in `<h3>Hi there</h3>` being output. But what we want is something closer to this:
-
-```html
-<h3>
-  <a class="anchor" id="hi-there"></a>Hi there
-  <a class="hash-link" href="#hi-there">#</a>
-</h3>
-```
-
-In that case, we need to override our heading rules like so:
-
-```js
-md.renderer.rules.heading_open = function (tokens, idx /*, options, env */) {
-  return (
-    '<h' +
-    tokens[idx].hLevel +
-    '>' +
-    '<a class="anchor" id="' +
-    toSlug(tokens[idx + 1].content) +
-    '"></a>'
-  );
-};
-
-md.renderer.rules.heading_close = function (tokens, idx /*, options, env */) {
-  return (
-    ' <a class="hash-link" href="#' +
-    toSlug(tokens[idx - 1].content) +
-    '">#</a>' +
-    '</h' +
-    tokens[idx].hLevel +
-    '>\n'
-  );
-};
-```
-
-Note that we are referring to `tokens[idx+1]` and `tokens[idx-1]` at various points in the code. In the case of `idx+1` in `heading_open`, it refers to the next token after `heading_open`, which is a `text` inline token. Same for `heading_close`, where we get the same `text` token by grabbing the preceding token. That's because we make a reasonable assumption that the markdown parser has generated three tokens for each of our headers as covered above.
-
-### Using the Extension
-
-We now need to tell Remarkable to use our extension. We can wrap our rules in a function called `anchors`:
-
-```js
-function anchors(md) {
-  md.renderer.rules.heading_open = function (tokens, idx /*, options, env */) {
-    return (
-      '<h' +
-      tokens[idx].hLevel +
-      '>' +
-      '<a class="anchor" id="' +
-      toSlug(tokens[idx + 1].content) +
-      '"></a>'
-    );
-  };
-
-  md.renderer.rules.heading_close = function (tokens, idx /*, options, env */) {
-    return (
-      ' <a class="hash-link" href="#' +
-      toSlug(tokens[idx - 1].content) +
-      '">#</a>' +
-      '</h' +
-      tokens[idx].hLevel +
-      '>\n'
-    );
-  };
-}
-```
-
-We can now tell Remarkable to load this function as a plugin (`md` is our instance of Remarkable):
-
-```js
-this.md.use(anchors);
-```
-
-### Future Work
-
-A more advanced extension might add additional parser rules. These rules may add support for new markdown syntax not covered by Remarkable. Say, for example, a custom syntax to embed video when a tag like `@video` is found can be supported by generating a new type of token, that is later used by the renderer to output the necessary `<embed>` HTML tags. This is left as an exercise to the reader for now.

admin/local-third-party-project-testing.md

@@ -6,125 +6,78 @@ There are two reasonable ways to use a local version of the Docusaurus npm packa
 
 ## Install from a local Docusaurus repo
 
-> If you want to use the docusaurus init script for testing, you will have to update the `initialize.js` file to point to the local Docusaurus repo instead of installing it from the npm server. In some ways, it is just easier to do the manual steps.
+### Install in an existing project
 
-### Install the package from the Docusaurus repo
-
-```bash
-cd /path/to/testing_project
-mkdir website # if this does not exist already
-cd website
-```
-
-If you do not have a `package.json` file in the `website` directory, create one with the following content:
+Let's say you have an existing project with this snippet inside package.json:
 
 ```json
 {
-  "scripts": {
-    "start": "docusaurus-start",
-    "build": "docusaurus-build",
-    "publish-gh-pages": "docusaurus-publish",
-    "examples": "docusaurus-examples"
+  "dependencies": {
+    "@docusaurus/core": "^2.0.0-beta.8",
+    "@docusaurus/preset-classic": "^2.0.0-beta.8"
   }
 }
 ```
 
-Then:
+Now, you have made changes to @docusaurus/core (this lives in packages/docusaurus) and would like to test the changes. In the local docusaurus repo, run `yarn install`. This will also build the local docusaurus packages and install them within the repo itself:
 
 ```sh
-# Path to your Docusaurus clone
-npm install ../../path/to/docusaurus/
+cd /path/to/local/docusaurus
+# can use yarn build:packages if dependencies have not been modified
+yarn install
 ```
 
-### Clowntown!
-
-Now, we have a bit of clowntown here in the way symlinks are handled. The above `npm install`, creates a `node_modules` directory with a symlink in it. And errors will result if you try to access the local site after starting the server (as you do below). You will get something like this error:
-
-```
-ReferenceError: Unknown plugin "transform-class-properties" specified in "base" at 1, attempted to resolve relative to "/Users/joelm/dev/testing-local-Docusaurus-changes-site/website/core"
+In the existing project, add the local package:
 
+```sh
+cd /path/to/existing/project
+# this can be an absolute or relative path
+yarn add @docusaurus/core@../../local/docusaurus/packages/docusaurus
 ```
 
-So, you should install these packages locally. **Base the versions on the versions defined in the Docusaurus `package.json`**. e.g.,
+Check package.json again and you will find this:
 
-```bash
-# Still in the website directory of the testing project
-npm install babel-plugin-transform-class-properties@^6.24.1
-npm install babel-plugin-transform-object-rest-spread@^6.26.0
-npm install react@^16.4.1
-npm install babel-preset-env@^1.7.0
-npm install babel-preset-react@^6.24.1
+```json
+{
+  "dependencies": {
+    "@docusaurus/core": "../../local/docusaurus/packages/docusaurus",
+    "@docusaurus/preset-classic": "^2.0.0-beta.8"
+  }
+}
 ```
 
-### Test
+If you make further changes to the local docusaurus repo, run `yarn install` inside the existing project so that the changes will be applied.
 
-```bash
-./node_modules/.bin/docusaurus-examples # or whatever you want to test, if anything
-./node_modules/.bin/docusaurus-start
-```
+Note that:
+
+- The format is `scoped-package-name@local/path/to/specific/package/directory`.
+- The last component of the supplied path cannot be a symbolic link, it has to be the package directory itself.
+- If you supplied the wrong directory name, `yarn add` may not complain, but `yarn build` and `yarn start` will fail. To avoid this, check `package.json` inside the package directory to make sure you have the correct path.
+- These commands don't work:
+  ```
+  yarn add @docusaurus/core@../../local/docusaurus/node_modules/@docusaurus/core
+  yarn add file:../../local/docusaurus/packages/docusaurus
+  yarn add link:../../local/docusaurus/packages/docusaurus
+  yarn add ../../local/docusaurus/node_modules/@docusaurus/core
+  yarn add ../../local/docusaurus/packages/docusaurus
+  ```
+- You cannot use `npm install` instead of `yarn add` for this purpose.
+- `yarn link` is very likely to fail with react, unless you also manually link react. See https://github.com/facebook/react/issues/14257.
 
 ## Use Verdaccio
 
 Verdaccio is a good local npm server that you can use to test your packages.
 
-### Install verdaccio
+We have a script `test:build:website` that starts a docker with verdaccio, publishes the packages, and initializes a new website in the parent directory. Alternatively, to install a package in the existing project, after you have started the verdaccio service, run
 
 ```bash
-npm install --global verdaccio
+npm_config_registry="http://localhost:4873" yarn install @docusaurus/core@"2.0.0-beta.8.NEW" # The version should be the latest
 ```
 
-### Publish to verdaccio
+You can refer to [the implementation](./scripts/test-release.sh) for more details.
 
-When you are ready to test the code that could make up the next version of your package, you can publish locally to verdaccio
-
-Run verdaccio in a **separate terminal window**:
+If you don't have docker, you can still invoke the CLI manually to start the service.
 
 ```bash
-verdaccio
-```
-
-In another terminal window, get ready to publish your local npm package:
-
-```bash
-# Your clone of Docusaurus
-cd /path/to/docusaurus/
-
-# use anything for user, password, email
-# You should only have to do this once as long as you keep verdaccio installed
-npm adduser --registry http://localhost:4873
-
-npm publish --registry http://localhost:4873
-```
-
-You can navigate to localhost:4873 and you can see that your package was published. You can also see it showing you the steps you ran above as well.
-
-### Install the local npm package and test
-
-Now install the package in the repo you want to test Docusaurus on.
-
-```bash
-cd /path/to/testing_project/
-mkdir website # if this does not exist already
-cd website
-```
-
-If you do not have a `package.json` file in the `website` directory, create one with the following content:
-
-```json
-{
-  "scripts": {
-    "start": "docusaurus-start",
-    "build": "docusaurus-build",
-    "publish-gh-pages": "docusaurus-publish",
-    "examples": "docusaurus-examples"
-  }
-}
-```
-
-Then:
-
-```bash
-npm install docusaurus --registry http://localhost:4873 # this may be slower than the normal npm registry
-npm run examples # or whatever you want to test, if anything
-npm run start
+npx verdaccio --listen 4873 --config admin/verdaccio.yaml
 ```

admin/new.docusaurus.io/README.md

@@ -2,7 +2,7 @@
 
 This is a Netlify deployment to handle the Docusaurus playgrounds shortcuts:
 
-- [docusaurus.new](https://docusaurus.new) (main one, as of today domain is owned by StackBlitz but may be transfered to FB)
+- [docusaurus.new](https://docusaurus.new) (main one, as of today domain is owned by StackBlitz but may be transferred to FB)
 - [new.docusaurus.io](https://new.docusaurus.io) (legacy one)
 
 See also the [Playground doc page](https://docusaurus.io/docs/playground)

admin/new.docusaurus.io/functionUtils/playgroundUtils.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {HandlerEvent, HandlerResponse} from '@netlify/functions';
+import type {HandlerEvent, HandlerResponse} from '@netlify/functions';
 
 const CookieName = 'DocusaurusPlaygroundName';
 

admin/new.docusaurus.io/functions/codesandbox.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {Handler} from '@netlify/functions';
+import type {Handler} from '@netlify/functions';
 
 import {createPlaygroundResponse} from '../functionUtils/playgroundUtils';
 

admin/new.docusaurus.io/functions/index.ts

@@ -4,7 +4,8 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import {Handler} from '@netlify/functions';
+
+import type {Handler} from '@netlify/functions';
 
 import {
   readPlaygroundName,

admin/new.docusaurus.io/functions/stackblitz.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {Handler} from '@netlify/functions';
+import type {Handler} from '@netlify/functions';
 
 import {createPlaygroundResponse} from '../functionUtils/playgroundUtils';
 

admin/new.docusaurus.io/package.json

@@ -1,14 +1,14 @@
 {
   "name": "new.docusaurus.io",
-  "version": "2.0.0-beta.9",
+  "version": "2.0.0-beta.14",
   "private": true,
   "scripts": {
     "start": "netlify dev"
   },
   "dependencies": {
-    "@netlify/functions": "^0.7.2"
+    "@netlify/functions": "^0.10.0"
   },
   "devDependencies": {
-    "netlify-cli": "^5.2.2"
+    "netlify-cli": "^8.0.5"
   }
 }

admin/scripts/generateExamples.mjs

@@ -5,15 +5,22 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// eslint-disable-next-line import/no-extraneous-dependencies
-const rimraf = require('rimraf');
-const {readFileSync, writeFileSync, readdirSync} = require('fs');
-const {execSync} = require('child_process');
+/* eslint-disable import/no-extraneous-dependencies */
+
+import fs from 'fs-extra';
+import shell from 'shelljs';
+
+const NODE_MAJOR_VERSION = parseInt(process.versions.node.split('.')[0], 10);
+if (NODE_MAJOR_VERSION < 16) {
+  throw new Error(
+    'This generateExamples Docusaurus script requires at least Node.js 16 and npm 7. See why here: https://github.com/facebook/docusaurus/pull/5722#issuecomment-948847891',
+  );
+}
 
 // Generate one example per init template
 // We use those generated examples as CodeSandbox projects
 // See https://github.com/facebook/docusaurus/issues/1699
-function generateTemplateExample(template) {
+async function generateTemplateExample(template) {
   try {
     console.log(
       `generating ${template} template for codesandbox in the examples folder...`,
@@ -23,20 +30,17 @@ function generateTemplateExample(template) {
     const command = template.endsWith('-typescript')
       ? template.replace('-typescript', ' -- --typescript')
       : template;
-    execSync(
+    shell.exec(
       // /!\ we use the published init script on purpose,
       // because using the local init script is too early and could generate upcoming/unavailable config options
       // remember CodeSandbox templates will use the published version, not the repo version
       `npm init docusaurus@latest examples/${template} ${command}`,
       // `node ./packages/docusaurus-init/bin/index.js init examples/${template} ${template}`,
-      {
-        stdio: 'inherit',
-      },
     );
 
     // read the content of the package.json
     const templatePackageJson = JSON.parse(
-      readFileSync(`examples/${template}/package.json`, 'utf8'),
+      await fs.readFile(`examples/${template}/package.json`, 'utf8'),
     );
 
     // attach the dev script which would be used in code sandbox by default
@@ -57,13 +61,13 @@ function generateTemplateExample(template) {
         : `Docusaurus example project (${template} template)`;
 
     // rewrite the package.json file with the new edit
-    writeFileSync(
+    await fs.writeFile(
       `./examples/${template}/package.json`,
-      JSON.stringify(templatePackageJson, null, 2),
+      `${JSON.stringify(templatePackageJson, null, 2)}\n`,
     );
 
     // create sandbox.config.json file at the root of template
-    const codeSanboxConfig = {
+    const codeSandboxConfig = {
       infiniteLoopProtection: true,
       hardReloadOnChange: true,
       view: 'browser',
@@ -73,18 +77,18 @@ function generateTemplateExample(template) {
         node: '14',
       },
     };
-    writeFileSync(
+    await fs.writeFile(
       `./examples/${template}/sandbox.config.json`,
-      JSON.stringify(codeSanboxConfig, null, 2),
+      `${JSON.stringify(codeSandboxConfig, null, 2)}\n`,
     );
 
     const stackBlitzConfig = {
       installDependencies: true,
       startCommand: 'npm start',
     };
-    writeFileSync(
+    await fs.writeFile(
       `./examples/${template}/.stackblitzrc`,
-      JSON.stringify(stackBlitzConfig, null, 2),
+      `${JSON.stringify(stackBlitzConfig, null, 2)}\n`,
     );
 
     console.log(`Generated example for template ${template}`);
@@ -108,7 +112,7 @@ function updateStarters() {
     const command = `git push ${remote} \`git subtree split --prefix ${subfolder}\`:${remoteBranch} --force`;
     try {
       console.log(`forcePushGitSubtree command: ${command}`);
-      execSync(command);
+      shell.exec(command);
       console.log('forcePushGitSubtree success!');
     } catch (e) {
       console.error(
@@ -143,60 +147,58 @@ function updateStarters() {
   console.log('');
 }
 
-function run() {
-  const branch = execSync('git rev-parse --abbrev-ref HEAD').toString();
-  if (branch === 'main') {
-    throw new Error(
-      "Please don't generate Docusaurus examples from the main branch!\nWe are going to commit during this process!",
-    );
-  }
-  try {
-    execSync('git diff --exit-code');
-  } catch (e) {
-    throw new Error(
-      'Please run the generate examples command with a clean Git state and no uncommited local changes. git diff should display nothing!',
-    );
-  }
-
-  console.log('');
-  console.log('# Generate examples start!');
-  console.log('');
-
-  // delete the examples directories if they exists
-  console.log('-------');
-  console.log('## Removing example folders...');
-  rimraf.sync('./examples/classic');
-  rimraf.sync('./examples/classic-typescript');
-  rimraf.sync('./examples/facebook');
-  console.log('');
-
-  // get the list of all available templates
-  console.log('-------');
-  console.log('## Generate example folders...');
-  console.log('');
-  const excludes = ['README.md', 'shared'];
-  const templates = readdirSync(
-    './packages/create-docusaurus/templates',
-  ).filter((name) => !excludes.includes(name));
-  console.log(`Will generate examples for templates: ${templates}`);
-  templates.forEach(generateTemplateExample);
-  console.log('Commiting changes');
-  execSync('git add examples');
-  execSync("git commit -am 'update examples' --allow-empty");
-  console.log('');
-
-  // update starters
-  console.log('-------');
-  console.log('# Updating starter repos and branches ...');
-  console.log('It can take some time... please wait until done...');
-  updateStarters();
-
-  console.log('');
-  console.log('-------');
-  console.log('');
-  console.log('Generate examples end!');
-  console.log("Don't forget to push and merge your pull-request!");
-  console.log('');
+const branch = shell.exec('git rev-parse --abbrev-ref HEAD').stdout;
+if (branch === 'main') {
+  throw new Error(
+    "Please don't generate Docusaurus examples from the main branch!\nWe are going to commit during this process!",
+  );
+}
+if (shell.exec('git diff --exit-code').code !== 0) {
+  throw new Error(
+    'Please run the generate examples command with a clean Git state and no uncommitted local changes. git diff should display nothing!',
+  );
 }
 
-run();
+console.log(`
+# Generate examples start!
+`);
+
+// delete the examples directories if they exists
+console.log(`-------
+## Removing example folders...
+`);
+await fs.rm('./examples/classic', {recursive: true, force: true});
+await fs.rm('./examples/classic-typescript', {recursive: true, force: true});
+await fs.rm('./examples/facebook', {recursive: true, force: true});
+
+// get the list of all available templates
+console.log(`
+-------
+## Generate example folders...
+`);
+const excludes = ['README.md', 'shared'];
+const templates = (
+  await fs.readdir('./packages/create-docusaurus/templates')
+).filter((name) => !excludes.includes(name));
+console.log(`Will generate examples for templates: ${templates.join(',')}`);
+// eslint-disable-next-line no-restricted-syntax
+for (const template of templates) {
+  await generateTemplateExample(template);
+}
+console.log('Committing changes');
+shell.exec('git add examples');
+shell.exec("git commit -am 'update examples' --allow-empty");
+
+// update starters
+console.log(`
+-------
+# Updating starter repos and branches ...
+It can take some time... please wait until done...
+`);
+updateStarters();
+
+console.log(`
+-------
+Generate examples end!
+Don't forget to push and merge your pull request!
+`);

admin/scripts/image-resize.mjs

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ */
+
+/* eslint-disable import/no-extraneous-dependencies */
+
+import sharp from 'sharp';
+import fs from 'fs-extra';
+import path from 'path';
+import imageSize from 'image-size';
+import {fileURLToPath} from 'url';
+
+const allImages = (
+  await fs.readdir(new URL('../../website/src/data/showcase', import.meta.url))
+).filter((file) => ['.png', 'jpg', '.jpeg'].includes(path.extname(file)));
+
+const [, , ...selectedImages] = process.argv;
+const images = selectedImages.length > 0 ? selectedImages : allImages;
+
+await Promise.all(
+  images.map(async (img) => {
+    const imgPath = fileURLToPath(
+      new URL(`../../website/src/data/showcase/${img}`, import.meta.url),
+    );
+    const {width, height} = imageSize(imgPath);
+    if (width === 640 && height === 320) {
+      // Do not emit if no resized. Important because we
+      // can't guarantee idempotency during resize -> optimization
+      return;
+    }
+    const data = await sharp(imgPath)
+      .resize(640, 320, {fit: 'cover', position: 'top'})
+      .png()
+      .toBuffer();
+    await fs.writeFile(imgPath.replace(/jpe?g/, 'png'), data);
+  }),
+);
+
+// You should also run optimizt `find website/src/data/showcase -type f -name '*.png'`.
+// This is not included here because @funboxteam/optimizt doesn't seem to play well with M1
+// so I had to run this in a Rosetta terminal.
+// TODO integrate this as part of the script

admin/scripts/test-release.sh

@@ -17,10 +17,10 @@ usage() { echo "Usage: $0 [-n] [-s]" 1>&2; exit 1; }
 while getopts ":ns" o; do
   case "${o}" in
     n)
-      EXTRA_OPTS="--use-npm"
+      EXTRA_OPTS="${EXTRA_OPTS} --use-npm"
       ;;
     s)
-      EXTRA_OPTS="--skip-install"
+      EXTRA_OPTS="${EXTRA_OPTS} --skip-install"
       ;;
     *)
       usage
@@ -47,8 +47,12 @@ npx --no-install lerna publish --exact --yes --no-verify-access --no-git-reset -
 # Revert version changes
 git diff --name-only -- '*.json' | sed 's, ,\\&,g' | xargs git checkout --
 
+
+# The website is generated outside the repo to minimize chances of yarn resolving the wrong version
+cd ..
+
 # Build skeleton website with new version
-npm_config_registry="$CUSTOM_REGISTRY_URL" npm init docusaurus@"$NEW_VERSION" test-website classic $EXTRA_OPTS
+npm_config_registry="$CUSTOM_REGISTRY_URL" npx create-docusaurus@"$NEW_VERSION" test-website classic $EXTRA_OPTS
 
 # Stop Docker container
 if [[ -z "${KEEP_CONTAINER:-}" ]] && ( $(docker container inspect "$CONTAINER_NAME" > /dev/null 2>&1) ); then

admin/testing-changes-on-Docusaurus-itself.md

@@ -8,13 +8,11 @@ It is straightforward to test your Docusaurus changes with Docusaurus.
 
 ```bash
 cd /path/to/docusaurus-repo
-npm install
+yarn install
 cd website
-npm run start
+yarn start
 ```
 
-> If you look in the `website/package.json` file, you will notice that running `start` with `npm run` actually executes the local `start-server.js` file. This is how you know you are running with local code.
-
 ## Debugging Locally
 
 ### VS Code
@@ -43,4 +41,4 @@ Feel free to contribute debug instructions for other IDEs
 
 ### Observing changes
 
-Now that the server is running, you can make changes to the core Docusaurus code and docs to see the effects on the Docusaurus site. LiveReload will reflect changes to the local site in your browser, usually running at http://localhost:3000.
+Note that since most packages are built with TypeScript, you would need to compile them every time to see the effect. Alternatively, you can run `yarn watch` inside the package directory to start an incremental build. Now that the server is running, you can make changes to the core Docusaurus code and docs to see the effects on the Docusaurus site. LiveReload will reflect changes to the local site in your browser, usually running at http://localhost:3000.

crowdin-v2.yaml

@@ -2,9 +2,9 @@
 # Your Crowdin credentials
 #
 project_id: '428890'
-api_token_env: 'CROWDIN_PERSONAL_TOKEN'
+api_token_env: CROWDIN_PERSONAL_TOKEN
 # base_path: '.'
-# base_url: 'https://api.crowdin.com'
+# base_url: https://api.crowdin.com
 
 #
 # Choose file structure in Crowdin
@@ -18,45 +18,31 @@ preserve_hierarchy: true
 # Note: &/* is Yaml anchor syntax: https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/
 languages_mapping: &languages_mapping
   two_letters_code:
-    'pt-BR': 'pt-BR'
+    pt-BR: pt-BR
 
 #
 # Files configuration
 #
 files:
-  [
-    {
-      source: '/website/i18n/en/**/*',
-      translation: '/website/i18n/%two_letters_code%/**/%original_file_name%',
-      languages_mapping: *languages_mapping,
-    },
-    {
-      source: '/website/docs/**/*',
-      translation: '/website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%',
-      languages_mapping: *languages_mapping,
-    },
-    {
-      source: '/website/community/**/*',
-      translation: '/website/i18n/%two_letters_code%/docusaurus-plugin-content-docs-community/current/**/%original_file_name%',
-      languages_mapping: *languages_mapping,
-    },
-    {
-      source: '/website/versioned_docs/**/*',
-      translation: '/website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/**/%original_file_name%',
-      languages_mapping: *languages_mapping,
-    },
-    {
-      source: '/website/blog/**/*',
-      translation: '/website/i18n/%two_letters_code%/docusaurus-plugin-content-blog/**/%original_file_name%',
-      languages_mapping: *languages_mapping,
-    },
-    {
-      source: '/website/src/pages/**/*',
-      translation: '/website/i18n/%two_letters_code%/docusaurus-plugin-content-pages/**/%original_file_name%',
-      ignore: ['/**/*.js', '/**/*.jsx', '/**/*.ts', '/**/*.tsx', '/**/*.css'],
-      languages_mapping: *languages_mapping,
-    },
-  ]
+  - source: /website/i18n/en/**/*
+    translation: /website/i18n/%two_letters_code%/**/%original_file_name%
+    languages_mapping: *languages_mapping
+  - source: /website/docs/**/*
+    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%
+    languages_mapping: *languages_mapping
+  - source: /website/community/**/*
+    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs-community/current/**/%original_file_name%
+    languages_mapping: *languages_mapping
+  - source: /website/versioned_docs/**/*
+    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/**/%original_file_name%
+    languages_mapping: *languages_mapping
+  - source: /website/blog/**/*
+    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-blog/**/%original_file_name%
+    languages_mapping: *languages_mapping
+  - source: /website/src/pages/**/*
+    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-pages/**/%original_file_name%
+    ignore: [/**/*.js, /**/*.jsx, /**/*.ts, /**/*.tsx, /**/*.css]
+    languages_mapping: *languages_mapping
 #
 # Source files filter
 # e.g. "/resources/en/*.json"

examples/README.md

@@ -9,7 +9,7 @@ npx @docusaurus/init@latest init examples/<templateName> <templateName>`
 You can run them in CodeSandbox:
 
 - [classic](https://codesandbox.io/s/github/facebook/docusaurus/tree/main/examples/classic)
-- [bootstrap](https://codesandbox.io/s/github/facebook/docusaurus/tree/main/examples/bootstrap)
+- [classic-typescript](https://codesandbox.io/s/github/facebook/docusaurus/tree/main/examples/classic-typescript)
 - [facebook](https://codesandbox.io/s/github/facebook/docusaurus/tree/main/examples/facebook)
 
 **Tip**: use the [new.docusaurus.io](https://new.docusaurus.io) shortcut.

examples/classic-typescript/README.md

@@ -26,8 +26,16 @@ This command generates static content into the `build` directory and can be serv
 
 ### Deployment
 
+Using SSH:
+
 ```
-$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

examples/classic-typescript/docs/intro.md

@@ -16,7 +16,7 @@ Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new
 
 Generate a new Docusaurus site using the **classic template**:
 
-```shell
+```bash
 npm init docusaurus@latest my-website classic
 ```
 
@@ -24,7 +24,7 @@ npm init docusaurus@latest my-website classic
 
 Run the development server:
 
-```shell
+```bash
 cd my-website
 
 npx docusaurus start
@@ -32,4 +32,4 @@ npx docusaurus start
 
 Your site starts at `http://localhost:3000`.
 
-Open `docs/intro.md` and edit some lines: the site **reloads automatically** and display your changes.
+Open `docs/intro.md` and edit some lines: the site **reloads automatically** and displays your changes.

examples/classic-typescript/docusaurus.config.js

@@ -18,19 +18,19 @@ const config = {
 
   presets: [
     [
-      '@docusaurus/preset-classic',
+      'classic',
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
         docs: {
           sidebarPath: require.resolve('./sidebars.js'),
           // Please change this to your repo.
-          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
+          editUrl: 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
         },
         blog: {
           showReadingTime: true,
           // Please change this to your repo.
           editUrl:
-            'https://github.com/facebook/docusaurus/edit/main/website/blog/',
+            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
         },
         theme: {
           customCss: require.resolve('./src/css/custom.css'),

examples/classic-typescript/package.json

@@ -16,21 +16,18 @@
     "dev": "docusaurus start"
   },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.8",
-    "@docusaurus/preset-classic": "2.0.0-beta.8",
+    "@docusaurus/core": "2.0.0-beta.14",
+    "@docusaurus/preset-classic": "2.0.0-beta.14",
     "@mdx-js/react": "^1.6.21",
-    "@svgr/webpack": "^5.5.0",
     "clsx": "^1.1.1",
-    "file-loader": "^6.2.0",
     "prism-react-renderer": "^1.2.1",
     "react": "^17.0.1",
-    "react-dom": "^17.0.1",
-    "url-loader": "^4.1.1"
+    "react-dom": "^17.0.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.8",
+    "@docusaurus/module-type-aliases": "2.0.0-beta.14",
     "@tsconfig/docusaurus": "^1.0.4",
-    "typescript": "^4.3.5"
+    "typescript": "^4.5.2"
   },
   "browserslist": {
     "production": [

examples/classic-typescript/src/components/HomepageFeatures.tsx

@@ -1,9 +1,4 @@
-/**
- * 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 useBaseUrl from '@docusaurus/useBaseUrl';
 import React from 'react';
 import clsx from 'clsx';
 import styles from './HomepageFeatures.module.css';
@@ -51,7 +46,11 @@ function Feature({title, image, description}: FeatureItem) {
   return (
     <div className={clsx('col col--4')}>
       <div className="text--center">
-        <img className={styles.featureSvg} alt={title} src={image} />
+        <img
+          className={styles.featureSvg}
+          alt={title}
+          src={useBaseUrl(image)}
+        />
       </div>
       <div className="text--center padding-horiz--md">
         <h3>{title}</h3>

examples/classic/README.md

@@ -26,8 +26,16 @@ This command generates static content into the `build` directory and can be serv
 
 ### Deployment
 
+Using SSH:
+
 ```
-$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

examples/classic/docs/intro.md

@@ -16,7 +16,7 @@ Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new
 
 Generate a new Docusaurus site using the **classic template**:
 
-```shell
+```bash
 npm init docusaurus@latest my-website classic
 ```
 
@@ -24,7 +24,7 @@ npm init docusaurus@latest my-website classic
 
 Run the development server:
 
-```shell
+```bash
 cd my-website
 
 npx docusaurus start
@@ -32,4 +32,4 @@ npx docusaurus start
 
 Your site starts at `http://localhost:3000`.
 
-Open `docs/intro.md` and edit some lines: the site **reloads automatically** and display your changes.
+Open `docs/intro.md` and edit some lines: the site **reloads automatically** and displays your changes.

examples/classic/docusaurus.config.js

@@ -18,19 +18,19 @@ const config = {
 
   presets: [
     [
-      '@docusaurus/preset-classic',
+      'classic',
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
         docs: {
           sidebarPath: require.resolve('./sidebars.js'),
           // Please change this to your repo.
-          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
+          editUrl: 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
         },
         blog: {
           showReadingTime: true,
           // Please change this to your repo.
           editUrl:
-            'https://github.com/facebook/docusaurus/edit/main/website/blog/',
+            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
         },
         theme: {
           customCss: require.resolve('./src/css/custom.css'),

examples/classic/package.json

@@ -15,16 +15,13 @@
     "dev": "docusaurus start"
   },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.8",
-    "@docusaurus/preset-classic": "2.0.0-beta.8",
+    "@docusaurus/core": "2.0.0-beta.14",
+    "@docusaurus/preset-classic": "2.0.0-beta.14",
     "@mdx-js/react": "^1.6.21",
-    "@svgr/webpack": "^5.5.0",
     "clsx": "^1.1.1",
-    "file-loader": "^6.2.0",
     "prism-react-renderer": "^1.2.1",
     "react": "^17.0.1",
-    "react-dom": "^17.0.1",
-    "url-loader": "^4.1.1"
+    "react-dom": "^17.0.1"
   },
   "browserslist": {
     "production": [

examples/facebook/.eslintrc.js

@@ -23,7 +23,7 @@ module.exports = {
   parserOptions: {
     allowImportExportEverywhere: true,
   },
-  extends: ['airbnb', 'prettier', 'prettier/react'],
+  extends: ['airbnb', 'prettier'],
   plugins: ['react-hooks', 'header'],
   rules: {
     // Ignore certain webpack alias because it can't be resolved
@@ -52,9 +52,15 @@ module.exports = {
         ' ',
       ],
     ],
-    'react/jsx-closing-bracket-location': OFF, // Conflicts with Prettier.
     'react/jsx-filename-extension': OFF,
     'react-hooks/rules-of-hooks': ERROR,
     'react/prop-types': OFF, // PropTypes aren't used much these days.
+    'react/function-component-definition': [
+      WARNING,
+      {
+        namedComponents: 'function-declaration',
+        unnamedComponents: 'arrow-function',
+      },
+    ],
   },
 };

examples/facebook/.prettierrc

@@ -1,7 +1,7 @@
 {
   "arrowParens": "always",
+  "bracketSameLine": true,
   "bracketSpacing": false,
-  "jsxBracketSameLine": true,
   "printWidth": 80,
   "proseWrap": "never",
   "singleQuote": true,

examples/facebook/README.md

@@ -26,8 +26,16 @@ This command generates static content into the `build` directory and can be serv
 
 ### Deployment
 
+Using SSH:
+
 ```
-$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

examples/facebook/docs/intro.md

@@ -16,7 +16,7 @@ Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new
 
 Generate a new Docusaurus site using the **classic template**:
 
-```shell
+```bash
 npm init docusaurus@latest my-website classic
 ```
 
@@ -24,7 +24,7 @@ npm init docusaurus@latest my-website classic
 
 Run the development server:
 
-```shell
+```bash
 cd my-website
 
 npx docusaurus start

examples/facebook/docusaurus.config.js

@@ -23,19 +23,20 @@ const config = {
 
   presets: [
     [
-      '@docusaurus/preset-classic',
+      'classic',
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
         docs: {
           sidebarPath: require.resolve('./sidebars.js'),
           // Please change this to your repo.
-          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
+          editUrl:
+            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
         },
         blog: {
           showReadingTime: true,
           // Please change this to your repo.
           editUrl:
-            'https://github.com/facebook/docusaurus/edit/main/website/blog/',
+            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
         },
         theme: {
           customCss: require.resolve('./src/css/custom.css'),

examples/facebook/package.json

@@ -12,34 +12,31 @@
     "serve": "docusaurus serve",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
-    "ci": "yarn lint && yarn prettier:diff",
+    "ci": "yarn lint && yarn format:diff",
     "lint": "eslint --cache \"**/*.js\" && stylelint \"**/*.css\"",
-    "prettier": "prettier --config .prettierrc --write \"**/*.{js,jsx,ts,tsx,md,mdx}\"",
-    "prettier:diff": "prettier --config .prettierrc --list-different \"**/*.{js,jsx,ts,tsx,md,mdx}\"",
+    "format": "prettier --config .prettierrc --write \"**/*.{js,jsx,ts,tsx,md,mdx}\"",
+    "format:diff": "prettier --config .prettierrc --list-different \"**/*.{js,jsx,ts,tsx,md,mdx}\"",
     "dev": "docusaurus start"
   },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.8",
-    "@docusaurus/preset-classic": "2.0.0-beta.8",
+    "@docusaurus/core": "2.0.0-beta.14",
+    "@docusaurus/preset-classic": "2.0.0-beta.14",
     "@mdx-js/react": "^1.6.21",
-    "@svgr/webpack": "^5.5.0",
     "clsx": "^1.1.1",
-    "file-loader": "^6.2.0",
     "react": "^17.0.1",
-    "react-dom": "^17.0.1",
-    "url-loader": "^4.1.1"
+    "react-dom": "^17.0.1"
   },
   "devDependencies": {
-    "@babel/eslint-parser": "^7.15.7",
-    "eslint": "^7.20.0",
-    "eslint-config-airbnb": "^18.2.1",
-    "eslint-config-prettier": "^6.15.0",
-    "eslint-plugin-header": "^3.0.0",
-    "eslint-plugin-import": "^2.22.1",
-    "eslint-plugin-jsx-a11y": "^6.4.1",
-    "eslint-plugin-react": "^7.21.5",
-    "eslint-plugin-react-hooks": "^4.2.0",
-    "prettier": "^2.2.1",
+    "@babel/eslint-parser": "^7.16.3",
+    "eslint": "^8.2.0",
+    "eslint-config-airbnb": "^19.0.0",
+    "eslint-config-prettier": "^8.3.0",
+    "eslint-plugin-header": "^3.1.1",
+    "eslint-plugin-import": "^2.25.3",
+    "eslint-plugin-jsx-a11y": "^6.5.1",
+    "eslint-plugin-react": "^7.27.0",
+    "eslint-plugin-react-hooks": "^4.3.0",
+    "prettier": "^2.5.1",
     "stylelint": "^13.2.1"
   },
   "browserslist": {
@@ -55,4 +52,4 @@
     ]
   },
   "description": "Docusaurus example project (facebook template)"
-}
+}

jest.config.mjs

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const path = require('path');
+import {fileURLToPath} from 'url';
 
 const ignorePatterns = [
   '/node_modules/',
@@ -21,8 +21,8 @@ const ignorePatterns = [
   '/packages/docusaurus-migrate/lib',
 ];
 
-module.exports = {
-  rootDir: path.resolve(__dirname),
+export default {
+  rootDir: fileURLToPath(new URL('.', import.meta.url)),
   verbose: true,
   testURL: 'http://localhost/',
   testEnvironment: 'node',
@@ -31,10 +31,10 @@ module.exports = {
   transform: {
     '^.+\\.[jt]sx?$': 'babel-jest',
   },
-  setupFiles: ['./jest/stylelint-rule-test.js', './jest/polyfills.js'],
   moduleNameMapper: {
-    // Jest can't resolve CSS imports
-    '^.+\\.css$': '<rootDir>/jest/emptyModule.js',
+    // Jest can't resolve CSS or asset imports
+    '^.+\\.(css|jpg|jpeg|png|svg)$': '<rootDir>/jest/emptyModule.js',
+
     // TODO we need to allow Jest to resolve core Webpack aliases automatically
     '@docusaurus/(browserContext|BrowserOnly|ComponentCreator|constants|docusaurusContext|ExecutionEnvironment|Head|Interpolate|isInternalUrl|Link|Noop|renderRoutes|router|Translate|use.*)':
       '@docusaurus/core/lib/client/exports/$1',
@@ -42,5 +42,15 @@ module.exports = {
     '@generated/.*': '<rootDir>/jest/emptyModule.js',
     // TODO maybe use "projects" + multiple configs if we plan to add tests to another theme?
     '@theme/(.*)': '@docusaurus/theme-classic/src/theme/$1',
+    '@site/(.*)': 'website/$1',
+
+    // TODO why Jest can't figure node package entry points?
+    '@docusaurus/plugin-content-docs/client':
+      '@docusaurus/plugin-content-docs/lib/client/index.js',
+  },
+  globals: {
+    window: {
+      location: {href: 'https://docusaurus.io'},
+    },
   },
 };

jest/polyfills.js

@@ -1,19 +0,0 @@
-/**
- * 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.
- */
-/* eslint-disable import/no-extraneous-dependencies */
-require('@formatjs/intl-pluralrules/polyfill');
-require('@formatjs/intl-pluralrules/locale-data/en');
-require('@formatjs/intl-pluralrules/locale-data/fr');
-
-require('@formatjs/intl-numberformat/polyfill');
-require('@formatjs/intl-numberformat/locale-data/en');
-require('@formatjs/intl-numberformat/locale-data/fr');
-
-require('@formatjs/intl-datetimeformat/polyfill');
-require('@formatjs/intl-datetimeformat/add-all-tz');
-require('@formatjs/intl-datetimeformat/locale-data/en');
-require('@formatjs/intl-datetimeformat/locale-data/fr');

jest/stylelint-rule-test.js

@@ -1,120 +0,0 @@
-/**
- * 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.
- */
-
-// eslint-disable-next-line import/no-extraneous-dependencies
-const stylelint = require('stylelint');
-
-function getOutputCss(output) {
-  const result = output.results[0]._postcssResult;
-  return result.root.toString(result.opts.syntax);
-}
-
-global.testStylelintRule = (config, tests) => {
-  describe(tests.ruleName, () => {
-    const checkTestCaseContent = (testCase) =>
-      testCase.description || testCase.code || 'no description';
-
-    if (tests.accept && tests.accept.length) {
-      describe('accept cases', () => {
-        tests.accept.forEach((testCase) => {
-          const spec = testCase.only ? it.only : it;
-
-          spec(checkTestCaseContent(testCase), () => {
-            const options = {
-              code: testCase.code,
-              config,
-              syntax: tests.syntax,
-            };
-
-            return stylelint.lint(options).then((output) => {
-              expect(output.results[0].warnings).toEqual([]);
-
-              if (!tests.fix) {
-                return null;
-              }
-
-              // Check the fix.
-              return stylelint
-                .lint({...options, fix: true})
-                .then((fixedOutput) => getOutputCss(fixedOutput))
-                .then((fixedCode) => expect(fixedCode).toBe(testCase.fixed));
-            });
-          });
-        });
-      });
-    }
-
-    if (tests.reject && tests.reject.length) {
-      describe('reject cases', () => {
-        tests.reject.forEach((testCase) => {
-          const skip = testCase.skip ? it.skip : it;
-          const spec = testCase.only ? it.only : skip;
-
-          spec(checkTestCaseContent(testCase), () => {
-            const options = {
-              code: testCase.code,
-              config,
-              syntax: tests.syntax,
-            };
-
-            return stylelint.lint(options).then((output) => {
-              const {warnings} = output.results[0];
-              const warning = warnings[0];
-
-              expect(warnings.length).toBeGreaterThanOrEqual(1);
-              expect(testCase).toHaveMessage();
-
-              if (testCase.message != null) {
-                expect(warning.text).toBe(testCase.message);
-              }
-
-              if (testCase.line != null) {
-                expect(warning.line).toBe(testCase.line);
-              }
-
-              if (testCase.column != null) {
-                expect(warning.column).toBe(testCase.column);
-              }
-
-              if (!tests.fix) {
-                return null;
-              }
-
-              if (!testCase.fixed) {
-                throw new Error(
-                  'If using { fix: true } in test tests, all reject cases must have { fixed: .. }',
-                );
-              }
-
-              // Check the fix.
-              return stylelint
-                .lint({...options, fix: true})
-                .then((fixedOutput) => getOutputCss(fixedOutput))
-                .then((fixedCode) => expect(fixedCode).toBe(testCase.fixed));
-            });
-          });
-        });
-      });
-    }
-
-    expect.extend({
-      toHaveMessage(testCase) {
-        if (testCase.message == null) {
-          return {
-            message: () =>
-              'Expected "reject" test case to have a "message" property',
-            pass: false,
-          };
-        }
-
-        return {
-          pass: true,
-        };
-      },
-    });
-  });
-};

lerna.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.0.0-beta.9",
+  "version": "2.0.0-beta.14",
   "npmClient": "yarn",
   "useWorkspaces": true,
   "changelog": {

package.json

@@ -1,5 +1,7 @@
 {
   "name": "root",
+  "version": "0.0.0",
+  "license": "MIT",
   "private": true,
   "workspaces": [
     "packages/*",
@@ -15,7 +17,7 @@
     "start:website:baseUrl": "yarn workspace website start:baseUrl",
     "start:website:blogOnly": "yarn workspace website start:blogOnly",
     "start:website:deployPreview": "cross-env NETLIFY=true CONTEXT='deploy-preview' yarn workspace website start",
-    "examples:generate": "node generateExamples",
+    "examples:generate": "node admin/scripts/generateExamples.mjs",
     "build": "yarn build:packages && yarn build:website",
     "build:packages": "lerna run build --no-private",
     "build:website": "yarn workspace website build",
@@ -38,16 +40,14 @@
     "canary:bumpVersion": "yarn lerna version `yarn --silent canary:version` --exact --no-push --yes",
     "canary:publish": "yarn lerna publish from-package --dist-tag canary --yes --no-verify-access",
     "changelog": "lerna-changelog",
-    "postinstall": "run-p postinstall:**",
-    "postinstall:main": "yarn lock:update && yarn build:packages",
-    "postinstall:dev": "is-ci || husky install",
-    "prettier": "prettier --config .prettierrc --write \"**/*.{js,jsx,ts,tsx,json}\"",
-    "prettier:diff": "prettier --config .prettierrc --list-different \"**/*.{js,jsx,ts,tsx,json}\"",
-    "prettier-docs": "prettier --config .prettierrc --write \"**/*.{md,mdx}\"",
-    "prettier-docs:diff": "prettier --config .prettierrc --list-different \"**/*.{md,mdx}\"",
-    "lint": "yarn lint:js && yarn lint:style",
-    "lint:ci": "yarn lint:js --quiet --report-unused-disable-directives && yarn lint:style",
-    "lint:js": "eslint --cache \"**/*.{js,jsx,ts,tsx}\"",
+    "postinstall": "yarn lock:update && yarn build:packages",
+    "prepare": "husky install",
+    "format": "prettier --write .",
+    "format:diff": "prettier --list-different .",
+    "lint": "yarn lint:js && yarn lint:style && yarn lint:spelling",
+    "lint:ci": "yarn lint:js --quiet && yarn lint:style && yarn lint:spelling",
+    "lint:js": "eslint --cache  --report-unused-disable-directives \"**/*.{js,jsx,ts,tsx,mjs}\"",
+    "lint:spelling": "cspell \"**\" --no-progress",
     "lint:style": "stylelint \"**/*.css\"",
     "lerna": "lerna",
     "test": "cross-env TZ=UTC jest",
@@ -66,66 +66,61 @@
     "@babel/plugin-transform-modules-commonjs": "^7.16.0",
     "@babel/preset-typescript": "^7.16.0",
     "@crowdin/cli": "^3.7.1",
-    "@formatjs/intl-datetimeformat": "^3.2.12",
-    "@formatjs/intl-numberformat": "^6.2.2",
-    "@formatjs/intl-pluralrules": "^4.0.11",
-    "@types/cssnano": "^4.0.0",
-    "@types/express": "^4.17.2",
     "@types/fs-extra": "^9.0.6",
     "@types/jest": "^26.0.20",
-    "@types/loader-utils": "^2.0.3",
     "@types/lodash": "^4.14.168",
-    "@types/node": "^14.14.22",
-    "@types/prismjs": "^1.16.2",
+    "@types/node": "^17.0.8",
     "@types/prompts": "^2.0.9",
     "@types/react": "^17.0.2",
     "@types/react-dev-utils": "^9.0.1",
-    "@types/react-helmet": "^6.0.0",
-    "@types/react-router-config": "^5.0.1",
     "@types/react-test-renderer": "^17.0.1",
     "@types/semver": "^7.1.0",
     "@types/shelljs": "^0.8.6",
-    "@types/wait-on": "^5.2.0",
-    "@types/webpack-dev-server": "^4.1.0",
-    "@typescript-eslint/eslint-plugin": "^5.4.0",
-    "@typescript-eslint/parser": "^5.4.0",
-    "concurrently": "^6.2.1",
+    "@typescript-eslint/eslint-plugin": "^5.8.1",
+    "@typescript-eslint/parser": "^5.8.1",
+    "concurrently": "^7.0.0",
     "cross-env": "^7.0.3",
+    "cspell": "^5.16.0",
     "eslint": "^8.2.0",
     "eslint-config-airbnb": "^19.0.0",
     "eslint-config-prettier": "^8.3.0",
     "eslint-plugin-header": "^3.1.1",
     "eslint-plugin-import": "^2.25.3",
+    "eslint-plugin-jest": "^25.7.0",
     "eslint-plugin-jsx-a11y": "^6.5.1",
     "eslint-plugin-react": "^7.27.0",
     "eslint-plugin-react-hooks": "^4.3.0",
     "glob": "^7.1.6",
-    "husky": "^5.0.9",
-    "is-ci": "^3.0.0",
+    "husky": "^7.0.4",
+    "image-size": "^1.0.1",
     "jest": "^26.6.3",
-    "lerna": "^3.22.1",
+    "lerna": "^4.0.0",
     "lerna-changelog": "^1.0.1",
-    "lint-staged": "^10.5.4",
-    "netlify-cli": "^2.58.0",
+    "lint-staged": "^12.1.7",
+    "netlify-cli": "^8.0.5",
     "nodemon": "^2.0.13",
-    "npm-run-all": "^4.1.5",
-    "prettier": "^2.4.1",
+    "prettier": "^2.5.1",
     "react": "^17.0.1",
     "react-dom": "^17.0.1",
     "react-test-renderer": "^17.0.2",
     "rimraf": "^3.0.2",
-    "serve": "^12.0.1",
-    "stylelint": "^13.10.0",
+    "sharp": "^0.29.1",
+    "stylelint": "^14.3.0",
+    "stylelint-config-prettier": "^9.0.3",
+    "stylelint-config-standard": "^24.0.0",
     "tslib": "^2.3.1",
     "typescript": "^4.5.2"
   },
   "lint-staged": {
-    "*.{js,jsx,ts,tsx}": [
-      "eslint --fix",
-      "prettier --config .prettierrc --write"
+    "*.{js,jsx,ts,tsx,mjs}": [
+      "eslint --fix"
     ],
-    "*.{md,mdx}": [
-      "prettier --config .prettierrc --write"
+    "*.css": [
+      "stylelint --allow-empty-input --fix"
+    ],
+    "*": [
+      "prettier --ignore-unknown --write",
+      "cspell --no-must-find-files --no-progress"
     ]
   },
   "engines": {

packages/create-docusaurus/.npmignore

@@ -0,0 +1,8 @@
+copyUntypedFiles.mjs
+.tsbuildinfo
+__tests__
+node_modules
+
+# Files in the templates need to stay
+/tsconfig*
+/src

packages/create-docusaurus/bin/index.js

@@ -6,7 +6,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const chalk = require('chalk');
+// @ts-check
+
+const logger = require('@docusaurus/logger').default;
 const semver = require('semver');
 const path = require('path');
 const program = require('commander');
@@ -14,19 +16,15 @@ const {default: init} = require('../lib');
 const requiredVersion = require('../package.json').engines.node;
 
 if (!semver.satisfies(process.version, requiredVersion)) {
-  console.log(
-    chalk.red(`\nMinimum Node.js version not met :)`) +
-      chalk.yellow(
-        `\nYou are using Node.js ${process.version}, Requirement: Node.js ${requiredVersion}.\n`,
-      ),
-  );
+  logger.error('Minimum Node.js version not met :(');
+  logger.info`You are using Node.js number=${process.version}, Requirement: Node.js number=${requiredVersion}.`;
   process.exit(1);
 }
 
 function wrapCommand(fn) {
   return (...args) =>
     fn(...args).catch((err) => {
-      console.error(chalk.red(err.stack));
+      logger.error(err.stack);
       process.exitCode = 1;
     });
 }
@@ -58,8 +56,7 @@ program
 
 program.arguments('<command>').action((cmd) => {
   program.outputHelp();
-  console.log(`  ${chalk.red(`\n  Unknown command ${chalk.yellow(cmd)}.`)}`);
-  console.log();
+  logger.error`Unknown command code=${cmd}.`;
 });
 
 program.parse(process.argv);

packages/create-docusaurus/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-docusaurus",
-  "version": "2.0.0-beta.9",
+  "version": "2.0.0-beta.14",
   "description": "Create Docusaurus apps easily.",
   "repository": {
     "type": "git",
@@ -15,15 +15,13 @@
     "build": "tsc",
     "watch": "tsc --watch"
   },
-  "bin": {
-    "create-docusaurus": "bin/index.js"
-  },
+  "bin": "bin/index.js",
   "publishConfig": {
     "access": "public"
   },
   "license": "MIT",
   "dependencies": {
-    "chalk": "^4.1.2",
+    "@docusaurus/logger": "2.0.0-beta.14",
     "commander": "^5.1.0",
     "fs-extra": "^10.0.0",
     "lodash": "^4.17.20",

packages/create-docusaurus/src/index.ts

@@ -5,10 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import chalk from 'chalk';
+import logger from '@docusaurus/logger';
 import fs from 'fs-extra';
 import {execSync} from 'child_process';
-import prompts, {Choice} from 'prompts';
+import prompts, {type Choice} from 'prompts';
 import path from 'path';
 import shell from 'shelljs';
 import {kebabCase, sortBy} from 'lodash';
@@ -35,7 +35,7 @@ async function updatePkg(pkgPath: string, obj: Record<string, unknown>) {
   const pkg = JSON.parse(content);
   const newPkg = Object.assign(pkg, obj);
 
-  await fs.outputFile(pkgPath, JSON.stringify(newPkg, null, 2));
+  await fs.outputFile(pkgPath, `${JSON.stringify(newPkg, null, 2)}\n`);
 }
 
 function readTemplates(templatesDir: string) {
@@ -131,12 +131,14 @@ export default async function init(
   }
 
   if (!name) {
-    throw new Error(chalk.red('A website name is required.'));
+    logger.error('A website name is required.');
+    process.exit(1);
   }
 
   const dest = path.resolve(rootDir, name);
   if (fs.existsSync(dest)) {
-    throw new Error(`Directory already exists at "${dest}"!`);
+    logger.error`Directory already exists at path=${dest}!`;
+    process.exit(1);
   }
 
   let template = reqTemplate;
@@ -171,10 +173,10 @@ export default async function init(
         if (url && isValidGitRepoUrl(url)) {
           return true;
         }
-        return chalk.red(`Invalid repository URL`);
+        return logger.red('Invalid repository URL');
       },
-      message:
-        'Enter a repository URL from GitHub, Bitbucket, GitLab, or any other public repo.\n(e.g: https://github.com/ownerName/repoName.git)',
+      message: logger.interpolate`Enter a repository URL from GitHub, Bitbucket, GitLab, or any other public repo.
+(e.g: path=${'https://github.com/ownerName/repoName.git'})`,
     });
     template = repoPrompt.gitRepoUrl;
   } else if (template === 'Local template') {
@@ -187,11 +189,11 @@ export default async function init(
           if (fs.existsSync(fullDir)) {
             return true;
           }
-          return chalk.red(
-            `The path ${chalk.magenta(fullDir)} does not exist.`,
+          return logger.red(
+            logger.interpolate`path=${fullDir} does not exist.`,
           );
         }
-        return chalk.red('Please enter a valid path.');
+        return logger.red('Please enter a valid path.');
       },
       message:
         'Enter a local folder path, relative to the current working directory.',
@@ -200,37 +202,34 @@ export default async function init(
   }
 
   if (!template) {
-    throw new Error('Template should not be empty');
+    logger.error('Template should not be empty');
+    process.exit(1);
   }
 
-  console.log(`
-${chalk.cyan('Creating new Docusaurus project...')}
-`);
+  logger.info('Creating new Docusaurus project...');
 
   if (isValidGitRepoUrl(template)) {
-    console.log(`Cloning Git template ${chalk.cyan(template)}...`);
+    logger.info`Cloning Git template path=${template}...`;
     if (
       shell.exec(`git clone --recursive ${template} ${dest}`, {silent: true})
         .code !== 0
     ) {
-      throw new Error(chalk.red(`Cloning Git template ${template} failed!`));
+      logger.error`Cloning Git template name=${template} failed!`;
+      process.exit(1);
     }
   } else if (templates.includes(template)) {
     // Docusaurus templates.
     if (useTS) {
       if (!hasTS(template)) {
-        throw new Error(
-          `Template ${template} doesn't provide the Typescript variant.`,
-        );
+        logger.error`Template name=${template} doesn't provide the Typescript variant.`;
+        process.exit(1);
       }
       template = `${template}${TypeScriptTemplateSuffix}`;
     }
     try {
       await copyTemplate(templatesDir, template, dest);
     } catch (err) {
-      console.log(
-        `Copying Docusaurus template ${chalk.cyan(template)} failed!`,
-      );
+      logger.error`Copying Docusaurus template name=${template} failed!`;
       throw err;
     }
   } else if (fs.existsSync(path.resolve(process.cwd(), template))) {
@@ -238,11 +237,12 @@ ${chalk.cyan('Creating new Docusaurus project...')}
     try {
       await fs.copy(templateDir, dest);
     } catch (err) {
-      console.log(`Copying local template ${templateDir} failed!`);
+      logger.error`Copying local template path=${templateDir} failed!`;
       throw err;
     }
   } else {
-    throw new Error('Invalid template.');
+    logger.error('Invalid template.');
+    process.exit(1);
   }
 
   // Update package.json info.
@@ -253,7 +253,7 @@ ${chalk.cyan('Creating new Docusaurus project...')}
       private: true,
     });
   } catch (err) {
-    console.log(chalk.red('Failed to update package.json.'));
+    logger.error('Failed to update package.json.');
     throw err;
   }
 
@@ -269,54 +269,49 @@ ${chalk.cyan('Creating new Docusaurus project...')}
   }
 
   const pkgManager = useYarn ? 'yarn' : 'npm';
+  // Display the most elegant way to cd.
+  const cdpath = path.relative('.', dest);
   if (!cliOptions.skipInstall) {
-    console.log(`Installing dependencies with ${chalk.cyan(pkgManager)}...`);
-
-    try {
-      // Use force coloring the output, since the command is invoked by shelljs, which is not the interactive shell
-      shell.exec(
-        `cd "${name}" && ${useYarn ? 'yarn' : 'npm install --color always'}`,
-        {
-          env: {
-            ...process.env,
-            ...(supportsColor.stdout ? {FORCE_COLOR: '1'} : {}),
-          },
+    shell.cd(dest);
+    logger.info`Installing dependencies with name=${pkgManager}...`;
+    if (
+      shell.exec(useYarn ? 'yarn' : 'npm install --color always', {
+        env: {
+          ...process.env,
+          // Force coloring the output, since the command is invoked by shelljs, which is not the interactive shell
+          ...(supportsColor.stdout ? {FORCE_COLOR: '1'} : {}),
         },
-      );
-    } catch (err) {
-      console.log(chalk.red('Installation failed.'));
-      throw err;
+      }).code !== 0
+    ) {
+      logger.error('Dependency installation failed.');
+      logger.info`The site directory has already been created, and you can retry by typing:
+
+  code=${`cd ${cdpath}`}
+  code=${`${pkgManager} install`}`;
+      process.exit(0);
     }
   }
-  console.log();
 
-  // Display the most elegant way to cd.
-  const cdpath =
-    path.join(process.cwd(), name) === dest
-      ? name
-      : path.relative(process.cwd(), name);
+  logger.success`Created path=${cdpath}.`;
+  logger.info`Inside that directory, you can run several commands:
 
-  console.log(`
-Successfully created "${chalk.cyan(cdpath)}".
-Inside that directory, you can run several commands:
-
-  ${chalk.cyan(`${pkgManager} start`)}
+  code=${`${pkgManager} start`}
     Starts the development server.
 
-  ${chalk.cyan(`${pkgManager} ${useYarn ? '' : 'run '}build`)}
+  code=${`${pkgManager} ${useYarn ? '' : 'run '}build`}
     Bundles your website into static files for production.
 
-  ${chalk.cyan(`${pkgManager} ${useYarn ? '' : 'run '}serve`)}
+  code=${`${pkgManager} ${useYarn ? '' : 'run '}serve`}
     Serves the built website locally.
 
-  ${chalk.cyan(`${pkgManager} deploy`)}
+  code=${`${pkgManager} deploy`}
     Publishes the website to GitHub pages.
 
 We recommend that you begin by typing:
 
-  ${chalk.cyan('cd')} ${cdpath}
-  ${chalk.cyan(`${pkgManager} start`)}
+  code=${`cd ${cdpath}`}
+  code=${`${pkgManager} start`}
 
 Happy building awesome websites!
-`);
+`;
 }

packages/create-docusaurus/templates/classic-typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-2-classic-typescript-template",
-  "version": "2.0.0-beta.9",
+  "version": "2.0.0-beta.14",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
@@ -15,19 +15,16 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.9",
-    "@docusaurus/preset-classic": "2.0.0-beta.9",
+    "@docusaurus/core": "2.0.0-beta.14",
+    "@docusaurus/preset-classic": "2.0.0-beta.14",
     "@mdx-js/react": "^1.6.21",
-    "@svgr/webpack": "^5.5.0",
     "clsx": "^1.1.1",
-    "file-loader": "^6.2.0",
     "prism-react-renderer": "^1.2.1",
     "react": "^17.0.1",
-    "react-dom": "^17.0.1",
-    "url-loader": "^4.1.1"
+    "react-dom": "^17.0.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.9",
+    "@docusaurus/module-type-aliases": "2.0.0-beta.14",
     "@tsconfig/docusaurus": "^1.0.4",
     "typescript": "^4.5.2"
   },

packages/create-docusaurus/templates/classic-typescript/src/components/HomepageFeatures.tsx

@@ -1,9 +1,4 @@
-/**
- * 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 useBaseUrl from '@docusaurus/useBaseUrl';
 import React from 'react';
 import clsx from 'clsx';
 import styles from './HomepageFeatures.module.css';
@@ -51,7 +46,11 @@ function Feature({title, image, description}: FeatureItem) {
   return (
     <div className={clsx('col col--4')}>
       <div className="text--center">
-        <img className={styles.featureSvg} alt={title} src={image} />
+        <img
+          className={styles.featureSvg}
+          alt={title}
+          src={useBaseUrl(image)}
+        />
       </div>
       <div className="text--center padding-horiz--md">
         <h3>{title}</h3>

packages/create-docusaurus/templates/classic/docusaurus.config.js

@@ -18,19 +18,19 @@ const config = {
 
   presets: [
     [
-      '@docusaurus/preset-classic',
+      'classic',
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
         docs: {
           sidebarPath: require.resolve('./sidebars.js'),
           // Please change this to your repo.
-          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
+          editUrl: 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
         },
         blog: {
           showReadingTime: true,
           // Please change this to your repo.
           editUrl:
-            'https://github.com/facebook/docusaurus/edit/main/website/blog/',
+            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
         },
         theme: {
           customCss: require.resolve('./src/css/custom.css'),

packages/create-docusaurus/templates/classic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-2-classic-template",
-  "version": "2.0.0-beta.9",
+  "version": "2.0.0-beta.14",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
@@ -14,16 +14,13 @@
     "write-heading-ids": "docusaurus write-heading-ids"
   },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.9",
-    "@docusaurus/preset-classic": "2.0.0-beta.9",
+    "@docusaurus/core": "2.0.0-beta.14",
+    "@docusaurus/preset-classic": "2.0.0-beta.14",
     "@mdx-js/react": "^1.6.21",
-    "@svgr/webpack": "^5.5.0",
     "clsx": "^1.1.1",
-    "file-loader": "^6.2.0",
     "prism-react-renderer": "^1.2.1",
     "react": "^17.0.1",
-    "react-dom": "^17.0.1",
-    "url-loader": "^4.1.1"
+    "react-dom": "^17.0.1"
   },
   "browserslist": {
     "production": [

packages/create-docusaurus/templates/classic/src/css/custom.css

@@ -6,16 +6,27 @@
 
 /* You can override the default Infima variables here. */
 :root {
-  --ifm-color-primary: #25c2a0;
-  --ifm-color-primary-dark: rgb(33, 175, 144);
-  --ifm-color-primary-darker: rgb(31, 165, 136);
-  --ifm-color-primary-darkest: rgb(26, 136, 112);
-  --ifm-color-primary-light: rgb(70, 203, 174);
-  --ifm-color-primary-lighter: rgb(102, 212, 189);
-  --ifm-color-primary-lightest: rgb(146, 224, 208);
+  --ifm-color-primary: #2e8555;
+  --ifm-color-primary-dark: #29784c;
+  --ifm-color-primary-darker: #277148;
+  --ifm-color-primary-darkest: #205d3b;
+  --ifm-color-primary-light: #33925d;
+  --ifm-color-primary-lighter: #359962;
+  --ifm-color-primary-lightest: #3cad6e;
   --ifm-code-font-size: 95%;
 }
 
+/* For readability concerns, you should choose a lighter palette in dark mode. */
+html[data-theme='dark'] {
+  --ifm-color-primary: #25c2a0;
+  --ifm-color-primary-dark: #21af90;
+  --ifm-color-primary-darker: #1fa588;
+  --ifm-color-primary-darkest: #1a8870;
+  --ifm-color-primary-light: #29d5b0;
+  --ifm-color-primary-lighter: #32d8b4;
+  --ifm-color-primary-lightest: #4fddbf;
+}
+
 .docusaurus-highlight-code-line {
   background-color: rgba(0, 0, 0, 0.1);
   display: block;

packages/create-docusaurus/templates/facebook/.eslintrc.js

@@ -52,7 +52,6 @@ module.exports = {
         ' ',
       ],
     ],
-    'react/jsx-closing-bracket-location': OFF, // Conflicts with Prettier.
     'react/jsx-filename-extension': OFF,
     'react-hooks/rules-of-hooks': ERROR,
     'react/prop-types': OFF, // PropTypes aren't used much these days.

packages/create-docusaurus/templates/facebook/.prettierrc

@@ -1,7 +1,7 @@
 {
   "arrowParens": "always",
+  "bracketSameLine": true,
   "bracketSpacing": false,
-  "jsxBracketSameLine": true,
   "printWidth": 80,
   "proseWrap": "never",
   "singleQuote": true,

packages/create-docusaurus/templates/facebook/docusaurus.config.js

@@ -23,19 +23,20 @@ const config = {
 
   presets: [
     [
-      '@docusaurus/preset-classic',
+      'classic',
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
         docs: {
           sidebarPath: require.resolve('./sidebars.js'),
           // Please change this to your repo.
-          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
+          editUrl:
+            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
         },
         blog: {
           showReadingTime: true,
           // Please change this to your repo.
           editUrl:
-            'https://github.com/facebook/docusaurus/edit/main/website/blog/',
+            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
         },
         theme: {
           customCss: require.resolve('./src/css/custom.css'),

packages/create-docusaurus/templates/facebook/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-2-facebook-template",
-  "version": "2.0.0-beta.9",
+  "version": "2.0.0-beta.14",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
@@ -12,24 +12,21 @@
     "serve": "docusaurus serve",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
-    "ci": "yarn lint && yarn prettier:diff",
+    "ci": "yarn lint && yarn format:diff",
     "lint": "eslint --cache \"**/*.js\" && stylelint \"**/*.css\"",
-    "prettier": "prettier --config .prettierrc --write \"**/*.{js,jsx,ts,tsx,md,mdx}\"",
-    "prettier:diff": "prettier --config .prettierrc --list-different \"**/*.{js,jsx,ts,tsx,md,mdx}\""
+    "format": "prettier --config .prettierrc --write \"**/*.{js,jsx,ts,tsx,md,mdx}\"",
+    "format:diff": "prettier --config .prettierrc --list-different \"**/*.{js,jsx,ts,tsx,md,mdx}\""
   },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.9",
-    "@docusaurus/preset-classic": "2.0.0-beta.9",
+    "@docusaurus/core": "2.0.0-beta.14",
+    "@docusaurus/preset-classic": "2.0.0-beta.14",
     "@mdx-js/react": "^1.6.21",
-    "@svgr/webpack": "^5.5.0",
     "clsx": "^1.1.1",
-    "file-loader": "^6.2.0",
     "react": "^17.0.1",
-    "react-dom": "^17.0.1",
-    "url-loader": "^4.1.1"
+    "react-dom": "^17.0.1"
   },
   "devDependencies": {
-    "@babel/eslint-parser": "^7.15.7",
+    "@babel/eslint-parser": "^7.16.3",
     "eslint": "^8.2.0",
     "eslint-config-airbnb": "^19.0.0",
     "eslint-config-prettier": "^8.3.0",
@@ -38,7 +35,7 @@
     "eslint-plugin-jsx-a11y": "^6.5.1",
     "eslint-plugin-react": "^7.27.0",
     "eslint-plugin-react-hooks": "^4.3.0",
-    "prettier": "^2.4.1",
+    "prettier": "^2.5.1",
     "stylelint": "^13.2.1"
   },
   "browserslist": {

packages/create-docusaurus/templates/facebook/src/css/custom.css

@@ -15,16 +15,27 @@
 
 /* You can override the default Infima variables here. */
 :root {
-  --ifm-color-primary: #25c2a0;
-  --ifm-color-primary-dark: rgb(33, 175, 144);
-  --ifm-color-primary-darker: rgb(31, 165, 136);
-  --ifm-color-primary-darkest: rgb(26, 136, 112);
-  --ifm-color-primary-light: rgb(70, 203, 174);
-  --ifm-color-primary-lighter: rgb(102, 212, 189);
-  --ifm-color-primary-lightest: rgb(146, 224, 208);
+  --ifm-color-primary: #2e8555;
+  --ifm-color-primary-dark: #29784c;
+  --ifm-color-primary-darker: #277148;
+  --ifm-color-primary-darkest: #205d3b;
+  --ifm-color-primary-light: #33925d;
+  --ifm-color-primary-lighter: #359962;
+  --ifm-color-primary-lightest: #3cad6e;
   --ifm-code-font-size: 95%;
 }
 
+/* For readability concerns, you should choose a lighter palette in dark mode. */
+html[data-theme='dark'] {
+  --ifm-color-primary: #25c2a0;
+  --ifm-color-primary-dark: #21af90;
+  --ifm-color-primary-darker: #1fa588;
+  --ifm-color-primary-darkest: #1a8870;
+  --ifm-color-primary-light: #29d5b0;
+  --ifm-color-primary-lighter: #32d8b4;
+  --ifm-color-primary-lightest: #4fddbf;
+}
+
 .docusaurus-highlight-code-line {
   background-color: rgb(72, 77, 91);
   display: block;

packages/create-docusaurus/templates/shared/docs/intro.md

@@ -12,24 +12,36 @@ Get started by **creating a new site**.
 
 Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
 
+### What you'll need
+
+- [Node.js](https://nodejs.org/en/download/) version 14 or above:
+  - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
+
 ## Generate a new site
 
-Generate a new Docusaurus site using the **classic template**:
+Generate a new Docusaurus site using the **classic template**.
 
-```shell
+The classic template will automatically be added to your project after you run the command:
+
+```bash
 npm init docusaurus@latest my-website classic
 ```
 
+You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
+
+The command also installs all necessary dependencies you need to run Docusaurus.
+
 ## Start your site
 
 Run the development server:
 
-```shell
+```bash
 cd my-website
-
-npx docusaurus start
+npm run start
 ```
 
-Your site starts at `http://localhost:3000`.
+The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
 
-Open `docs/intro.md` and edit some lines: the site **reloads automatically** and displays your changes.
+The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
+
+Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.

packages/docusaurus-cssnano-preset/.npmignore

@@ -0,0 +1 @@
+__tests__

packages/docusaurus-cssnano-preset/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/cssnano-preset",
-  "version": "2.0.0-beta.9",
+  "version": "2.0.0-beta.14",
   "description": "Advanced cssnano preset for maximum optimization.",
   "main": "index.js",
   "license": "MIT",

packages/docusaurus-cssnano-preset/src/remove-overridden-custom-properties/__tests__/__fixtures__/important_rule.css

@@ -1,3 +1,4 @@
+/* stylelint-disable docusaurus/copyright-header, declaration-block-no-duplicate-custom-properties */
 :root {
   --color-primary: red;
   --color-secondary: green;

packages/docusaurus-cssnano-preset/src/remove-overridden-custom-properties/__tests__/__fixtures__/normal.css

@@ -0,0 +1,13 @@
+/* stylelint-disable docusaurus/copyright-header, declaration-block-no-duplicate-custom-properties */
+:root {
+  --color-primary: red;
+  --color-primary: red;
+  --color-secondary: green;
+  --color-primary: blue;
+  --color-header: gray;
+}
+
+.non-root {
+  --color-primary: red;
+  --color-primary: red;
+}

packages/docusaurus-cssnano-preset/src/remove-overridden-custom-properties/__tests__/__snapshots__/index.test.js.snap

@@ -1,16 +1,23 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`remove-overridden-custom-properties overridden custom properties should be removed 1`] = `
-":root {
+"/* stylelint-disable docusaurus/copyright-header, declaration-block-no-duplicate-custom-properties */
+:root {
   --color-secondary: green;
   --color-primary: blue;
   --color-header: gray;
 }
+
+.non-root {
+  --color-primary: red;
+  --color-primary: red;
+}
 "
 `;
 
 exports[`remove-overridden-custom-properties overridden custom properties with \`!important\` rule should not be removed 1`] = `
-":root {
+"/* stylelint-disable docusaurus/copyright-header, declaration-block-no-duplicate-custom-properties */
+:root {
   --color-primary: blue;
   --color-header: gray !important;
   --color-secondary: yellow !important;

packages/docusaurus-cssnano-preset/src/remove-overridden-custom-properties/__tests__/fixtures/normal.css

@@ -1,7 +0,0 @@
-:root {
-  --color-primary: red;
-  --color-primary: red;
-  --color-secondary: green;
-  --color-primary: blue;
-  --color-header: gray;
-}

packages/docusaurus-cssnano-preset/src/remove-overridden-custom-properties/__tests__/index.test.js

@@ -12,7 +12,7 @@ const postCssRemoveOverriddenCustomProperties = require('../index');
 
 const processFixture = (name) => {
   const input = vfile.readSync(
-    path.join(__dirname, 'fixtures', `${name}.css`),
+    path.join(__dirname, '__fixtures__', `${name}.css`),
     'utf8',
   );
   const output = postcss([postCssRemoveOverriddenCustomProperties]).process(

packages/docusaurus-cssnano-preset/src/remove-overridden-custom-properties/index.js

@@ -22,8 +22,9 @@ module.exports = function creator() {
         return;
       }
 
-      const sameProperties =
-        decl.parent.nodes.filter((n) => n.prop === decl.prop) || [];
+      const sameProperties = decl.parent.nodes.filter(
+        (n) => n.prop === decl.prop,
+      );
       const hasImportantProperties = sameProperties.some((p) =>
         Object.prototype.hasOwnProperty.call(p, 'important'),
       );

packages/docusaurus-logger/.npmignore

@@ -0,0 +1,4 @@
+copyUntypedFiles.mjs
+.tsbuildinfo
+tsconfig*
+__tests__

packages/docusaurus-logger/README.md

@@ -0,0 +1,44 @@
+# `@docusaurus/logger`
+
+An encapsulated logger for semantically formatting console messages.
+
+## APIs
+
+It exports a single object as default export: `logger`. `logger` has the following properties:
+
+- Some useful colors.
+- Formatters. These functions have the same signature as the formatters of `picocolors`. Note that their implementations are not guaranteed. You should only care about their semantics.
+  - `path`: formats a file path or URL.
+  - `id`: formats an identifier.
+  - `code`: formats a code snippet.
+  - `subdue`: subdues the text.
+  - `num`: formats a number.
+- The `interpolate` function. It is a template literal tag.
+- Logging functions. All logging functions can both be used as functions (in which it has the same usage as `console.log`) or template literal tags.
+  - `info`: prints information.
+  - `warn`: prints a warning that should be payed attention to.
+  - `error`: prints an error (not necessarily halting the program) that signals significant problems.
+  - `success`: prints a success message.
+
+### Using the template literal tag
+
+The template literal tag evaluates the template and expressions embedded. `interpolate` returns a new string, while other logging functions prints it. Below is a typical usage:
+
+```js
+logger.info`Hello name=${name}! You have number=${money} dollars. Here are the ${
+  items.length > 1 ? 'items' : 'item'
+} on the shelf: ${items}
+To buy anything, enter code=${'buy x'} where code=${'x'} is the item's name; to quit, press code=${'Ctrl + C'}.`;
+```
+
+An embedded expression is optionally preceded by a flag in the form `%[a-z]+` (a percentage sign followed by a few lowercase letters). If it's not preceded by any flag, it's printed out as-is. Otherwise, it's formatted with one of the formatters:
+
+- `path=`: `path`
+- `name=`: `id`
+- `code=`: `code`
+- `subdue=`: `subdue`
+- `number=`: `num`
+
+If the expression is an array, it's formatted by `` `\n- ${array.join('\n- ')}\n` `` (note it automatically gets a leading line end). Each member is formatted by itself and the bullet is not formatted. So you would see the above message printed as:
+
+![demo](./demo.png)

packages/docusaurus-logger/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@docusaurus/logger",
+  "version": "2.0.0-beta.14",
+  "description": "An encapsulated logger for semantically formatting console messages.",
+  "main": "./lib/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/facebook/docusaurus.git",
+    "directory": "packages/docusaurus-logger"
+  },
+  "bugs": {
+    "url": "https://github.com/facebook/docusaurus/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "tslib": "^2.3.1"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "devDependencies": {
+    "@types/supports-color": "^8.1.1"
+  }
+}

packages/docusaurus-logger/src/__mocks__/chalk.js

@@ -5,8 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {createContext} from 'react';
+const chalk = require('chalk');
 
-const UserPreferencesContext = createContext(undefined);
-
-export default UserPreferencesContext;
+// Force coloring the output even in CI
+module.exports = new chalk.Instance({level: 3});

packages/docusaurus-logger/src/__tests__/index.test.ts

@@ -0,0 +1,177 @@
+/**
+ * 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 logger from '../index';
+
+describe('formatters', () => {
+  test('path', () => {
+    expect(logger.path('hey')).toMatchInlineSnapshot(`"hey"`);
+  });
+  test('id', () => {
+    expect(logger.name('hey')).toMatchInlineSnapshot(`"hey"`);
+  });
+  test('code', () => {
+    expect(logger.code('hey')).toMatchInlineSnapshot(`"\`hey\`"`);
+  });
+  test('subdue', () => {
+    expect(logger.subdue('hey')).toMatchInlineSnapshot(`"hey"`);
+  });
+});
+
+describe('interpolate', () => {
+  test('should format text with variables & arrays', () => {
+    const name = 'Josh';
+    const items = [1, 'hi', 'Hmmm'];
+    expect(logger.interpolate`Hello ${name}! Here are your goodies:${items}`)
+      .toMatchInlineSnapshot(`
+      "Hello Josh! Here are your goodies:
+      - 1
+      - hi
+      - Hmmm"
+    `);
+  });
+  test('should recognize valid flags', () => {
+    expect(
+      logger.interpolate`The package at path=${'packages/docusaurus'} has number=${10} files. name=${'Babel'} is exported here subdue=${'(as a preset)'} that you can with code=${"require.resolve('@docusaurus/core/lib/babel/preset')"}`,
+    ).toMatchInlineSnapshot(
+      `"The package at packages/docusaurus has 10 files. Babel is exported here (as a preset) that you can with \`require.resolve('@docusaurus/core/lib/babel/preset')\`"`,
+    );
+  });
+  test('should interpolate arrays with flags', () => {
+    expect(
+      logger.interpolate`The following commands are available:code=${[
+        'docusaurus start',
+        'docusaurus build',
+        'docusaurus deploy',
+      ]}`,
+    ).toMatchInlineSnapshot(`
+      "The following commands are available:
+      - \`docusaurus start\`
+      - \`docusaurus build\`
+      - \`docusaurus deploy\`"
+    `);
+  });
+  test('should print detached flags as-is', () => {
+    expect(
+      logger.interpolate`You can use placeholders like code= ${'and it will'} be replaced with the succeeding arguments`,
+    ).toMatchInlineSnapshot(
+      `"You can use placeholders like code= and it will be replaced with the succeeding arguments"`,
+    );
+  });
+  test('should throw with bad flags', () => {
+    expect(
+      () =>
+        logger.interpolate`I mistyped this: cde=${'this code'} and I will be damned`,
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Bad Docusaurus logging message. This is likely an internal bug, please report it."`,
+    );
+  });
+});
+
+describe('info', () => {
+  const consoleMock = jest.spyOn(console, 'info').mockImplementation(() => {});
+  test('should print objects', () => {
+    logger.info({a: 1});
+    logger.info(undefined);
+    logger.info([1, 2, 3]);
+    logger.info(new Date(2021, 10, 13));
+    expect(consoleMock.mock.calls).toMatchInlineSnapshot(`
+      Array [
+        Array [
+          "[INFO] {\\"a\\":1}",
+        ],
+        Array [
+          "[INFO] undefined",
+        ],
+        Array [
+          "[INFO] 1,2,3",
+        ],
+        Array [
+          "[INFO] Sat Nov 13 2021 00:00:00 GMT+0000 (Coordinated Universal Time)",
+        ],
+      ]
+    `);
+  });
+});
+
+describe('warn', () => {
+  const consoleMock = jest.spyOn(console, 'warn').mockImplementation(() => {});
+  test('should print objects', () => {
+    logger.warn({a: 1});
+    logger.warn(undefined);
+    logger.warn([1, 2, 3]);
+    logger.warn(new Date(2021, 10, 13));
+    expect(consoleMock.mock.calls).toMatchInlineSnapshot(`
+      Array [
+        Array [
+          "[WARNING] {\\"a\\":1}",
+        ],
+        Array [
+          "[WARNING] undefined",
+        ],
+        Array [
+          "[WARNING] 1,2,3",
+        ],
+        Array [
+          "[WARNING] Sat Nov 13 2021 00:00:00 GMT+0000 (Coordinated Universal Time)",
+        ],
+      ]
+    `);
+  });
+});
+
+describe('error', () => {
+  const consoleMock = jest.spyOn(console, 'error').mockImplementation(() => {});
+  test('should print objects', () => {
+    logger.error({a: 1});
+    logger.error(undefined);
+    logger.error([1, 2, 3]);
+    logger.error(new Date(2021, 10, 13));
+    expect(consoleMock.mock.calls).toMatchInlineSnapshot(`
+      Array [
+        Array [
+          "[ERROR] {\\"a\\":1}",
+        ],
+        Array [
+          "[ERROR] undefined",
+        ],
+        Array [
+          "[ERROR] 1,2,3",
+        ],
+        Array [
+          "[ERROR] Sat Nov 13 2021 00:00:00 GMT+0000 (Coordinated Universal Time)",
+        ],
+      ]
+    `);
+  });
+});
+
+describe('success', () => {
+  const consoleMock = jest.spyOn(console, 'log').mockImplementation(() => {});
+  test('should print objects', () => {
+    logger.success({a: 1});
+    logger.success(undefined);
+    logger.success([1, 2, 3]);
+    logger.success(new Date(2021, 10, 13));
+    expect(consoleMock.mock.calls).toMatchInlineSnapshot(`
+      Array [
+        Array [
+          "[SUCCESS] {\\"a\\":1}",
+        ],
+        Array [
+          "[SUCCESS] undefined",
+        ],
+        Array [
+          "[SUCCESS] 1,2,3",
+        ],
+        Array [
+          "[SUCCESS] Sat Nov 13 2021 00:00:00 GMT+0000 (Coordinated Universal Time)",
+        ],
+      ]
+    `);
+  });
+});

packages/docusaurus-logger/src/index.ts

@@ -0,0 +1,141 @@
+/**
+ * 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 chalk, {type Chalk} from 'chalk';
+
+type InterpolatableValue = string | number | (string | number)[];
+
+const path = (msg: unknown): string => chalk.cyan(chalk.underline(msg));
+const name = (msg: unknown): string => chalk.blue(chalk.bold(msg));
+const code = (msg: unknown): string => chalk.cyan(`\`${msg}\``);
+const subdue: Chalk = chalk.gray;
+const num: Chalk = chalk.yellow;
+
+function interpolate(
+  msgs: TemplateStringsArray,
+  ...values: InterpolatableValue[]
+): string {
+  let res = '';
+  values.forEach((value, idx) => {
+    const flag = msgs[idx].match(/[a-z]+=$/);
+    res += msgs[idx].replace(/[a-z]+=$/, '');
+    const format = (function () {
+      if (!flag) {
+        return (a: string | number) => a;
+      }
+      switch (flag[0]) {
+        case 'path=':
+          return path;
+        case 'number=':
+          return num;
+        case 'name=':
+          return name;
+        case 'subdue=':
+          return subdue;
+        case 'code=':
+          return code;
+        default:
+          throw new Error(
+            'Bad Docusaurus logging message. This is likely an internal bug, please report it.',
+          );
+      }
+    })();
+    res += Array.isArray(value)
+      ? `\n- ${value.map((v) => format(v)).join('\n- ')}`
+      : format(value);
+  });
+  res += msgs.slice(-1)[0];
+  return res;
+}
+
+function stringify(msg: unknown): string {
+  if (String(msg) === '[object Object]') {
+    return JSON.stringify(msg);
+  }
+  return String(msg);
+}
+
+function info(msg: unknown): void;
+function info(
+  msg: TemplateStringsArray,
+  ...values: [InterpolatableValue, ...InterpolatableValue[]]
+): void;
+function info(msg: unknown, ...values: InterpolatableValue[]): void {
+  console.info(
+    `${chalk.cyan(chalk.bold('[INFO]'))} ${
+      values.length === 0
+        ? stringify(msg)
+        : interpolate(msg as TemplateStringsArray, ...values)
+    }`,
+  );
+}
+function warn(msg: unknown): void;
+function warn(
+  msg: TemplateStringsArray,
+  ...values: [InterpolatableValue, ...InterpolatableValue[]]
+): void;
+function warn(msg: unknown, ...values: InterpolatableValue[]): void {
+  console.warn(
+    chalk.yellow(
+      `${chalk.bold('[WARNING]')} ${
+        values.length === 0
+          ? stringify(msg)
+          : interpolate(msg as TemplateStringsArray, ...values)
+      }`,
+    ),
+  );
+}
+function error(msg: unknown): void;
+function error(
+  msg: TemplateStringsArray,
+  ...values: [InterpolatableValue, ...InterpolatableValue[]]
+): void;
+function error(msg: unknown, ...values: InterpolatableValue[]): void {
+  console.error(
+    chalk.red(
+      `${chalk.bold('[ERROR]')} ${
+        values.length === 0
+          ? stringify(msg)
+          : interpolate(msg as TemplateStringsArray, ...values)
+      }`,
+    ),
+  );
+}
+function success(msg: unknown): void;
+function success(
+  msg: TemplateStringsArray,
+  ...values: [InterpolatableValue, ...InterpolatableValue[]]
+): void;
+function success(msg: unknown, ...values: InterpolatableValue[]): void {
+  console.log(
+    `${chalk.green(chalk.bold('[SUCCESS]'))} ${
+      values.length === 0
+        ? stringify(msg)
+        : interpolate(msg as TemplateStringsArray, ...values)
+    }`,
+  );
+}
+
+const logger = {
+  red: chalk.red,
+  yellow: chalk.yellow,
+  green: chalk.green,
+  bold: chalk.bold,
+  dim: chalk.dim,
+  path,
+  name,
+  code,
+  subdue,
+  num,
+  interpolate,
+  info,
+  warn,
+  error,
+  success,
+};
+
+export default logger;

packages/docusaurus-logger/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "incremental": true,
+    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "sourceMap": true,
+    "declarationMap": true,
+    "rootDir": "src",
+    "outDir": "lib"
+  }
+}

packages/docusaurus-mdx-loader/.npmignore

@@ -0,0 +1,4 @@
+copyUntypedFiles.mjs
+.tsbuildinfo
+tsconfig*
+__tests__

packages/docusaurus-mdx-loader/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/mdx-loader",
-  "version": "2.0.0-beta.9",
+  "version": "2.0.0-beta.14",
   "description": "Docusaurus Loader for MDX",
   "main": "lib/index.js",
   "types": "src/mdx-loader.d.ts",
@@ -18,27 +18,25 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@babel/parser": "^7.12.16",
-    "@babel/traverse": "^7.12.13",
-    "@docusaurus/core": "2.0.0-beta.9",
-    "@docusaurus/utils": "2.0.0-beta.9",
+    "@babel/parser": "^7.16.4",
+    "@babel/traverse": "^7.16.3",
+    "@docusaurus/logger": "2.0.0-beta.14",
+    "@docusaurus/utils": "2.0.0-beta.14",
     "@mdx-js/mdx": "^1.6.21",
-    "@mdx-js/react": "^1.6.21",
-    "chalk": "^4.1.2",
     "escape-html": "^1.0.3",
     "file-loader": "^6.2.0",
     "fs-extra": "^10.0.0",
-    "github-slugger": "^1.4.0",
-    "gray-matter": "^4.0.3",
+    "image-size": "^1.0.1",
     "mdast-util-to-string": "^2.0.0",
     "remark-emoji": "^2.1.0",
     "stringify-object": "^3.3.0",
+    "tslib": "^2.3.1",
     "unist-util-visit": "^2.0.2",
     "url-loader": "^4.1.1",
     "webpack": "^5.61.0"
   },
   "devDependencies": {
-    "@docusaurus/types": "2.0.0-beta.9",
+    "@docusaurus/types": "2.0.0-beta.14",
     "@types/escape-html": "^1.0.1",
     "@types/mdast": "^3.0.7",
     "@types/stringify-object": "^3.3.1",

packages/docusaurus-mdx-loader/src/index.ts

@@ -7,12 +7,13 @@
 
 import {readFile} from 'fs-extra';
 import mdx from '@mdx-js/mdx';
-import chalk from 'chalk';
+import logger from '@docusaurus/logger';
 import emoji from 'remark-emoji';
 import {
   parseFrontMatter,
   parseMarkdownContentTitle,
   escapePath,
+  getFileLoaderUtils,
 } from '@docusaurus/utils';
 import stringifyObject from 'stringify-object';
 import headings from './remark/headings';
@@ -20,7 +21,6 @@ import toc from './remark/toc';
 import unwrapMdxCodeBlocks from './remark/unwrapMdxCodeBlocks';
 import transformImage from './remark/transformImage';
 import transformLinks from './remark/transformLinks';
-import {getFileLoaderUtils} from '@docusaurus/core/lib/webpack/utils';
 import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
 import type {LoaderContext} from 'webpack';
 
@@ -124,12 +124,17 @@ export default async function mdxLoader(
     remarkPlugins: [
       ...(reqOptions.beforeDefaultRemarkPlugins || []),
       ...DEFAULT_OPTIONS.remarkPlugins,
-      [transformImage, {staticDirs: reqOptions.staticDirs, filePath}],
+      [
+        transformImage,
+        {
+          staticDirs: reqOptions.staticDirs,
+          siteDir: reqOptions.siteDir,
+        },
+      ],
       [
         transformLinks,
         {
           staticDirs: reqOptions.staticDirs,
-          filePath,
           siteDir: reqOptions.siteDir,
         },
       ],
@@ -151,7 +156,7 @@ export default async function mdxLoader(
   }
 
   // MDX partials are MDX files starting with _ or in a folder starting with _
-  // Partial are not expected to have an associated metadata file or frontmatter
+  // Partial are not expected to have an associated metadata file or front matter
   const isMDXPartial = options.isMDXPartial && options.isMDXPartial(filePath);
   if (isMDXPartial && hasFrontMatter) {
     const errorMessage = `Docusaurus MDX partial files should not contain FrontMatter.
@@ -164,7 +169,7 @@ ${JSON.stringify(frontMatter, null, 2)}`;
       if (shouldError) {
         return callback(new Error(errorMessage));
       } else {
-        console.warn(chalk.yellow(errorMessage));
+        logger.warn(errorMessage);
       }
     }
   }

packages/docusaurus-mdx-loader/src/remark/headings/index.ts

@@ -7,19 +7,16 @@
 
 /* Based on remark-slug (https://github.com/remarkjs/remark-slug) and gatsby-remark-autolink-headers (https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-remark-autolink-headers) */
 
-import {parseMarkdownHeadingId} from '@docusaurus/utils';
-import visit, {Visitor} from 'unist-util-visit';
+import {parseMarkdownHeadingId, createSlugger} from '@docusaurus/utils';
+import visit, {type Visitor} from 'unist-util-visit';
 import toString from 'mdast-util-to-string';
-import Slugger from 'github-slugger';
 import type {Transformer} from 'unified';
 import type {Parent} from 'unist';
 import type {Heading, Text} from 'mdast';
 
-const slugs = new Slugger();
-
 function headings(): Transformer {
   const transformer: Transformer = (ast) => {
-    slugs.reset();
+    const slugs = createSlugger();
 
     const visitor: Visitor<Heading> = (headingNode) => {
       const data = headingNode.data || (headingNode.data = {});
@@ -29,7 +26,7 @@ function headings(): Transformer {
       let {id} = properties;
 
       if (id) {
-        id = slugs.slug(id, true);
+        id = slugs.slug(id, {maintainCase: true});
       } else {
         const headingTextNodes = headingNode.children.filter(
           ({type}) => !['html', 'jsx'].includes(type),

packages/docusaurus-mdx-loader/src/remark/toc/__tests__/search.test.ts

@@ -32,7 +32,7 @@ test('should process all heading levels', async () => {
 
   `;
 
-  expect(await getHeadings(md)).toEqual([
+  await expect(getHeadings(md)).resolves.toEqual([
     {
       children: [
         {
@@ -126,7 +126,7 @@ some text
 
   `;
 
-  expect(await getHeadings(md)).toEqual([
+  await expect(getHeadings(md)).resolves.toEqual([
     {
       children: [
         {