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,7 +22,9 @@ 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 {MarkdownConfig} from '@docusaurus/types';
 import type {LoaderContext} from 'webpack';
 import type {Processor, Plugin} from 'unified';
 
@@ -55,19 +57,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
@@ -154,6 +157,7 @@ export async function mdxLoader(
       remarkPlugins: [
         ...(reqOptions.beforeDefaultRemarkPlugins ?? []),
         ...DEFAULT_OPTIONS.remarkPlugins,
+        ...(reqOptions.mermaid ? [mermaid] : []),
         [
           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,
                       ),
                     }),
+                    ...siteConfig.markdown,
                   },
                 },
                 {

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

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

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

@@ -221,6 +221,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,47 @@
+{
+  "name": "@docusaurus/theme-mermaid",
+  "version": "2.0.0-beta.20",
+  "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.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,
+      },
+    });
+  });
+});

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

@@ -0,0 +1,35 @@
+/**
+ * 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 {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations';
+import type {LoadContext, Plugin} from '@docusaurus/types';
+
+export default function themeMermaid(context: LoadContext): Plugin<void> {
+  const {
+    i18n: {currentLocale},
+  } = context;
+
+  return {
+    name: 'docusaurus-theme-mermaid',
+
+    getThemePath() {
+      return '../lib/theme';
+    },
+    getTypeScriptThemePath() {
+      return '../src/theme';
+    },
+
+    getDefaultCodeTranslationMessages() {
+      return readDefaultCodeTranslationMessages({
+        locale: currentLocale,
+        name: 'theme-mermaid',
+      });
+    },
+  };
+}
+
+export {validateThemeConfig} from './validateThemeConfig';