From 57ee181fad6cd3f6be162297e18ad25e37766162 Mon Sep 17 00:00:00 2001
From: Alois Klink <alois@aloisklink.com>
Date: Thu, 13 Jul 2023 23:59:56 +0100
Subject: [PATCH] build(docs): add `editLink: ` to MD frontmatter

Add a YAML front-matter entry called `editLink` to Markdown files in
Vitepress, e.g.

```markdown
---
editLink: "https://github.com/mermaid-js/mermaid/edit/develop/packages/mermaid/src/schemas/config.schema.yaml"
---

Here is my markdown file!
```

Although Vitepress doesn't officially support adding a URL as a
`editLink:` YAML front-matter, we can add a custom `editLink` function
to our Vitepress config that does allow it.
---
 packages/mermaid/src/docs.mts     | 26 +++++++++++++++++++++++++-
 packages/mermaid/src/docs.spec.ts | 21 +++++++++++++++++++++
 2 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/packages/mermaid/src/docs.mts b/packages/mermaid/src/docs.mts
index b3f356f34..227449a0a 100644
--- a/packages/mermaid/src/docs.mts
+++ b/packages/mermaid/src/docs.mts
@@ -34,7 +34,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, rmdirSync }
 import { exec } from 'child_process';
 import { globby } from 'globby';
 import { JSDOM } from 'jsdom';
-import type { Code, ListItem, Root, Text } from 'mdast';
+import type { Code, ListItem, Root, Text, YAML } from 'mdast';
 import { posix, dirname, relative, join } from 'path';
 import prettier from 'prettier';
 import { remark } from 'remark';
@@ -209,6 +209,8 @@ interface TransformMarkdownAstOptions {
   originalFilename: string;
   /** If `true`, add a warning that the file is autogenerated */
   addAutogeneratedWarning?: boolean;
+  /** If `true`, adds an `editLink: "https://..."` YAML frontmatter field */
+  addEditLink?: boolean;
   /**
    * If `true`, remove the YAML metadata from the Markdown input.
    * Generally, YAML metadata is only used for Vitepress.
@@ -231,6 +233,7 @@ interface TransformMarkdownAstOptions {
 export function transformMarkdownAst({
   originalFilename,
   addAutogeneratedWarning,
+  addEditLink,
   removeYAML,
 }: TransformMarkdownAstOptions) {
   return (tree: Root, _file?: any): Root => {
@@ -270,6 +273,25 @@ export function transformMarkdownAst({
       }
     }
 
+    if (addEditLink) {
+      // add originalFilename as custom editLink in YAML frontmatter
+      let yamlFrontMatter: YAML;
+      if (astWithTransformedBlocks.children[0].type === 'yaml') {
+        yamlFrontMatter = astWithTransformedBlocks.children[0];
+      } else {
+        yamlFrontMatter = {
+          type: 'yaml',
+          value: '',
+        };
+        astWithTransformedBlocks.children.unshift(yamlFrontMatter);
+      }
+      const filePathFromRoot = posix.join('packages/mermaid', originalFilename);
+      // TODO, should we replace this with proper YAML parsing?
+      yamlFrontMatter.value += `\neditLink: ${JSON.stringify(
+        `https://github.com/mermaid-js/mermaid/edit/develop/${filePathFromRoot}`
+      )}`;
+    }
+
     if (removeYAML) {
       const firstNode = astWithTransformedBlocks.children[0];
       if (firstNode.type == 'yaml') {
@@ -306,6 +328,7 @@ const transformMarkdown = (file: string) => {
       // mermaid project specific plugin
       originalFilename: file,
       addAutogeneratedWarning: !noHeader,
+      addEditLink: noHeader,
       removeYAML: !noHeader,
     })
     .processSync(doc)
@@ -427,6 +450,7 @@ async function transormJsonSchema(file: string) {
         // mermaid project specific plugin
         originalFilename: file,
         addAutogeneratedWarning: !noHeader,
+        addEditLink: noHeader,
         removeYAML: !noHeader,
       });
 
diff --git a/packages/mermaid/src/docs.spec.ts b/packages/mermaid/src/docs.spec.ts
index 50feaee6a..bea833fd9 100644
--- a/packages/mermaid/src/docs.spec.ts
+++ b/packages/mermaid/src/docs.spec.ts
@@ -105,6 +105,27 @@ This Markdown should be kept.
     });
   });
 
+  it('should add an editLink in the YAML frontmatter if `addEditLink: true`', async () => {
+    const contents = `---
+title: Flowcharts Syntax
+---
+
+This Markdown should be kept.
+`;
+    const withYaml = (
+      await remarkBuilder()
+        .use(transformMarkdownAst, { originalFilename, addEditLink: true })
+        .process(contents)
+    ).toString();
+    expect(withYaml).toEqual(`---
+title: Flowcharts Syntax
+editLink: "https://github.com/mermaid-js/mermaid/edit/develop/packages/mermaid/example-input-filename.md"
+---
+
+This Markdown should be kept.
+`);
+  });
+
   describe('transformToBlockQuote', () => {
     // TODO Is there a way to test this with --vitepress given as a process argument?