feat(cli): support mermaid files within markdown

Support mermaid diagrams that are embedded within CommonMark
`.md` markdown files.

We're using [remark](https://github.com/remarkjs/remark) to parse the
markdown into a [markdown AST](https://github.com/syntax-tree/mdast).
From this, we process every code block that has `lang=mermaid`, then
turn the mdAST back to a string.

This means that we also automatically format/prettify the user's
markdown input, which is potentially unideal.

Author: aloisklink

packages/cli/README.md

@@ -29,6 +29,10 @@ npx @mermaidchart/cli --help
 `@mermaidchart/cli` allows you to easily sync local diagrams with your diagrams
 on https://mermaidchart.com.
 
+These local diagrams can either be stored in `.mmd` or `.mermaid` files, or
+the can be stored within ```` ```mermaid```` code blocks within `.md` markdown
+files.
+
 ### `login`
 
 Firstly, go to https://www.mermaidchart.com/app/user/settings and generate an

packages/cli/package.json

@@ -42,12 +42,14 @@
     "@tsconfig/strictest": "^2.0.2",
     "@types/iarna__toml": "^2.0.5",
     "@types/js-yaml": "^4.0.9",
+    "@types/mdast": "^4.0.3",
     "@types/node": "^18.18.11",
     "@typescript-eslint/eslint-plugin": "^6.11.0",
     "@typescript-eslint/parser": "^6.11.0",
     "eslint": "^8.54.0",
     "tsx": "^3.12.8",
     "typescript": "^5.2.2",
+    "vfile": "^6.0.1",
     "vitest": "^0.34.6"
   },
   "dependencies": {
@@ -58,6 +60,9 @@
     "@inquirer/select": "^1.3.1",
     "@mermaidchart/sdk": "workspace:^",
     "commander": "^11.1.0",
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.1.0",
+    "remark": "^15.0.1",
+    "to-vfile": "^8.0.0",
+    "unist-util-visit": "^5.0.0"
   }
 }

packages/cli/src/commander.test.ts

@@ -11,6 +11,10 @@ import type { MCDocument, MCProject, MCUser } from '@mermaidchart/sdk/dist/types
 
 /** Config file with auth_key setup */
 const CONFIG_AUTHED = 'test/fixtures/config-authed.toml';
+/** Markdown file that has every Mermaid diagrams already linked */
+const LINKED_MARKDOWN_FILE = 'test/fixtures/linked-markdown-file.md';
+/** Markdown file that has some unlinked Mermaid diagrams */
+const UNLINKED_MARKDOWN_FILE = 'test/fixtures/unlinked-markdown-file.md';
 
 type Optional<T> = T | undefined;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -269,16 +273,42 @@ describe('link', () => {
       );
     });
   }
+
+  it('should link diagrams in a markdown file', async () => {
+    const unlinkedMarkdownFile = 'test/output/markdown-file.md';
+    await copyFile(UNLINKED_MARKDOWN_FILE, unlinkedMarkdownFile);
+
+    const { program } = mockedProgram();
+
+    vi.mock('@inquirer/confirm');
+    vi.mock('@inquirer/select');
+    vi.mocked(confirm).mockResolvedValue(true);
+    vi.mocked(select).mockResolvedValueOnce(mockedProjects[0].id);
+
+    vi.mocked(MermaidChart.prototype.createDocument)
+      .mockResolvedValueOnce(mockedEmptyDiagram)
+      .mockResolvedValueOnce({ ...mockedEmptyDiagram, documentID: 'second-id' });
+    await program.parseAsync(['--config', CONFIG_AUTHED, 'link', unlinkedMarkdownFile], {
+      from: 'user',
+    });
+
+    const file = await readFile(unlinkedMarkdownFile, { encoding: 'utf8' });
+
+    expect(file).toMatch(`id: ${mockedEmptyDiagram.documentID}\n`);
+    expect(file).toMatch(`id: second-id\n`);
+  });
 });
 
 describe('pull', () => {
   const diagram = 'test/output/connected-diagram.mmd';
   const diagram2 = 'test/output/connected-diagram-2.mmd';
+  const linkedMarkdownFile = 'test/output/linked-markdown-file.md';
 
   beforeEach(async () => {
     await Promise.all([
       copyFile('test/fixtures/connected-diagram.mmd', diagram),
       copyFile('test/fixtures/connected-diagram.mmd', diagram2),
+      copyFile(LINKED_MARKDOWN_FILE, linkedMarkdownFile),
     ]);
   });
 
@@ -327,16 +357,41 @@ title: My cool flowchart
       expect(diagramContents).toContain("flowchart TD\n      A[I've been updated!]");
     }
   });
+
+  it('should pull documents from within markdown file', async () => {
+    const { program } = mockedProgram();
+
+    vi.mocked(MermaidChart.prototype.getDocument)
+      .mockResolvedValueOnce({
+        ...mockedEmptyDiagram,
+        code: "flowchart TD\n      A[I've been updated!]",
+      })
+      .mockResolvedValueOnce({
+        ...mockedEmptyDiagram,
+        code: 'pie\n  "Flowchart" : 2',
+      });
+
+    await program.parseAsync(['--config', CONFIG_AUTHED, 'pull', linkedMarkdownFile], {
+      from: 'user',
+    });
+
+    const file = await readFile(linkedMarkdownFile, { encoding: 'utf8' });
+
+    expect(file).toMatch("flowchart TD\n      A[I've been updated!]");
+    expect(file).toMatch('pie\n  "Flowchart" : 2');
+  });
 });
 
 describe('push', () => {
   const diagram = 'test/output/connected-diagram.mmd';
   const diagram2 = 'test/output/connected-diagram-2.mmd';
+  const linkedMarkdownFile = 'test/output/linked-markdown-file.md';
 
   beforeEach(async () => {
     await Promise.all([
       copyFile('test/fixtures/connected-diagram.mmd', diagram),
       copyFile('test/fixtures/connected-diagram.mmd', diagram2),
+      copyFile(LINKED_MARKDOWN_FILE, linkedMarkdownFile),
     ]);
   });
 
@@ -368,4 +423,16 @@ describe('push', () => {
       }),
     );
   });
+
+  it('should push documents from within markdown file', async () => {
+    const { program } = mockedProgram();
+
+    vi.mocked(MermaidChart.prototype.getDocument).mockResolvedValue(mockedEmptyDiagram);
+
+    await program.parseAsync(['--config', CONFIG_AUTHED, 'push', linkedMarkdownFile], {
+      from: 'user',
+    });
+
+    expect(vi.mocked(MermaidChart.prototype.setDocument)).toHaveBeenCalledTimes(2);
+  });
 });

packages/cli/src/commander.ts

@@ -11,7 +11,8 @@ import confirm from '@inquirer/confirm';
 import input from '@inquirer/input';
 import select, { Separator } from '@inquirer/select';
 import { type Config, defaultConfigPath, readConfig, writeConfig } from './config.js';
-import { link, type LinkOptions, pull, push } from './methods.js';
+import { type Cache, link, type LinkOptions, pull, push } from './methods.js';
+import { processMarkdown } from './remark.js';
 
 /**
  * Global configuration option for the root Commander Command.
@@ -157,6 +158,10 @@ function logout() {
     });
 }
 
+function isMarkdownFile(path: string): path is `${string}.${'md' | 'markdown'}` {
+  return /\.(md|markdown)$/.test(path);
+}
+
 function linkCmd() {
   return createCommand('link')
     .description('Link the given Mermaid diagrams to Mermaid Chart')
@@ -200,9 +205,13 @@ function linkCmd() {
         return projectId;
       };
 
-      const linkCache = {};
+      const linkCache: Cache = {};
 
       for (const path of paths) {
+        if (isMarkdownFile(path)) {
+          await processMarkdown(path, { command: 'link', client, cache: linkCache, getProjectId });
+          continue;
+        }
         const existingFile = await readFile(path, { encoding: 'utf8' });
 
         const linkedDiagram = await link(existingFile, client, {
@@ -220,12 +229,18 @@ function pullCmd() {
   return createCommand('pull')
     .description('Pulls documents from Mermaid Chart')
     .addArgument(new Argument('<path...>', 'The paths of the files to pull.'))
-    .option('--check', 'Check whether the local files would be overwrited')
+    .option('--check', 'Check whether the local files would be overwrited', false)
     .action(async (paths, options, command) => {
       const optsWithGlobals = command.optsWithGlobals<CommonOptions>();
       const client = await createClient(optsWithGlobals);
+
       await Promise.all(
         paths.map(async (path) => {
+          if (isMarkdownFile(path)) {
+            await processMarkdown(path, { command: 'pull', client, check: options['check'] });
+            return;
+          }
+
           const text = await readFile(path, { encoding: 'utf8' });
 
           const newFile = await pull(text, client, { title: path });
@@ -255,6 +270,11 @@ function pushCmd() {
       const client = await createClient(optsWithGlobals);
       await Promise.all(
         paths.map(async (path) => {
+          if (isMarkdownFile(path)) {
+            await processMarkdown(path, { command: 'push', client });
+            return;
+          }
+
           const text = await readFile(path, { encoding: 'utf8' });
 
           await push(text, client, { title: path });

packages/cli/src/remark.ts

@@ -0,0 +1,99 @@
+import type { Root, Code } from 'mdast';
+import type { VFile } from 'vfile';
+import { visit } from 'unist-util-visit';
+import type { MermaidChart } from '@mermaidchart/sdk';
+import { type LinkOptions, link, pull, push } from './methods.js';
+
+import { remark } from 'remark';
+import { read, write } from 'to-vfile';
+interface MCPluginCommonOptions {
+  /** Authenticated client */
+  client: MermaidChart;
+}
+
+type MCPluginLinkOptions = MCPluginCommonOptions & {
+  command: 'link';
+} & Pick<LinkOptions, 'cache' | 'getProjectId'>;
+
+interface MCPluginPullOptions extends MCPluginCommonOptions {
+  command: 'pull';
+  check: boolean;
+}
+
+interface MCPluginPushOptions extends MCPluginCommonOptions {
+  command: 'push';
+}
+
+export type MCPluginOptions = MCPluginLinkOptions | MCPluginPullOptions | MCPluginPushOptions;
+
+/**
+ * UnifiedJS plugin for syncing mermaid diagrams in a markdown file with
+ * MermaidChart.com
+ *
+ * @param options - Options.
+ */
+export function plugin({ client, ...options }: MCPluginOptions) {
+  return async function (tree: Root, file: VFile) {
+    const mermaidNodes: Code[] = [];
+    visit(tree, (node) => {
+      if (node.type === 'code' && node?.lang === 'mermaid') {
+        mermaidNodes.push(node);
+      }
+    });
+
+    if (mermaidNodes.length == 0) {
+      console.log(`○ - ${file.basename} ignored, as it has no mermaid diagrams`);
+    }
+
+    for (const node of mermaidNodes) {
+      const title = `${file.basename}:${node.position?.start.line}`;
+      switch (options.command) {
+        case 'link':
+          node.value = await link(node.value, client, {
+            cache: options.cache,
+            title: ``,
+            getProjectId: options.getProjectId,
+          });
+          break;
+        case 'pull': {
+          const newValue = await pull(node.value, client, { title });
+
+          if (node.value === newValue) {
+            console.log(`✅ - ${title} is up to date`);
+          } else {
+            if (options['check']) {
+              console.log(`❌ - ${title} would be updated`);
+              process.exitCode = 1;
+            } else {
+              node.value = newValue;
+              console.log(`✅ - ${title} will be updated`);
+            }
+          }
+          break;
+        }
+        case 'push':
+          await push(node.value, client, { title });
+      }
+    }
+  };
+}
+
+/**
+ * Read, process, and potentially update the given markdown file.
+ *
+ * @param inputFile - The file to read from, and potentially write to.
+ * @param options - Options to pass to {@link plugin}.
+ */
+export async function processMarkdown(inputFile: string, options: MCPluginOptions) {
+  const inVFile = await read(inputFile);
+  const outVFile = await remark().use(plugin, options).process(inVFile);
+
+  switch (options.command) {
+    case 'link':
+    case 'pull':
+      await write(outVFile);
+      break;
+    case 'push':
+    // no need to write-back any data to the file
+  }
+}

packages/cli/test/fixtures/linked-markdown-file.md

@@ -0,0 +1,24 @@
+# Test markdown file with linked diagrams
+
+Here is a markdown comment: <!-- Hello World -->
+
+This is a flowchart diagram
+
+```mermaid
+---
+id: xxxxxxx-flowchart
+---
+flowchart
+    A[Hello World]
+```
+
+While this is a pie diagram
+
+```mermaid
+---
+id: xxxxxxx-pie
+---
+pie
+    "Flowchart" : 1
+    "Pie" : 1
+```

packages/cli/test/fixtures/unlinked-markdown-file.md

@@ -0,0 +1,18 @@
+# Test markdown file
+
+Here is a markdown comment: <!-- Hello World -->
+
+This is a flowchart diagram
+
+```mermaid
+flowchart
+    A[Hello World]
+```
+
+While this is a pie diagram
+
+```mermaid
+pie
+    "Flowchart" : 1
+    "Pie" : 1
+```