feat(cli): support GFM (github flavored markdown)

[remark][1] by default only supports [CommonMark][2], however, with
[remark-gfm][3] and [remark-frontmatter][4] we can support
[GFM (GitHub flavoured markdown][5], which is used by GitHub.

[1]: https://github.com/remarkjs/remark
[2]: https://commonmark.org/
[3]: https://github.com/remarkjs/remark-gfm
[4]: https://github.com/remarkjs/remark-frontmatter
[5]: https://github.github.com/gfm/

packages/cli/README.md

@@ -30,8 +30,8 @@ npx @mermaidchart/cli --help
 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.
+they can be stored within ```` ```mermaid```` code blocks within `.md`
+[GFM](https://github.github.com/gfm/) markdown files.
 
 ### `login`
 

packages/cli/package.json

@@ -62,6 +62,8 @@
     "commander": "^11.1.0",
     "js-yaml": "^4.1.0",
     "remark": "^15.0.1",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.0",
     "to-vfile": "^8.0.0",
     "unist-util-visit": "^5.0.0"
   }

packages/cli/src/commander.test.ts

@@ -17,6 +17,8 @@ const LINKED_MARKDOWN_FILE = 'test/fixtures/linked-markdown-file.md';
 const PARTIALLY_LINKED_MARKDOWN_FILE = 'test/fixtures/partially-linked-markdown-file.md';
 /** Markdown file that has unlinked Mermaid diagrams */
 const UNLINKED_MARKDOWN_FILE = 'test/fixtures/unlinked-markdown-file.md';
+/** Markdown file that has non-standard Markdown features like YAML frontmatter */
+const UNUSUAL_MARKDOWN_FILE = 'test/fixtures/unusual-markdown-file.md';
 
 type Optional<T> = T | undefined;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -323,6 +325,37 @@ describe('link', () => {
 
     expect(file).toMatch(`id: second-id\n`);
   });
+
+  it('should handle unusual markdown formatting', async () => {
+    const unusualMarkdownFile = 'test/output/unusual-markdown-file.md';
+    await copyFile(UNUSUAL_MARKDOWN_FILE, unusualMarkdownFile);
+
+    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,
+      documentID: 'my-mocked-diagram-id',
+    });
+    await program.parseAsync(['--config', CONFIG_AUTHED, 'link', unusualMarkdownFile], {
+      from: 'user',
+    });
+
+    const file = await readFile(unusualMarkdownFile, { encoding: 'utf8' });
+
+    const idLineRegex = /^.*id: my-mocked-diagram-id\n/gm;
+
+    expect(file).toMatch(idLineRegex);
+    // other than the added `id: xxxx` field, everything else should be identical,
+    // although in practice, we'd expect some formatting changes
+    expect(file.replace(idLineRegex, '')).toStrictEqual(
+      await readFile(UNUSUAL_MARKDOWN_FILE, { encoding: 'utf8' }),
+    );
+  });
 });
 
 describe('pull', () => {

packages/cli/src/remark.ts

@@ -5,6 +5,8 @@ import type { MermaidChart } from '@mermaidchart/sdk';
 import { type LinkOptions, link, pull, push } from './methods.js';
 
 import { remark } from 'remark';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkGfm from 'remark-gfm';
 import { read, write } from 'to-vfile';
 interface MCPluginCommonOptions {
   /** Authenticated client */
@@ -87,7 +89,11 @@ export function plugin({ client, ...options }: MCPluginOptions) {
  */
 export async function processMarkdown(inputFile: string, options: MCPluginOptions) {
   const inVFile = await read(inputFile);
-  const outVFile = await remark().use(plugin, options).process(inVFile);
+  const outVFile = await remark()
+    .use(remarkFrontmatter)
+    .use(remarkGfm)
+    .use(plugin, options)
+    .process(inVFile);
 
   switch (options.command) {
     case 'link':

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

@@ -0,0 +1,49 @@
+---
+description: |
+    Here is a YAML frontmatter, supported by GitHub (by not GFM!!), Docusaurus,
+    Vitepress, etc.
+---
+
+# This is an unusual markdown file with non-standard syntax
+
+See <https://github.github.com/gfm> for some of GitHub's
+GitHub Flavored Markdown extensions.
+
+Here is a markdown comment: <!-- Hello World -->
+
+This is my text with a footnote.[^1]
+
+[^1]: This is my footnote.
+
+This is a ~~strikethrough~~.
+
+Here is some math (not part of GFM): $ x=5 + 1 $
+
+Here is some more math:
+
+```math
+\sum_{n=1}^{\infty} x = \infty
+```
+
+## Here is a table
+
+| foo | bar |
+| --- | --- |
+| baz | bim |
+
+## Here is my Mermaid diagram in a quote in a list
+
+* This is my list
+  * This is my list
+    1. This is another list entry.
+    2. And another one.
+    3. This is my entry with the diagram:
+       > Here is my quote with the diagram:
+       >
+       > ```mermaid
+       > ---
+       > title: This is my diagram title
+       > ---
+       > flowchart
+       >     A[Hello World]
+       > ```