chore: backport retro compatible commits for the Docusaurus v2.3 release

admin/new.docusaurus.io/package.json

@@ -1,6 +1,6 @@
 {
   "name": "new.docusaurus.io",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "private": true,
   "scripts": {
     "start": "npx --package netlify-cli netlify dev"

lerna.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.2.0",
+  "version": "2.3.0",
   "npmClient": "yarn",
   "useWorkspaces": true,
   "changelog": {

packages/create-docusaurus/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-docusaurus",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Create Docusaurus apps easily.",
   "type": "module",
   "repository": {
@@ -22,8 +22,8 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "2.2.0",
-    "@docusaurus/utils": "2.2.0",
+    "@docusaurus/logger": "2.3.0",
+    "@docusaurus/utils": "2.3.0",
     "commander": "^5.1.0",
     "fs-extra": "^10.1.0",
     "lodash": "^4.17.21",

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

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-2-classic-typescript-template",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
@@ -15,16 +15,16 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@docusaurus/core": "2.2.0",
-    "@docusaurus/preset-classic": "2.2.0",
+    "@docusaurus/core": "2.3.0",
+    "@docusaurus/preset-classic": "2.3.0",
     "@mdx-js/react": "^1.6.22",
     "clsx": "^1.2.1",
     "prism-react-renderer": "^1.3.5",
     "react": "^17.0.2",
     "react-dom": "^17.0.2"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.2.0",
+    "@docusaurus/module-type-aliases": "2.3.0",
     "@tsconfig/docusaurus": "^1.0.5",
     "typescript": "^4.7.4"
   },

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

@@ -8,17 +8,22 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula');
 const config = {
   title: 'My Site',
   tagline: 'Dinosaurs are cool',
+  favicon: 'img/favicon.ico',
+
+  // Set the production url of your site here
   url: 'https://your-docusaurus-test-site.com',
+  // Set the /<baseUrl>/ pathname under which your site is served
+  // For GitHub pages deployment, it is often '/<projectName>/'
   baseUrl: '/',
-  onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
-  favicon: 'img/favicon.ico',
 
   // GitHub pages deployment config.
   // If you aren't using GitHub pages, you don't need these.
   organizationName: 'facebook', // Usually your GitHub org/user name.
   projectName: 'docusaurus', // Usually your repo name.
 
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+
   // Even if you don't use internalization, you can use this field to set useful
   // metadata like html lang. For example, if your site is Chinese, you may want
   // to replace "en" with "zh-Hans".
@@ -56,6 +61,8 @@ const config = {
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
+      // Replace with your project's social card
+      image: 'img/docusaurus-social-card.jpg',
       navbar: {
         title: 'My Site',
         logo: {

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

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-2-classic-template",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
@@ -14,16 +14,16 @@
     "write-heading-ids": "docusaurus write-heading-ids"
   },
   "dependencies": {
-    "@docusaurus/core": "2.2.0",
-    "@docusaurus/preset-classic": "2.2.0",
+    "@docusaurus/core": "2.3.0",
+    "@docusaurus/preset-classic": "2.3.0",
     "@mdx-js/react": "^1.6.22",
     "clsx": "^1.2.1",
     "prism-react-renderer": "^1.3.5",
     "react": "^17.0.2",
     "react-dom": "^17.0.2"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.2.0"
+    "@docusaurus/module-type-aliases": "2.3.0"
   },
   "browserslist": {
     "production": [

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

@@ -13,17 +13,22 @@
 const config = {
   title: 'My Site',
   tagline: 'The tagline of my site',
+  favicon: 'img/favicon.ico',
+
+  // Set the production url of your site here
   url: 'https://your-docusaurus-test-site.com',
+  // Set the /<baseUrl>/ pathname under which your site is served
+  // For GitHub pages deployment, it is often '/<projectName>/'
   baseUrl: '/',
-  onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
-  favicon: 'img/favicon.ico',
 
   // GitHub pages deployment config.
   // If you aren't using GitHub pages, you don't need these.
   organizationName: 'facebook', // Usually your GitHub org/user name.
   projectName: 'docusaurus', // Usually your repo name.
 
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+
   presets: [
     [
       'classic',
@@ -53,6 +58,7 @@ const config = {
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
+      image: 'img/docusaurus-social-card.jpg',
       navbar: {
         title: 'My Meta Project',
         logo: {

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

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-2-facebook-template",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
@@ -18,8 +18,8 @@
     "format:diff": "prettier --config .prettierrc --list-different \"**/*.{js,jsx,ts,tsx,md,mdx}\""
   },
   "dependencies": {
-    "@docusaurus/core": "2.2.0",
-    "@docusaurus/preset-classic": "2.2.0",
+    "@docusaurus/core": "2.3.0",
+    "@docusaurus/preset-classic": "2.3.0",
     "@mdx-js/react": "^1.6.22",
     "clsx": "^1.2.1",
     "react": "^17.0.2",

packages/create-docusaurus/templates/shared/docs/tutorial-basics/markdown-features.mdx

@@ -51,7 +51,11 @@ You can use absolute paths to reference images in the static directory (`static/
 
 ![Docusaurus logo](/img/docusaurus.png)
 
-You can reference images relative to the current file as well, as shown in [the extra guides](../tutorial-extras/manage-docs-versions.md).
+You can reference images relative to the current file as well. This is particularly useful to colocate images close to the Markdown files using them:
+
+```md
+![Docusaurus logo](./img/docusaurus.png)
+```
 
 ## Code Blocks
 

packages/docusaurus-cssnano-preset/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/cssnano-preset",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Advanced cssnano preset for maximum optimization.",
   "main": "lib/index.js",
   "license": "MIT",

packages/docusaurus-logger/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/logger",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "An encapsulated logger for semantically formatting console messages.",
   "main": "./lib/index.js",
   "repository": {

packages/docusaurus-mdx-loader/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/mdx-loader",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Docusaurus Loader for MDX",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -20,8 +20,8 @@
   "dependencies": {
     "@babel/parser": "^7.18.8",
     "@babel/traverse": "^7.18.8",
-    "@docusaurus/logger": "2.2.0",
-    "@docusaurus/utils": "2.2.0",
+    "@docusaurus/logger": "2.3.0",
+    "@docusaurus/utils": "2.3.0",
     "@mdx-js/mdx": "^1.6.22",
     "escape-html": "^1.0.3",
     "file-loader": "^6.2.0",
@@ -37,10 +37,9 @@
     "webpack": "^5.73.0"
   },
   "devDependencies": {
-    "@docusaurus/types": "2.2.0",
+    "@docusaurus/types": "2.3.0",
     "@types/escape-html": "^1.0.2",
     "@types/mdast": "^3.0.10",
-    "@types/mermaid": "^8.2.9",
     "@types/stringify-object": "^3.3.1",
     "@types/unist": "^2.0.6",
     "rehype-stringify": "^8.0.0",

packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__snapshots__/index.test.ts.snap

@@ -42,3 +42,8 @@ exports[`admonitions remark plugin interpolation 1`] = `
 "<p>Test admonition with interpolated title/body</p>
 <admonition type="tip"><mdxAdmonitionTitle>My <code>interpolated</code> <strong>title</strong> &#x3C;button style={{color: "red"}} onClick={() => alert("click")}>test</mdxAdmonitionTitle><p><code>body</code> <strong>interpolated</strong> content</p></admonition>"
 `;
+
+exports[`admonitions remark plugin nesting 1`] = `
+"<p>Test nested Admonitions</p>
+<admonition type="info"><mdxAdmonitionTitle><strong>Weather</strong></mdxAdmonitionTitle><p>On nice days, you can enjoy skiing in the mountains.</p><admonition type="danger"><mdxAdmonitionTitle><em>Storms</em></mdxAdmonitionTitle><p>Take care of snowstorms...</p></admonition></admonition>"
+`;

packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/index.test.ts

@@ -50,4 +50,9 @@ describe('admonitions remark plugin', () => {
     const result = await processFixture('interpolation');
     expect(result).toMatchSnapshot();
   });
+
+  it('nesting', async () => {
+    const result = await processFixture('nesting');
+    expect(result).toMatchSnapshot();
+  });
 });

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

@@ -52,9 +52,20 @@ const plugin: Plugin = function plugin(
   const options = normalizeOptions(optionsInput);
 
   const keywords = Object.values(options.keywords).map(escapeRegExp).join('|');
+  const nestingChar = escapeRegExp(options.tag.slice(0, 1));
   const tag = escapeRegExp(options.tag);
-  const regex = new RegExp(`${tag}(${keywords})(?: *(.*))?\n`);
-  const escapeTag = new RegExp(escapeRegExp(`\\${options.tag}`), 'g');
+
+  // resolve th nesting level of an opening tag
+  // ::: -> 0, :::: -> 1, ::::: -> 2 ...
+  const nestingLevelRegex = new RegExp(
+    `^${tag}(?<nestingLevel>${nestingChar}*)`,
+  );
+
+  const regex = new RegExp(`${tag}${nestingChar}*(${keywords})(?: *(.*))?\n`);
+  const escapeTag = new RegExp(
+    escapeRegExp(`\\${options.tag}${options.tag.slice(0, 1)}*`),
+    'g',
+  );
 
   // The tokenizer is called on blocks to determine if there is an admonition
   // present and create tags for it
@@ -77,6 +88,11 @@ const plugin: Plugin = function plugin(
     ];
     const food = [];
     const content = [];
+    // get the nesting level of the opening tag
+    const openingLevel =
+      nestingLevelRegex.exec(opening)!.groups!.nestingLevel!.length;
+    // used as a stack to keep track of nested admonitions
+    const nestingLevels: number[] = [openingLevel];
 
     let newValue = value;
     // consume lines until a closing tag
@@ -88,12 +104,32 @@ const plugin: Plugin = function plugin(
         next !== -1 ? newValue.slice(idx + 1, next) : newValue.slice(idx + 1);
       food.push(line);
       newValue = newValue.slice(idx + 1);
-      // the closing tag is NOT part of the content
-      if (line.startsWith(options.tag)) {
-        break;
+      const nesting = nestingLevelRegex.exec(line);
+      idx = newValue.indexOf(NEWLINE);
+      if (!nesting) {
+        content.push(line);
+        continue;
+      }
+      const tagLevel = nesting.groups!.nestingLevel!.length;
+      // first level
+      if (nestingLevels.length === 0) {
+        nestingLevels.push(tagLevel);
+        content.push(line);
+        continue;
+      }
+      const currentLevel = nestingLevels[nestingLevels.length - 1]!;
+      if (tagLevel < currentLevel) {
+        // entering a nested admonition block
+        nestingLevels.push(tagLevel);
+      } else if (tagLevel === currentLevel) {
+        // closing a nested admonition block
+        nestingLevels.pop();
+        // the closing tag is NOT part of the content
+        if (nestingLevels.length === 0) {
+          break;
+        }
       }
       content.push(line);
-      idx = newValue.indexOf(NEWLINE);
     }
 
     // consume the processed tag and replace escape sequences

packages/docusaurus-migrate/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/migrate",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "A CLI tool to migrate from older versions of Docusaurus.",
   "license": "MIT",
   "engines": {
@@ -24,8 +24,8 @@
   "dependencies": {
     "@babel/core": "^7.18.6",
     "@babel/preset-env": "^7.18.6",
-    "@docusaurus/logger": "2.2.0",
-    "@docusaurus/utils": "2.2.0",
+    "@docusaurus/logger": "2.3.0",
+    "@docusaurus/utils": "2.3.0",
     "@mapbox/hast-util-to-jsx": "^2.0.0",
     "color": "^4.2.3",
     "commander": "^5.1.0",

packages/docusaurus-migrate/src/__tests__/__snapshots__/index.test.ts.snap

@@ -120,7 +120,7 @@ exports[`migration CLI migrates complex website: write 1`] = `
           ]
         }
       ],
-      "copyright": "Copyright © 2022 Facebook Inc.",
+      "copyright": "Copyright © 2023 Facebook Inc.",
       "logo": {
         "src": "img/docusaurus_monochrome.svg"
       }
@@ -303,7 +303,7 @@ exports[`migration CLI migrates missing versions: write 1`] = `
           ]
         }
       ],
-      "copyright": "Copyright © 2022 Facebook Inc.",
+      "copyright": "Copyright © 2023 Facebook Inc.",
       "logo": {
         "src": "img/docusaurus_monochrome.svg"
       }
@@ -483,7 +483,7 @@ exports[`migration CLI migrates simple website: write 1`] = `
           ]
         }
       ],
-      "copyright": "Copyright © 2022 Facebook Inc.",
+      "copyright": "Copyright © 2023 Facebook Inc.",
       "logo": {
         "src": "img/docusaurus_monochrome.svg"
       }