feat: support mermaid code blocks in Markdown

packages/docusaurus-mdx-loader/package.json

@@ -40,6 +40,7 @@
     "@docusaurus/types": "2.0.0-beta.21",
     "@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",
     "remark": "^12.0.1",

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

@@ -22,8 +22,10 @@ import toc from './remark/toc';
 import unwrapMdxCodeBlocks from './remark/unwrapMdxCodeBlocks';
 import transformImage from './remark/transformImage';
 import transformLinks from './remark/transformLinks';
+import mermaid from './remark/mermaid';
 
 import transformAdmonitions from './remark/admonitions';
+import type {MarkdownConfig} from '@docusaurus/types';
 import type {LoaderContext} from 'webpack';
 import type {Processor, Plugin} from 'unified';
 import type {AdmonitionOptions} from './remark/admonitions';
@@ -60,19 +62,20 @@ export type MDXOptions = {
   beforeDefaultRehypePlugins: MDXPlugin[];
 };
 
-export type Options = Partial<MDXOptions> & {
-  staticDirs: string[];
-  siteDir: string;
-  isMDXPartial?: (filePath: string) => boolean;
-  isMDXPartialFrontMatterWarningDisabled?: boolean;
-  removeContentTitle?: boolean;
-  metadataPath?: string | ((filePath: string) => string);
-  createAssets?: (metadata: {
-    frontMatter: {[key: string]: unknown};
-    metadata: {[key: string]: unknown};
-  }) => {[key: string]: unknown};
-  filepath: string;
-};
+export type Options = Partial<MDXOptions> &
+  MarkdownConfig & {
+    staticDirs: string[];
+    siteDir: string;
+    isMDXPartial?: (filePath: string) => boolean;
+    isMDXPartialFrontMatterWarningDisabled?: boolean;
+    removeContentTitle?: boolean;
+    metadataPath?: string | ((filePath: string) => string);
+    createAssets?: (metadata: {
+      frontMatter: {[key: string]: unknown};
+      metadata: {[key: string]: unknown};
+    }) => {[key: string]: unknown};
+    filepath: string;
+  };
 
 /**
  * When this throws, it generally means that there's no metadata file associated
@@ -171,6 +174,7 @@ export async function mdxLoader(
       ...(reqOptions.beforeDefaultRemarkPlugins ?? []),
       ...getAdmonitionsPlugins(reqOptions.admonitions ?? false),
       ...DEFAULT_OPTIONS.remarkPlugins,
+      ...(reqOptions.mermaid ? [mermaid] : []),
       [
         transformImage,
         {

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

@@ -0,0 +1,51 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`mermaid remark plugin does nothing if there's no mermaid code block 1`] = `
+"
+
+
+const layoutProps = {
+
+};
+const MDXLayout = "wrapper"
+export default function MDXContent({
+  components,
+  ...props
+}) {
+  return <MDXLayout {...layoutProps} {...props} components={components} mdxType="MDXLayout">
+    <h1>{\`Heading 1\`}</h1>
+    <p>{\`No Mermaid diagram :(\`}</p>
+    <pre><code parentName="pre" {...{
+        "className": "language-js"
+      }}>{\`this is not mermaid
+\`}</code></pre>
+    </MDXLayout>;
+}
+
+;
+MDXContent.isMDXComponent = true;"
+`;
+
+exports[`mermaid remark plugin works for basic mermaid code blocks 1`] = `
+"
+
+
+const layoutProps = {
+
+};
+const MDXLayout = "wrapper"
+export default function MDXContent({
+  components,
+  ...props
+}) {
+  return <MDXLayout {...layoutProps} {...props} components={components} mdxType="MDXLayout">
+    <h1>{\`Heading 1\`}</h1>
+    <mermaid {...{
+      "value": "graph TD;/n    A-->B;/n    A-->C;/n    B-->D;/n    C-->D;"
+    }}></mermaid>
+    </MDXLayout>;
+}
+
+;
+MDXContent.isMDXComponent = true;"
+`;

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

@@ -0,0 +1,46 @@
+/**
+ * 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 {createCompiler} from '@mdx-js/mdx';
+import mermaid from '..';
+
+describe('mermaid remark plugin', () => {
+  function createTestCompiler() {
+    return createCompiler({
+      remarkPlugins: [mermaid],
+    });
+  }
+
+  it("does nothing if there's no mermaid code block", async () => {
+    const mdxCompiler = createTestCompiler();
+    const result = await mdxCompiler.process(
+      `# Heading 1
+
+No Mermaid diagram :(
+
+\`\`\`js
+this is not mermaid
+\`\`\`
+`,
+    );
+    expect(result.contents).toMatchSnapshot();
+  });
+
+  it('works for basic mermaid code blocks', async () => {
+    const mdxCompiler = createTestCompiler();
+    const result = await mdxCompiler.process(`# Heading 1
+
+\`\`\`mermaid
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+\`\`\``);
+    expect(result.contents).toMatchSnapshot();
+  });
+});

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

@@ -0,0 +1,32 @@
+/**
+ * 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 visit from 'unist-util-visit';
+import type {Transformer} from 'unified';
+import type {Code} from 'mdast';
+
+// TODO: this plugin shouldn't be in the core MDX loader
+// After we allow plugins to provide Remark/Rehype plugins (see
+// https://github.com/facebook/docusaurus/issues/6370), this should be provided
+// by theme-mermaid itself
+export default function plugin(): Transformer {
+  return (root) => {
+    visit(root, 'code', (node: Code, index, parent) => {
+      if (node.lang === 'mermaid') {
+        parent!.children.splice(index, 1, {
+          type: 'mermaidCodeBlock',
+          data: {
+            hName: 'mermaid',
+            hProperties: {
+              value: node.value,
+            },
+          },
+        });
+      }
+    });
+  };
+}

packages/docusaurus-plugin-content-blog/src/index.ts

@@ -460,6 +460,7 @@ export default async function pluginContentBlog(
                         (author) => author.imageURL,
                       ),
                     }),
+                    ...siteConfig.markdown,
                   },
                 },
                 {

packages/docusaurus-plugin-content-docs/src/index.ts

@@ -380,6 +380,7 @@ export default async function pluginContentDocs(
                 }) => ({
                   image: frontMatter.image,
                 }),
+                ...siteConfig.markdown,
               },
             },
             {

packages/docusaurus-plugin-content-pages/src/index.ts

@@ -211,6 +211,7 @@ export default function pluginContentPages(
                         `${docuHash(aliasedSource)}.json`,
                       );
                     },
+                    ...siteConfig.markdown,
                   },
                 },
                 {

packages/docusaurus-theme-mermaid/.npmignore

@@ -0,0 +1,3 @@
+.tsbuildinfo*
+tsconfig*
+__tests__

packages/docusaurus-theme-mermaid/README.md

@@ -0,0 +1,21 @@
+# Docusaurus Theme Mermaid
+
+The mermaid components for Docusaurus.
+
+## Installation
+
+Add `docusaurus/theme-mermaid` to your package:
+
+```bash
+npm i @docusaurus/theme-mermaid
+# or
+yarn add @docusaurus/theme-mermaid
+```
+
+## Swizzling components
+
+```bash
+$ npm swizzle @docusaurus/theme-mermaid [component name]
+```
+
+All components used by this theme can be found [here](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-mermaid/src/theme)

packages/docusaurus-theme-mermaid/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@docusaurus/theme-mermaid",
+  "version": "2.0.0-beta.21",
+  "description": "Mermaid components for Docusaurus.",
+  "main": "lib/index.js",
+  "types": "src/theme-mermaid.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/facebook/docusaurus.git",
+    "directory": "packages/docusaurus-theme-mermaid"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc --build && node ../../admin/scripts/copyUntypedFiles.js && prettier --config ../../.prettierrc --write \"lib/theme/**/*.js\"",
+    "watch": "run-p -c copy:watch build:watch",
+    "build:watch": "tsc --build --watch",
+    "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
+  },
+  "dependencies": {
+    "@docusaurus/core": "2.0.0-beta.21",
+    "@docusaurus/module-type-aliases": "2.0.0-beta.21",
+    "@docusaurus/theme-common": "2.0.0-beta.21",
+    "@docusaurus/types": "2.0.0-beta.21",
+    "@docusaurus/utils-validation": "2.0.0-beta.21",
+    "@mdx-js/react": "^1.6.22",
+    "mermaid": "^9.1.1",
+    "tslib": "^2.4.0"
+  },
+  "devDependencies": {
+    "@types/mdx-js__react": "^1.5.5",
+    "@types/mermaid": "^8.2.9",
+    "react-test-renderer": "^17.0.2"
+  },
+  "peerDependencies": {
+    "react": "^16.8.4 || ^17.0.0",
+    "react-dom": "^16.8.4 || ^17.0.0"
+  },
+  "engines": {
+    "node": ">=16.14"
+  }
+}

packages/docusaurus-theme-mermaid/src/__tests__/validateThemeConfig.test.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 {
+  validateThemeConfig,
+  DEFAULT_THEME_CONFIG,
+} from '../validateThemeConfig';
+import type {Joi} from '@docusaurus/utils-validation';
+import type {ThemeConfig, UserThemeConfig} from '@docusaurus/theme-mermaid';
+
+function testValidateThemeConfig(themeConfig: UserThemeConfig) {
+  function validate(
+    schema: Joi.ObjectSchema<ThemeConfig>,
+    cfg: UserThemeConfig,
+  ) {
+    const {value, error} = schema.validate(cfg, {
+      convert: false,
+    });
+    if (error) {
+      throw error;
+    }
+    return value;
+  }
+
+  return validateThemeConfig({validate, themeConfig});
+}
+
+describe('validateThemeConfig', () => {
+  it('undefined config', () => {
+    const mermaid = undefined;
+    expect(testValidateThemeConfig({mermaid})).toEqual(DEFAULT_THEME_CONFIG);
+  });
+
+  it('nonexistent config', () => {
+    expect(testValidateThemeConfig({})).toEqual(DEFAULT_THEME_CONFIG);
+  });
+
+  it('empty config', () => {
+    const mermaid = {};
+    expect(testValidateThemeConfig({mermaid})).toEqual(DEFAULT_THEME_CONFIG);
+  });
+
+  it('theme', () => {
+    const mermaid = {
+      theme: {
+        light: 'light',
+        dark: 'dark',
+      },
+    };
+    expect(testValidateThemeConfig({mermaid})).toEqual({
+      mermaid: {
+        ...DEFAULT_THEME_CONFIG.mermaid,
+        ...mermaid,
+      },
+    });
+  });
+
+  it('mermaidOptions', () => {
+    const mermaid = {
+      mermaidOptions: {
+        fontFamily: 'Ariel',
+      },
+    };
+    expect(testValidateThemeConfig({mermaid})).toEqual({
+      mermaid: {
+        ...DEFAULT_THEME_CONFIG.mermaid,
+        ...mermaid,
+      },
+    });
+  });
+});

packages/docusaurus-theme-mermaid/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 type {Plugin} from '@docusaurus/types';
+
+export default function themeMermaid(): Plugin<void> {
+  return {
+    name: 'docusaurus-theme-mermaid',
+
+    getThemePath() {
+      return '../lib/theme';
+    },
+    getTypeScriptThemePath() {
+      return '../src/theme';
+    },
+  };
+}
+
+export {validateThemeConfig} from './validateThemeConfig';