build(docs): handle YAML edgecases in markdown

Our current method of adding a entry using `+=` is not safe in YAML, since it's valid to make a YAML object entirely in JSON, see mermaid-js#4640 (comment) We're already using `js-yaml` elsewhere in this file, so we may as well use it for parsing/stringifying. Reported-by: Remco Haszing <[email protected]>
Incognito · Jul 19, 2023 · 4d2d790 · 4d2d790
1 parent af9b3f7
commit 4d2d790
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 15 deletions.
diff --git a/packages/mermaid/src/docs.mts b/packages/mermaid/src/docs.mts
@@ -30,10 +30,19 @@
  * @todo Write a test file for this. (Will need to be able to deal .mts file. Jest has trouble with
  *   it.)
  */
+// @ts-ignore: we're importing internal jsonschema2md functions
+import { default as schemaLoader } from '@adobe/jsonschema2md/lib/schemaProxy.js';
+// @ts-ignore: we're importing internal jsonschema2md functions
+import { default as traverseSchemas } from '@adobe/jsonschema2md/lib/traverseSchema.js';
+// @ts-ignore: we're importing internal jsonschema2md functions
+import { default as buildMarkdownFromSchema } from '@adobe/jsonschema2md/lib/markdownBuilder.js';
+// @ts-ignore: we're importing internal jsonschema2md functions
+import { default as jsonSchemaReadmeBuilder } from '@adobe/jsonschema2md/lib/readmeBuilder.js';
 import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, rmdirSync } from 'fs';
 import { exec } from 'child_process';
 import { globby } from 'globby';
 import { JSDOM } from 'jsdom';
+import { dump, load, JSON_SCHEMA } from 'js-yaml';
 import type { Code, ListItem, Root, Text, YAML } from 'mdast';
 import { posix, dirname, relative, join } from 'path';
 import prettier from 'prettier';
@@ -286,10 +295,12 @@ export function transformMarkdownAst({
         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}`
-      )}`;
+      yamlFrontMatter.value = dump({
+        ...(load(yamlFrontMatter.value, { schema: JSON_SCHEMA }) as
+          | Record<string, unknown>
+          | undefined),
+        editLink: `https://github.com/mermaid-js/mermaid/edit/develop/${filePathFromRoot}`,
+      });
     }
 
     if (removeYAML) {
@@ -346,16 +357,6 @@ const transformMarkdown = (file: string) => {
   copyTransformedContents(file, !verifyOnly, formatted);
 };
 
-import { load, JSON_SCHEMA } from 'js-yaml';
-// @ts-ignore: we're importing internal jsonschema2md functions
-import { default as schemaLoader } from '@adobe/jsonschema2md/lib/schemaProxy.js';
-// @ts-ignore: we're importing internal jsonschema2md functions
-import { default as traverseSchemas } from '@adobe/jsonschema2md/lib/traverseSchema.js';
-// @ts-ignore: we're importing internal jsonschema2md functions
-import { default as buildMarkdownFromSchema } from '@adobe/jsonschema2md/lib/markdownBuilder.js';
-// @ts-ignore: we're importing internal jsonschema2md functions
-import { default as jsonSchemaReadmeBuilder } from '@adobe/jsonschema2md/lib/readmeBuilder.js';
-
 /**
  * Transforms the given JSON Schema into Markdown documentation
  */

diff --git a/packages/mermaid/src/docs.spec.ts b/packages/mermaid/src/docs.spec.ts
@@ -119,7 +119,9 @@ This Markdown should be kept.
     ).toString();
     expect(withYaml).toEqual(`---
 title: Flowcharts Syntax
-editLink: "https://github.com/mermaid-js/mermaid/edit/develop/packages/mermaid/example-input-filename.md"
+editLink: >-
+  https://github.com/mermaid-js/mermaid/edit/develop/packages/mermaid/example-input-filename.md
+
 ---
 
 This Markdown should be kept.