build(docs): hide YAML when building for GitHub

YAML front-matter is currently only used for Vitepress.

Because of that, to avoid confusion, we can remove this YAML
front-matter when converting the Markdown in packages/mermaid/src/docs
to go into the `docs/` folder for GitHub browsing.

docs/syntax/flowchart.md

@@ -1,8 +1,3 @@
----
-title: Flowcharts Syntax
-outline: 'deep' # shows all h3 headings in outline in Vitepress
----
-
 > **Warning**
 >
 > ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.

packages/mermaid/src/docs.mts

@@ -207,6 +207,11 @@ interface TransformMarkdownAstOptions {
   originalFilename: string;
   /** If `true`, add a warning that the file is autogenerated */
   addAutogeneratedWarning?: boolean;
+  /**
+   * If `true`, remove the YAML metadata from the Markdown input.
+   * Generally, YAML metadata is only used for Vitepress.
+   */
+  removeYAML?: boolean;
 }
 
 /**
@@ -224,6 +229,7 @@ interface TransformMarkdownAstOptions {
 export function transformMarkdownAst({
   originalFilename,
   addAutogeneratedWarning,
+  removeYAML,
 }: TransformMarkdownAstOptions) {
   return (tree: Root, _file?: any): Root => {
     const astWithTransformedBlocks = flatmap(tree, (node: Code) => {
@@ -249,7 +255,7 @@ export function transformMarkdownAst({
       }
 
       return [node]; // default is to do nothing to the node
-    });
+    }) as Root;
 
     if (addAutogeneratedWarning) {
       // Add the header to the start of the file
@@ -262,6 +268,14 @@ export function transformMarkdownAst({
       }
     }
 
+    if (removeYAML) {
+      const firstNode = astWithTransformedBlocks.children[0];
+      if (firstNode.type == 'yaml') {
+        // YAML is currently only used for Vitepress metadata, so we should remove it for GFM output
+        astWithTransformedBlocks.children.shift();
+      }
+    }
+
     return astWithTransformedBlocks;
   };
 }
@@ -286,7 +300,12 @@ const transformMarkdown = (file: string) => {
   let transformed = remark()
     .use(remarkGfm)
     .use(remarkFrontmatter, ['yaml']) // support YAML front-matter in Markdown
-    .use(transformMarkdownAst, { originalFilename: file, addAutogeneratedWarning: !noHeader }) // mermaid project specific plugin
+    .use(transformMarkdownAst, {
+      // mermaid project specific plugin
+      originalFilename: file,
+      addAutogeneratedWarning: !noHeader,
+      removeYAML: !noHeader,
+    })
     .processSync(doc)
     .toString();
 

packages/mermaid/src/docs.spec.ts

@@ -1,13 +1,15 @@
 import { transformMarkdownAst, transformToBlockQuote } from './docs.mjs';
 
-import { remark as remarkBuilder } from 'remark'; // import it this way so we can mock it
+import { remark } from 'remark'; // import it this way so we can mock it
+import remarkFrontmatter from 'remark-frontmatter';
 import { vi, afterEach, describe, it, expect } from 'vitest';
 
 afterEach(() => {
   vi.restoreAllMocks();
 });
 
 const originalFilename = 'example-input-filename.md';
+const remarkBuilder = remark().use(remarkFrontmatter, ['yaml']); // support YAML front-matter in Markdown
 
 describe('docs.mts', () => {
   describe('transformMarkdownAst', () => {
@@ -79,6 +81,28 @@ describe('docs.mts', () => {
         });
       });
     });
+
+    it('should remove YAML if `removeYAML` is true', async () => {
+      const contents = `---
+title: Flowcharts Syntax
+---
+
+This Markdown should be kept.
+`;
+      const withYaml = (
+        await remarkBuilder().use(transformMarkdownAst, { originalFilename }).process(contents)
+      ).toString();
+      // no change
+      expect(withYaml).toEqual(contents);
+
+      const withoutYaml = (
+        await remarkBuilder()
+          .use(transformMarkdownAst, { originalFilename, removeYAML: true })
+          .process(contents)
+      ).toString();
+      // no change
+      expect(withoutYaml).toEqual('This Markdown should be kept.\n');
+    });
   });
 
   describe('transformToBlockQuote', () => {