feat: support mermaid code blocks in Markdown

packages/docusaurus-mdx-loader/package.json

@@ -39,6 +39,7 @@
     "@docusaurus/types": "2.0.0-beta.20",
     "@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,6 +22,7 @@ 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 type {LoaderContext} from 'webpack';
 import type {Processor, Plugin} from 'unified';
@@ -67,6 +68,7 @@ export type Options = Partial<MDXOptions> & {
     metadata: {[key: string]: unknown};
   }) => {[key: string]: unknown};
   filepath: string;
+  mermaid?: boolean;
 };
 
 /**
@@ -149,11 +151,13 @@ export async function mdxLoader(
   const hasFrontMatter = Object.keys(frontMatter).length > 0;
 
   if (!compilerCache.has(this.query)) {
+    const mermaidOptions = reqOptions.mermaid === true ? [mermaid] : [];
     const options: Options = {
       ...reqOptions,
       remarkPlugins: [
         ...(reqOptions.beforeDefaultRemarkPlugins ?? []),
         ...DEFAULT_OPTIONS.remarkPlugins,
+        ...mermaidOptions,
         [
           transformImage,
           {

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

@@ -0,0 +1,62 @@
+/**
+ * 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('no mermaid', async () => {
+    const mdxCompiler = createTestCompiler();
+    const result = await mdxCompiler.process(
+      '# Heading 1\n\nNo Mermaid diagram :(',
+    );
+    expect(result.contents).toBe(
+      '\n\n\nconst layoutProps = {\n  \n};\nconst MDXLayout = "wrapper"\nexport default function MDXContent({\n  components,\n  ...props\n}) {\n  return <MDXLayout {...layoutProps} {...props} components={components} mdxType="MDXLayout">\n    <h1>{`Heading 1`}</h1>\n    <p>{`No Mermaid diagram :(`}</p>\n    </MDXLayout>;\n}\n\n;\nMDXContent.isMDXComponent = true;',
+    );
+  });
+
+  it('basic', async () => {
+    const mdxCompiler = createTestCompiler();
+    const result = await mdxCompiler.process(`# Heading 1\n
+\`\`\`mermaid
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+\`\`\``);
+    expect(result.contents).toBe(`
+
+
+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;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;\`} />
+    </MDXLayout>;
+}
+
+;
+MDXContent.isMDXComponent = true;`);
+  });
+});

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

@@ -0,0 +1,48 @@
+/**
+ * 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 {Data, Literal, Node, Parent} from 'unist';
+
+type CodeMermaid = Literal<string> & {
+  type: 'code';
+  lang: 'mermaid';
+};
+
+function processMermaidNode(
+  node: CodeMermaid,
+  index: number,
+  parent: Parent<Node<Data> | Literal, Data>,
+) {
+  parent.children.splice(index, 1, {
+    type: 'jsx',
+    value: `<mermaid value={\`${node.value}\`}/>`,
+    position: node.position,
+  });
+}
+
+export default function plugin(): Transformer {
+  return async (root) => {
+    // Find all the mermaid diagram code blocks. i.e. ```mermaid
+    const instances: [CodeMermaid, number, Parent<Node<Data>, Data>][] = [];
+    visit(
+      root,
+      {type: 'code', lang: 'mermaid'},
+      (node: CodeMermaid, index, parent) => {
+        if (parent) {
+          instances.push([node, index, parent]);
+        }
+      },
+    );
+
+    // Replace each Mermaid code block with the Mermaid component
+    instances.forEach(([node, index, parent]) => {
+      processMermaidNode(node, index, parent);
+    });
+  };
+}

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

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

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

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

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

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

packages/docusaurus-theme-classic/package.json

@@ -25,6 +25,7 @@
     "@docusaurus/plugin-content-docs": "2.0.0-beta.20",
     "@docusaurus/plugin-content-pages": "2.0.0-beta.20",
     "@docusaurus/theme-common": "2.0.0-beta.20",
+    "@docusaurus/theme-mermaid": "2.0.0-beta.20",
     "@docusaurus/theme-translations": "2.0.0-beta.20",
     "@docusaurus/utils": "2.0.0-beta.20",
     "@docusaurus/utils-common": "2.0.0-beta.20",

packages/docusaurus-theme-classic/src/theme-classic.d.ts

@@ -11,6 +11,7 @@
 /// <reference types="@docusaurus/plugin-content-docs" />
 /// <reference types="@docusaurus/plugin-content-blog" />
 /// <reference types="@docusaurus/plugin-content-pages" />
+/// <reference types="@docusaurus/theme-mermaid" />
 
 // This file, like all the other ambient declaration files for plugins, is
 // needed for TS to understand our `@theme` alias. The export signatures are

packages/docusaurus-theme-classic/src/theme/Layout/index.tsx

@@ -13,6 +13,7 @@ import {
   ThemeClassNames,
   useKeyboardNavigation,
 } from '@docusaurus/theme-common';
+import useMermaid from '@docusaurus/theme-mermaid/theme/useMermaid';
 import SkipToContent from '@theme/SkipToContent';
 import AnnouncementBar from '@theme/AnnouncementBar';
 import Navbar from '@theme/Navbar';
@@ -33,6 +34,7 @@ export default function Layout(props: Props): JSX.Element {
   } = props;
 
   useKeyboardNavigation();
+  useMermaid();
 
   return (
     <LayoutProviders>

packages/docusaurus-theme-classic/src/theme/MDXComponents/index.tsx

@@ -6,6 +6,7 @@
  */
 
 import React from 'react';
+import MDXMermaid from '@docusaurus/theme-mermaid/theme/MDXComponents/Mermaid';
 import MDXHead from '@theme/MDXComponents/Head';
 import MDXCode from '@theme/MDXComponents/Code';
 import MDXA from '@theme/MDXComponents/A';
@@ -31,6 +32,7 @@ const MDXComponents: MDXComponentsObject = {
   h4: (props) => <MDXHeading as="h4" {...props} />,
   h5: (props) => <MDXHeading as="h5" {...props} />,
   h6: (props) => <MDXHeading as="h6" {...props} />,
+  mermaid: MDXMermaid,
 };
 
 export default MDXComponents;

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,53 @@
+{
+  "name": "@docusaurus/theme-mermaid",
+  "version": "2.0.0-beta.20",
+  "description": "Mermaid components for Docusaurus.",
+  "main": "lib/index.js",
+  "exports": {
+    "./theme/MDXComponents/Mermaid": "./lib/theme/MDXComponents/Mermaid.js",
+    "./theme/useMermaid": "./lib/theme/useMermaid.js",
+    "./theme/Mermaid": "./lib/theme/Mermaid/index.js",
+    ".": "./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.20",
+    "@docusaurus/theme-common": "2.0.0-beta.20",
+    "@docusaurus/theme-translations": "2.0.0-beta.20",
+    "@docusaurus/utils": "2.0.0-beta.20",
+    "@docusaurus/utils-common": "2.0.0-beta.20",
+    "@docusaurus/utils-validation": "2.0.0-beta.20",
+    "@mdx-js/react": "^1.6.22",
+    "mermaid": "^9.1.1",
+    "tslib": "^2.4.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "2.0.0-beta.20",
+    "@docusaurus/types": "2.0.0-beta.20",
+    "@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": ">=14"
+  }
+}

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

@@ -0,0 +1,71 @@
+/**
+ * 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} from '../validateThemeConfig';
+import type {Joi} from '@docusaurus/utils-validation';
+
+function testValidateThemeConfig(themeConfig: {[key: string]: unknown}) {
+  function validate(
+    schema: Joi.ObjectSchema<{[key: string]: unknown}>,
+    cfg: {[key: string]: unknown},
+  ) {
+    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({});
+  });
+
+  it('nonexistent config', () => {
+    expect(testValidateThemeConfig({})).toEqual({});
+  });
+
+  it('empty config', () => {
+    const mermaid = {};
+    expect(testValidateThemeConfig({mermaid})).toEqual({
+      mermaid: {},
+    });
+  });
+
+  it('theme', () => {
+    const mermaid = {
+      theme: {
+        light: 'light',
+        dark: 'dark',
+      },
+    };
+    expect(testValidateThemeConfig({mermaid})).toEqual({
+      mermaid: {
+        ...mermaid,
+      },
+    });
+  });
+
+  it('config', () => {
+    const mermaid = {
+      config: {
+        fontFamily: 'Ariel',
+      },
+    };
+    expect(testValidateThemeConfig({mermaid})).toEqual({
+      mermaid: {
+        ...mermaid,
+      },
+    });
+  });
+});