introduce @theguild/remark-mermaid (#1092)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

.changeset/@theguild_components-1092-dependencies.md

@@ -0,0 +1,6 @@
+---
+"@theguild/components": patch
+---
+dependencies updates:
+  - Removed dependency [`[email protected]` ↗︎](https://www.npmjs.com/package/mermaid/v/10.1.0) (from `dependencies`)
+  - Removed dependency [`[email protected]` ↗︎](https://www.npmjs.com/package/unist-util-visit/v/4.1.2) (from `dependencies`)

.changeset/sweet-houses-approve.md

@@ -0,0 +1,6 @@
+---
+'@theguild/remark-mermaid': patch
+'@theguild/components': patch
+---
+
+release `@theguild/remark-mermaid`

.gitignore

@@ -11,3 +11,4 @@ packages/og-image/vender/*.wasm
 .eslintcache
 .wrangler/
 .DS_Store
+tsup.config.*.mjs

package.json

@@ -10,6 +10,7 @@
     "build": "turbo run build",
     "build-storybook": "storybook build",
     "build:css": "NODE_ENV=production tailwindcss --config tailwind.config.cjs --postcss --output packages/components/style.css",
+    "dev": "turbo run dev --parallel",
     "lint": "eslint --cache --ignore-path .gitignore .",
     "lint:prettier": "prettier --cache --check .",
     "prepare": "husky install",

packages/components/package.json

@@ -48,6 +48,7 @@
   ],
   "scripts": {
     "build": "tsup",
+    "dev": "tsup --watch",
     "prebuild": "pnpm types:check && rm -rf dist",
     "types:check": "tsc --noEmit"
   },
@@ -64,11 +65,11 @@
     "@giscus/react": "2.2.8",
     "@next/bundle-analyzer": "13.4.2",
     "@radix-ui/react-navigation-menu": "1.1.3",
+    "@theguild/remark-mermaid": "workspace:*",
     "algoliasearch": "4.17.1",
     "clsx": "1.2.1",
     "focus-trap-react": "10.1.4",
     "fuzzy": "^0.1.3",
-    "mermaid": "10.1.0",
     "next-videos": "1.5.0",
     "nextra": "2.6.2",
     "nextra-theme-docs": "2.6.2",
@@ -78,15 +79,12 @@
     "remark-mdx-disable-explicit-jsx": "0.1.0",
     "search-insights": "2.6.0",
     "semver": "^7.3.8",
-    "unist-util-visit": "4.1.2",
     "use-debounce": "9.0.4"
   },
   "devDependencies": {
     "@theguild/algolia": "workspace:*",
     "@theguild/editor": "workspace:*",
     "@types/dedent": "0.7.0",
-    "@types/mdast": "3.0.11",
-    "@types/mermaid": "9.1.0",
     "@types/react-dom": "18.2.4",
     "@types/semver": "7.5.0",
     "dedent": "0.7.0",
@@ -95,8 +93,7 @@
     "next": "13.4.2",
     "react": "18.2.0",
     "react-dom": "18.2.0",
-    "tailwindcss": "3.3.2",
-    "unified": "10.1.2"
+    "tailwindcss": "3.3.2"
   },
   "publishConfig": {
     "access": "public"

packages/components/src/index.ts

@@ -1,6 +1,5 @@
 export * from './components';
 export { defineConfig } from './define-config';
-export * from './mermaid';
 export { fetchPackageInfo } from './npm';
 export { PRODUCTS } from './products';
 export * from './types/components';

packages/components/src/next.config.ts

@@ -3,7 +3,7 @@ import withVideos from 'next-videos';
 import nextra from 'nextra';
 import remarkMdxDisableExplicitJsx from 'remark-mdx-disable-explicit-jsx';
 import nextBundleAnalyzer from '@next/bundle-analyzer';
-import { remarkMermaid } from './remark-mermaid';
+import { remarkMermaid } from '@theguild/remark-mermaid';
 import { applyUnderscoreRedirects } from './underscore-redirects';
 
 export const defaultRemarkPlugins = [
@@ -39,6 +39,7 @@ export const withGuildDocs = ({
     mdxOptions: {
       remarkPlugins: defaultRemarkPlugins,
     },
+    flexsearch: false,
   });
   const siteUrl = process.env.SITE_URL || '';
 

packages/components/tsup.config.ts

@@ -6,6 +6,7 @@ import tsconfig from './tsconfig.json';
 const options = defineConfig({
   format: 'esm',
   target: tsconfig.compilerOptions.target as Options['target'],
+  clean: true,
 });
 
 export default defineConfig([

packages/og-image/global.d.ts

@@ -1,17 +1,3 @@
-// interface CustomMatchers<R = unknown> {
-//   toMatchImageSnapshot(): R;
-// }
-
-// declare global {
-//   namespace Vi {
-//     type Assertion = CustomMatchers;
-//
-//     type AsymmetricMatchersContaining = CustomMatchers;
-//   }
-//
-//   // Note: augmenting jest.Matchers interface will also work.
-// }
-
 declare global {
   namespace jest {
     interface Matchers<R> {

packages/remark-mermaid/README.md

@@ -0,0 +1,47 @@
+# `@theguild/remark-mermaid`
+
+> Created by Dimitri POSTOLOV https://twitter.com/B2o5T.
+>
+> Maintained by The Guild https://twitter.com/TheGuildDev.
+
+Remark plugin for replacing ```mermaid code blocks with react `<Mermaid />` component.
+
+- Support MDX2
+
+- Support both dark and light themes. Listening for the `dark` class on the `<html />` element and
+  updating mermaid's theme.
+
+## Install
+
+```sh
+npm i @theguild/remark-mermaid
+```
+
+## How to Use
+
+Follow code will be converted to a mermaid diagram.
+
+````mdx
+// my-page.mdx
+
+```mermaid
+graph TD;
+subgraph AA [Consumers]
+A[Mobile app];
+B[Web app];
+C[Node.js client];
+end
+subgraph BB [Services]
+E[REST API];
+F[GraphQL API];
+G[SOAP API];
+end
+Z[GraphQL API];
+A --> Z;
+B --> Z;
+C --> Z;
+Z --> E;
+Z --> F;
+Z --> G;
+```
+````

packages/remark-mermaid/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@theguild/remark-mermaid",
+  "version": "0.0.0",
+  "type": "module",
+  "description": "Remark plugin for replacing ```mermaid code blocks with react `<Mermaid />` component",
+  "repository": {
+    "url": "https://github.com/the-guild-org/docs",
+    "directory": "packages/remark-mermaid"
+  },
+  "author": "Dimitri POSTOLOV <[email protected]> (https://github.com/B2o5T)",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./dist/index.js",
+    "./*": "./dist/*.js"
+  },
+  "typesVersions": {
+    "*": {
+      "mermaid": [
+        "./dist/mermaid.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0"
+  },
+  "dependencies": {
+    "mermaid": "10.2.1",
+    "unist-util-visit": "4.1.2"
+  },
+  "devDependencies": {
+    "@types/mdast": "3.0.11",
+    "@types/mermaid": "9.2.0",
+    "react": "^18.2.0",
+    "unified": "10.1.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false
+}

packages/components/src/remark-mermaid.ts → packages/remark-mermaid/src/index.ts

@@ -1,12 +1,15 @@
+import { createRequire } from 'node:module';
 import { Root } from 'mdast';
 import { Plugin } from 'unified';
 import { visit } from 'unist-util-visit';
 
-const FILE_PATH = '@theguild/components';
+const require = createRequire(import.meta.url);
+
+const MERMAID_COMPONENT_PATH = require.resolve('@theguild/remark-mermaid/mermaid');
 
 const MERMAID_IMPORT_AST = {
   type: 'mdxjsEsm' as 'inlineCode',
-  value: `import { Mermaid } from "${FILE_PATH}"`,
+  value: `import { Mermaid } from "${MERMAID_COMPONENT_PATH}"`,
   data: {
     estree: {
       type: 'Program',
@@ -23,8 +26,8 @@ const MERMAID_IMPORT_AST = {
           ],
           source: {
             type: 'Literal',
-            value: FILE_PATH,
-            raw: `"${FILE_PATH}"`,
+            value: MERMAID_COMPONENT_PATH,
+            raw: `"${MERMAID_COMPONENT_PATH}"`,
           },
         },
       ],

packages/remark-mermaid/src/mermaid.tsx

@@ -0,0 +1,42 @@
+import { ReactElement, useEffect, useId, useState } from 'react';
+import mermaid, { MermaidConfig } from 'mermaid';
+
+export function Mermaid({ chart }: { chart: string }): ReactElement {
+  const id = useId();
+  const [svg, setSvg] = useState('');
+
+  useEffect(() => {
+    const htmlElement = document.documentElement;
+    const mutationObserver = new MutationObserver(renderChart);
+    mutationObserver.observe(htmlElement, { attributes: true });
+
+    // Switching themes taken from https://github.com/mermaid-js/mermaid/blob/1b40f552b20df4ab99a986dd58c9d254b3bfd7bc/packages/mermaid/src/docs/.vitepress/theme/Mermaid.vue#L53
+    async function renderChart() {
+      const hasDarkClass = htmlElement.classList.contains('dark');
+      const mermaidConfig: MermaidConfig = {
+        startOnLoad: false,
+        securityLevel: 'loose',
+        fontFamily: 'inherit',
+        themeCSS: 'margin: 1.5rem auto 0;',
+        theme: hasDarkClass ? 'dark' : 'default',
+      };
+
+      try {
+        mermaid.initialize(mermaidConfig);
+        const { svg } = await mermaid.render(
+          // strip invalid characters for `id` attribute
+          id.replaceAll(':', ''),
+          chart,
+        );
+        setSvg(svg);
+      } catch (error) {
+        // eslint-disable-next-line no-console -- show error
+        console.error('Error while rendering mermaid', error);
+      }
+    }
+
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- only on mount
+  }, []);
+
+  return <div dangerouslySetInnerHTML={{ __html: svg }} />;
+}

packages/remark-mermaid/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "es2021",
+    "module": "ESNext",
+    "declaration": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "allowJs": true,
+    "jsx": "react-jsx",
+    "moduleResolution": "node",
+    "resolveJsonModule": true
+  }
+}

packages/remark-mermaid/tsup.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig, Options } from 'tsup';
+import tsconfig from './tsconfig.json';
+
+export default defineConfig([
+  {
+    format: 'esm',
+    entry: ['src/**/*.{ts,tsx}'],
+    target: tsconfig.compilerOptions.target as Options['target'],
+    bundle: false,
+  },
+  {
+    name: 'dts',
+    entry: ['src/**/*.{ts,tsx}'],
+    dts: {
+      only: true,
+    },
+  },
+]);