From 0c85e8ee53725f0371c2fe0952c011846e971c1b Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Mon, 5 Sep 2022 18:27:58 -0700
Subject: [PATCH 01/27] eslint (mostly use double quotes)

---
 src/docs.mts | 48 ++++++++++++++++++++++++------------------------
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/src/docs.mts b/src/docs.mts
index 76594c4bf4..9e3b9ddefd 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -1,26 +1,26 @@
-import { remark } from 'remark';
-import type { Code, Root } from 'mdast';
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { remark } from "remark";
+import type { Code, Root } from "mdast";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
 // @ts-ignore
-import flatmap from 'unist-util-flatmap';
-import { globby } from 'globby';
-import { join, dirname } from 'path';
-import { exec } from 'child_process';
-import prettier from 'prettier';
+import flatmap from "unist-util-flatmap";
+import { globby } from "globby";
+import { join, dirname } from "path";
+import { exec } from "child_process";
+import prettier from "prettier";
 
-const verify = process.argv.includes('--verify');
-const git = process.argv.includes('--git');
+const verify = process.argv.includes("--verify");
+const git = process.argv.includes("--git");
 let fileChanged = false;
 // Possible Improvement: combine with lint-staged to only copy files that have changed
 const prepareOutFile = (file: string): string => {
-  const outFile = join('docs', file.replace('src/docs/', ''));
+  const outFile = join("docs", file.replace("src/docs/", ""));
   mkdirSync(dirname(outFile), { recursive: true });
   return outFile;
 };
 
 const verifyAndCopy = (file: string, content?: string) => {
   const outFile = prepareOutFile(file);
-  const existingBuffer = existsSync(outFile) ? readFileSync(outFile) : Buffer.from('#NEW FILE#');
+  const existingBuffer = existsSync(outFile) ? readFileSync(outFile) : Buffer.from("#NEW FILE#");
   const newBuffer = content ? Buffer.from(content) : readFileSync(file);
   if (existingBuffer.equals(newBuffer)) {
     // Files are same, skip.
@@ -34,16 +34,16 @@ const verifyAndCopy = (file: string, content?: string) => {
 };
 
 const transform = (file: string) => {
-  const doc = readFileSync(file, 'utf8');
+  const doc = readFileSync(file, "utf8");
   const ast: Root = remark.parse(doc);
   const out = flatmap(ast, (c: Code) => {
-    if (c.type !== 'code' || !c.lang?.startsWith('mermaid')) {
+    if (c.type !== "code" || !c.lang?.startsWith("mermaid")) {
       return [c];
     }
-    if (c.lang === 'mermaid' || c.lang === 'mmd') {
-      c.lang = 'mermaid-example';
+    if (c.lang === "mermaid" || c.lang === "mmd") {
+      c.lang = "mermaid-example";
     }
-    return [c, Object.assign({}, c, { lang: 'mermaid' })];
+    return [c, Object.assign({}, c, { lang: "mermaid" })];
   });
 
   const transformed = `# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.\n${remark.stringify(
@@ -52,20 +52,20 @@ const transform = (file: string) => {
   verifyAndCopy(
     file,
     prettier.format(transformed, {
-      parser: 'markdown',
+      parser: "markdown",
       useTabs: false,
       tabWidth: 2,
-      endOfLine: 'auto',
+      endOfLine: "auto",
       printWidth: 100,
-      singleQuote: true,
+      singleQuote: true
     })
   );
 };
 
 (async () => {
-  const mdFiles = await globby(['./src/docs/**/*.md'], { dot: true });
+  const mdFiles = await globby(["./src/docs/**/*.md"], { dot: true });
   mdFiles.forEach(transform);
-  const nonMDFiles = await globby(['src/docs/**', '!**/*.md'], { dot: true });
+  const nonMDFiles = await globby(["src/docs/**", "!**/*.md"], { dot: true });
   nonMDFiles.forEach((file) => {
     verifyAndCopy(file);
   });
@@ -77,8 +77,8 @@ const transform = (file: string) => {
       process.exit(1);
     }
     if (git) {
-      console.log('Adding changes in docs folder to git');
-      exec('git add docs');
+      console.log("Adding changes in docs folder to git");
+      exec("git add docs");
     }
   }
 })();

From 703b7eb91d38d0248d2bccfe7d1b753355326a45 Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Mon, 5 Sep 2022 18:33:17 -0700
Subject: [PATCH 02/27] rename vars so intent is clearer, add doc, use
 constants

---
 src/docs.mts | 55 +++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 44 insertions(+), 11 deletions(-)

diff --git a/src/docs.mts b/src/docs.mts
index 9e3b9ddefd..fe38cf52e1 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -6,18 +6,41 @@ import flatmap from "unist-util-flatmap";
 import { globby } from "globby";
 import { join, dirname } from "path";
 import { exec } from "child_process";
+// @ts-ignore
 import prettier from "prettier";
 
-const verify = process.argv.includes("--verify");
+const SOURCE_DOCS_DIR = 'src/docs/';
+const FINAL_DOCS_DIR = 'docs/';
+const AUTOGENERATED_TEXT =
+  "# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.";
+
+const verifyOnly = process.argv.includes("--verify");
 const git = process.argv.includes("--git");
-let fileChanged = false;
-// Possible Improvement: combine with lint-staged to only copy files that have changed
+
+let filesWereChanged = false;
+
+
+/**
+ * Given a source file name and path, return the documentation destination full path and file name
+ * Create the destination path if it does not already exist.
+ * Possible Improvement: combine with lint-staged to only copy files that have changed
+ *
+ * @param file {string} name of the file (including full path)
+ * @returns {string} name of the file with the path changed from src/docs to docs
+ */
 const prepareOutFile = (file: string): string => {
-  const outFile = join("docs", file.replace("src/docs/", ""));
+  const outFile = join(FINAL_DOCS_DIR, file.replace(SOURCE_DOCS_DIR, ""));
   mkdirSync(dirname(outFile), { recursive: true });
   return outFile;
 };
 
+/**
+ * Verify that a file was changed and (potentially) write the new contents out to the file. Log a message to the console
+ * If the file was not changed, do nothing. (No message is logged to the console.)
+ *
+ * @param file {string} name of the file that will be verified
+ * @param content {string} new contents for the file
+ */
 const verifyAndCopy = (file: string, content?: string) => {
   const outFile = prepareOutFile(file);
   const existingBuffer = existsSync(outFile) ? readFileSync(outFile) : Buffer.from("#NEW FILE#");
@@ -27,12 +50,22 @@ const verifyAndCopy = (file: string, content?: string) => {
     return;
   }
   console.log(`File changed: ${outFile}`);
-  fileChanged = true;
-  if (!verify) {
+  filesWereChanged = true;
+  if (!verifyOnly) {
     writeFileSync(outFile, newBuffer);
   }
 };
 
+/**
+ * Transform a markdown file and write the transformed file to the directory for published documentation
+ *   1. add a `mermaid-example` block before every `mermaid` or `mmd` block
+ *      On the docsify site (one place where the documentation is published), this will show the code used for the mermaid diagram
+ *   2. add the text that says the file is automatically generated
+ *   3. use prettier to format the file
+ *   Verify that the file has been changed and write out the changes
+ *
+ * @param file {string} name of the file that will be verified
+ */
 const transform = (file: string) => {
   const doc = readFileSync(file, "utf8");
   const ast: Root = remark.parse(doc);
@@ -46,9 +79,9 @@ const transform = (file: string) => {
     return [c, Object.assign({}, c, { lang: "mermaid" })];
   });
 
-  const transformed = `# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.\n${remark.stringify(
-    out
-  )}`;
+  // Add the AUTOGENERATED_TEXT to the start of the file
+  const transformed = `${AUTOGENERATED_TEXT}\n${remark.stringify(out)}`;
+
   verifyAndCopy(
     file,
     prettier.format(transformed, {
@@ -69,8 +102,8 @@ const transform = (file: string) => {
   nonMDFiles.forEach((file) => {
     verifyAndCopy(file);
   });
-  if (fileChanged) {
-    if (verify) {
+  if (filesWereChanged) {
+    if (verifyOnly) {
       console.log(
         "Changes detected in files in `docs`. Please run `yarn docs:build` after making changes to 'src/docs' to update the `docs` folder."
       );

From d38f0e9e03794b01bd6ee652e36d98b78478aeeb Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Mon, 5 Sep 2022 18:36:17 -0700
Subject: [PATCH 03/27] adjust console log message if only verifying, if copied
 actually happened

---
 src/docs.mts | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/src/docs.mts b/src/docs.mts
index fe38cf52e1..4ed1f7feb0 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -49,11 +49,18 @@ const verifyAndCopy = (file: string, content?: string) => {
     // Files are same, skip.
     return;
   }
-  console.log(`File changed: ${outFile}`);
+  let changeMsg = 'changed';
+  if (verifyOnly) {
+    changeMsg = 'to be changed';
+  }
+  let logMsg = `  File ${changeMsg}: ${outFile}`
+
   filesWereChanged = true;
   if (!verifyOnly) {
     writeFileSync(outFile, newBuffer);
+    logMsg += ' ...and copied to /docs'
   }
+  console.log(logMsg);
 };
 
 /**

From 6554a41f6dfd054d6540b4e101e25e4b7213780a Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Mon, 5 Sep 2022 18:39:36 -0700
Subject: [PATCH 04/27] transform HTML (insert comment); add console msgs and
 clarify; add file doc

---
 src/docs.mts | 71 +++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 65 insertions(+), 6 deletions(-)

diff --git a/src/docs.mts b/src/docs.mts
index 4ed1f7feb0..d211e0fbff 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -1,6 +1,24 @@
+/**
+ * @overview Process and potentially transform documentation source files into files suitable for publishing.
+ *   Copy files from the source directory (/src/docs) to the directory used for the final, published documentation (/docs).
+ *   The list of files changed (transformed) and copied to /docs are logged to the console.
+ *   If a file in /src/docs has the same contents in /docs, nothing is done (it is not copied to /docs).
+ *
+ * @example docs
+ * @example docs --verify
+ *   If the --verify option is used, no files will be copied to /docs, but the list of files to be changed is still shown on the console.
+ *   A message to the console will show that this command should be run without the --verify flag so that the 'docs' folder is be updated.
+ *   Note that the command will return an exit code (1), which will show that it failed.
+ * @example docs --git
+ *   If the --git option is used, the command `git add docs` will be run
+ *
+ */
+
 import { remark } from "remark";
 import type { Code, Root } from "mdast";
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { JSDOM } from "jsdom";
+
 // @ts-ignore
 import flatmap from "unist-util-flatmap";
 import { globby } from "globby";
@@ -63,6 +81,10 @@ const verifyAndCopy = (file: string, content?: string) => {
   console.log(logMsg);
 };
 
+const readSyncedUTF8file = (file: string): string => {
+  return readFileSync(file, "utf8");
+}
+
 /**
  * Transform a markdown file and write the transformed file to the directory for published documentation
  *   1. add a `mermaid-example` block before every `mermaid` or `mmd` block
@@ -73,8 +95,8 @@ const verifyAndCopy = (file: string, content?: string) => {
  *
  * @param file {string} name of the file that will be verified
  */
-const transform = (file: string) => {
-  const doc = readFileSync(file, "utf8");
+const transformMarkdown = (file: string) => {
+  const doc = readSyncedUTF8file(file);
   const ast: Root = remark.parse(doc);
   const out = flatmap(ast, (c: Code) => {
     if (c.type !== "code" || !c.lang?.startsWith("mermaid")) {
@@ -102,17 +124,54 @@ const transform = (file: string) => {
   );
 };
 
+/**
+ * Transform a HTML file and write the transformed file to the directory for published documentation
+ *   - add the text that says the file is automatically generated
+ *   Verify that the file has been changed and write out the changes
+ *
+ * @param filename {string} name of the HTML file to transform
+ */
+const transformHtml = (filename: string) => {
+
+  /**
+   * Insert the '...auto generated...' comment into an HTML file after the <html> element
+   *
+   * @param fname {string} file name that should have the comment inserted
+   * @returns {string} the contents of the file with the comment inserted
+   */
+  function insertAutoGeneratedComment(fname: string): string {
+    const fileContents = readSyncedUTF8file(fname);
+    const jsdom = new JSDOM(fileContents);
+    const htmlDoc = jsdom.window.document;
+    const autoGeneratedComment = jsdom.window.document.createComment(AUTOGENERATED_TEXT);
+
+    let rootElement = htmlDoc.documentElement;
+    rootElement.prepend(autoGeneratedComment);
+    return jsdom.serialize();
+  }
+
+  let transformedHTML = insertAutoGeneratedComment(filename);
+  verifyAndCopy(filename, transformedHTML);
+};
+
 (async () => {
+  console.log("Transforming markdown files...");
   const mdFiles = await globby(["./src/docs/**/*.md"], { dot: true });
-  mdFiles.forEach(transform);
-  const nonMDFiles = await globby(["src/docs/**", "!**/*.md"], { dot: true });
-  nonMDFiles.forEach((file) => {
+  mdFiles.forEach(transformMarkdown);
+
+  console.log("Transforming html files...");
+  const htmlFiles = await globby(["./src/docs/**/*.html"], { dot: true });
+  htmlFiles.forEach(transformHtml);
+
+  console.log("Transforming all other files...");
+  const otherFiles = await globby(["src/docs/**", "!**/*.md", "!**/*.html"], { dot: true });
+  otherFiles.forEach((file) => {
     verifyAndCopy(file);
   });
   if (filesWereChanged) {
     if (verifyOnly) {
       console.log(
-        "Changes detected in files in `docs`. Please run `yarn docs:build` after making changes to 'src/docs' to update the `docs` folder."
+        "Changes detected in files in `src/docs`. Please run `yarn docs:build` after making changes to 'src/docs' to update the `docs` folder."
       );
       process.exit(1);
     }

From 0832b24d66d07b9f71160ad29edae60026cd35e8 Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Mon, 5 Sep 2022 23:43:57 -0700
Subject: [PATCH 05/27] use single quotes; use const instead of let (2); use
 const instead of function

---
 src/docs.mts | 78 +++++++++++++++++++++++++---------------------------
 1 file changed, 38 insertions(+), 40 deletions(-)

diff --git a/src/docs.mts b/src/docs.mts
index d211e0fbff..ad9ab1bf07 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -14,30 +14,29 @@
  *
  */
 
-import { remark } from "remark";
-import type { Code, Root } from "mdast";
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
-import { JSDOM } from "jsdom";
+import { remark } from 'remark';
+import type { Code, Root } from 'mdast';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { JSDOM } from 'jsdom';
 
 // @ts-ignore
-import flatmap from "unist-util-flatmap";
-import { globby } from "globby";
-import { join, dirname } from "path";
-import { exec } from "child_process";
+import flatmap from 'unist-util-flatmap';
+import { globby } from 'globby';
+import { join, dirname } from 'path';
+import { exec } from 'child_process';
 // @ts-ignore
-import prettier from "prettier";
+import prettier from 'prettier';
 
 const SOURCE_DOCS_DIR = 'src/docs/';
 const FINAL_DOCS_DIR = 'docs/';
 const AUTOGENERATED_TEXT =
-  "# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.";
+  '# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.';
 
-const verifyOnly = process.argv.includes("--verify");
-const git = process.argv.includes("--git");
+const verifyOnly = process.argv.includes('--verify');
+const git = process.argv.includes('--git');
 
 let filesWereChanged = false;
 
-
 /**
  * Given a source file name and path, return the documentation destination full path and file name
  * Create the destination path if it does not already exist.
@@ -47,7 +46,7 @@ let filesWereChanged = false;
  * @returns {string} name of the file with the path changed from src/docs to docs
  */
 const prepareOutFile = (file: string): string => {
-  const outFile = join(FINAL_DOCS_DIR, file.replace(SOURCE_DOCS_DIR, ""));
+  const outFile = join(FINAL_DOCS_DIR, file.replace(SOURCE_DOCS_DIR, ''));
   mkdirSync(dirname(outFile), { recursive: true });
   return outFile;
 };
@@ -61,7 +60,7 @@ const prepareOutFile = (file: string): string => {
  */
 const verifyAndCopy = (file: string, content?: string) => {
   const outFile = prepareOutFile(file);
-  const existingBuffer = existsSync(outFile) ? readFileSync(outFile) : Buffer.from("#NEW FILE#");
+  const existingBuffer = existsSync(outFile) ? readFileSync(outFile) : Buffer.from('#NEW FILE#');
   const newBuffer = content ? Buffer.from(content) : readFileSync(file);
   if (existingBuffer.equals(newBuffer)) {
     // Files are same, skip.
@@ -71,19 +70,19 @@ const verifyAndCopy = (file: string, content?: string) => {
   if (verifyOnly) {
     changeMsg = 'to be changed';
   }
-  let logMsg = `  File ${changeMsg}: ${outFile}`
+  let logMsg = `  File ${changeMsg}: ${outFile}`;
 
   filesWereChanged = true;
   if (!verifyOnly) {
     writeFileSync(outFile, newBuffer);
-    logMsg += ' ...and copied to /docs'
+    logMsg += ' ...and copied to /docs';
   }
   console.log(logMsg);
 };
 
 const readSyncedUTF8file = (file: string): string => {
-  return readFileSync(file, "utf8");
-}
+  return readFileSync(file, 'utf8');
+};
 
 /**
  * Transform a markdown file and write the transformed file to the directory for published documentation
@@ -99,13 +98,13 @@ const transformMarkdown = (file: string) => {
   const doc = readSyncedUTF8file(file);
   const ast: Root = remark.parse(doc);
   const out = flatmap(ast, (c: Code) => {
-    if (c.type !== "code" || !c.lang?.startsWith("mermaid")) {
+    if (c.type !== 'code' || !c.lang?.startsWith('mermaid')) {
       return [c];
     }
-    if (c.lang === "mermaid" || c.lang === "mmd") {
-      c.lang = "mermaid-example";
+    if (c.lang === 'mermaid' || c.lang === 'mmd') {
+      c.lang = 'mermaid-example';
     }
-    return [c, Object.assign({}, c, { lang: "mermaid" })];
+    return [c, Object.assign({}, c, { lang: 'mermaid' })];
   });
 
   // Add the AUTOGENERATED_TEXT to the start of the file
@@ -114,12 +113,12 @@ const transformMarkdown = (file: string) => {
   verifyAndCopy(
     file,
     prettier.format(transformed, {
-      parser: "markdown",
+      parser: 'markdown',
       useTabs: false,
       tabWidth: 2,
-      endOfLine: "auto",
+      endOfLine: 'auto',
       printWidth: 100,
-      singleQuote: true
+      singleQuote: true,
     })
   );
 };
@@ -132,39 +131,38 @@ const transformMarkdown = (file: string) => {
  * @param filename {string} name of the HTML file to transform
  */
 const transformHtml = (filename: string) => {
-
   /**
    * Insert the '...auto generated...' comment into an HTML file after the <html> element
    *
-   * @param fname {string} file name that should have the comment inserted
+   * @param fileName {string} file name that should have the comment inserted
    * @returns {string} the contents of the file with the comment inserted
    */
-  function insertAutoGeneratedComment(fname: string): string {
-    const fileContents = readSyncedUTF8file(fname);
+  const insertAutoGeneratedComment = (fileName: string): string => {
+    const fileContents = readSyncedUTF8file(fileName);
     const jsdom = new JSDOM(fileContents);
     const htmlDoc = jsdom.window.document;
     const autoGeneratedComment = jsdom.window.document.createComment(AUTOGENERATED_TEXT);
 
-    let rootElement = htmlDoc.documentElement;
+    const rootElement = htmlDoc.documentElement;
     rootElement.prepend(autoGeneratedComment);
     return jsdom.serialize();
   }
 
-  let transformedHTML = insertAutoGeneratedComment(filename);
+  const transformedHTML = insertAutoGeneratedComment(filename);
   verifyAndCopy(filename, transformedHTML);
 };
 
 (async () => {
-  console.log("Transforming markdown files...");
-  const mdFiles = await globby(["./src/docs/**/*.md"], { dot: true });
+  console.log('Transforming markdown files...');
+  const mdFiles = await globby(['./src/docs/**/*.md'], { dot: true });
   mdFiles.forEach(transformMarkdown);
 
-  console.log("Transforming html files...");
-  const htmlFiles = await globby(["./src/docs/**/*.html"], { dot: true });
+  console.log('Transforming html files...');
+  const htmlFiles = await globby(['./src/docs/**/*.html'], { dot: true });
   htmlFiles.forEach(transformHtml);
 
-  console.log("Transforming all other files...");
-  const otherFiles = await globby(["src/docs/**", "!**/*.md", "!**/*.html"], { dot: true });
+  console.log('Transforming all other files...');
+  const otherFiles = await globby(['src/docs/**', '!**/*.md', '!**/*.html'], { dot: true });
   otherFiles.forEach((file) => {
     verifyAndCopy(file);
   });
@@ -176,8 +174,8 @@ const transformHtml = (filename: string) => {
       process.exit(1);
     }
     if (git) {
-      console.log("Adding changes in docs folder to git");
-      exec("git add docs");
+      console.log('Adding changes in docs folder to git');
+      exec('git add docs');
     }
   }
 })();

From 1a0fe0abf6ac06c38be700aafadce88e9394b5c9 Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Wed, 7 Sep 2022 08:19:34 -0700
Subject: [PATCH 06/27] (comments only) reword main docblock; clarify other
 comments; grammar etc. fixes

---
 src/docs.mts | 57 ++++++++++++++++++++++++++++++----------------------
 1 file changed, 33 insertions(+), 24 deletions(-)

diff --git a/src/docs.mts b/src/docs.mts
index ad9ab1bf07..b090fdd8c7 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -1,17 +1,25 @@
 /**
- * @overview Process and potentially transform documentation source files into files suitable for publishing.
- *   Copy files from the source directory (/src/docs) to the directory used for the final, published documentation (/docs).
- *   The list of files changed (transformed) and copied to /docs are logged to the console.
- *   If a file in /src/docs has the same contents in /docs, nothing is done (it is not copied to /docs).
+ * @file Transform documentation source files into files suitable for publishing and optionally copy
+ *   the transformed files from the source directory to the directory used for the final, published
+ *   documentation directory. The list of files transformed and copied to final documentation
+ *   directory are logged to the console. If a file in the source directory has the same contents in
+ *   the final directory, nothing is done (the final directory is up-to-date).
+ * @example
+ *   docs
+ *   Run with no option flags
  *
- * @example docs
- * @example docs --verify
- *   If the --verify option is used, no files will be copied to /docs, but the list of files to be changed is still shown on the console.
- *   A message to the console will show that this command should be run without the --verify flag so that the 'docs' folder is be updated.
- *   Note that the command will return an exit code (1), which will show that it failed.
- * @example docs --git
- *   If the --git option is used, the command `git add docs` will be run
+ * @example
+ *   docs --verify
+ *   If the --verify option is used, it only _verifies_ that the final directory has been updated with the transformed files in the source directory.
+ *   No files will be copied to the final documentation directory, but the list of files to be changed is shown on the console.
+ *   If the final documentation directory does not have the transformed files from source directory
+ *   - a message to the console will show that this command should be run without the --verify flag so that the final directory is updated, and
+ *   - it will return a fail exit code (1)
  *
+ * @example
+ *   docs --git
+ *   If the --git option is used, the command `git add docs` will be run after all transformations (and/or verifications) have completed successfully
+ *   If not files were transformed, the git command is not run.
  */
 
 import { remark } from 'remark';
@@ -39,11 +47,12 @@ let filesWereChanged = false;
 
 /**
  * Given a source file name and path, return the documentation destination full path and file name
- * Create the destination path if it does not already exist.
- * Possible Improvement: combine with lint-staged to only copy files that have changed
+ * Create the destination path if it does not already exist. Possible Improvement: combine with
+ * lint-staged to only copy files that have changed
  *
- * @param file {string} name of the file (including full path)
- * @returns {string} name of the file with the path changed from src/docs to docs
+ * @param {string} file - Name of the file (including full path)
+ * @returns {string} Name of the file with the path changed from the source directory to final
+ *   documentation directory
  */
 const prepareOutFile = (file: string): string => {
   const outFile = join(FINAL_DOCS_DIR, file.replace(SOURCE_DOCS_DIR, ''));
@@ -86,11 +95,10 @@ const readSyncedUTF8file = (file: string): string => {
 
 /**
  * Transform a markdown file and write the transformed file to the directory for published documentation
- *   1. add a `mermaid-example` block before every `mermaid` or `mmd` block
- *      On the docsify site (one place where the documentation is published), this will show the code used for the mermaid diagram
- *   2. add the text that says the file is automatically generated
- *   3. use prettier to format the file
- *   Verify that the file has been changed and write out the changes
+ * 1. Add a `mermaid-example` block before every `mermaid` or `mmd` block On the docsify site (one
+ *    place where the documentation is published), this will show the code used for the mermaid diagram
+ * 2. Add the text that says the file is automatically generated
+ * 3. Use prettier to format the file Verify that the file has been changed and write out the changes
  *
  * @param file {string} name of the file that will be verified
  */
@@ -124,9 +132,9 @@ const transformMarkdown = (file: string) => {
 };
 
 /**
- * Transform a HTML file and write the transformed file to the directory for published documentation
- *   - add the text that says the file is automatically generated
- *   Verify that the file has been changed and write out the changes
+ * Transform an HTML file and write the transformed file to the directory for published documentation
+ * - Add the text that says the file is automatically generated Verify that the file has been changed
+ *   and write out the changes
  *
  * @param filename {string} name of the HTML file to transform
  */
@@ -135,7 +143,7 @@ const transformHtml = (filename: string) => {
    * Insert the '...auto generated...' comment into an HTML file after the <html> element
    *
    * @param fileName {string} file name that should have the comment inserted
-   * @returns {string} the contents of the file with the comment inserted
+   * @returns {string} The contents of the file with the comment inserted
    */
   const insertAutoGeneratedComment = (fileName: string): string => {
     const fileContents = readSyncedUTF8file(fileName);
@@ -152,6 +160,7 @@ const transformHtml = (filename: string) => {
   verifyAndCopy(filename, transformedHTML);
 };
 
+/** Main method (entry point) */
 (async () => {
   console.log('Transforming markdown files...');
   const mdFiles = await globby(['./src/docs/**/*.md'], { dot: true });

From a878edfb9b230970902c3a38ee5702b7f5a24dad Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Wed, 7 Sep 2022 08:32:52 -0700
Subject: [PATCH 07/27] add and use constants; DRY glob patterns in main

---
 src/docs.mts | 30 +++++++++++++++++++++---------
 1 file changed, 21 insertions(+), 9 deletions(-)

diff --git a/src/docs.mts b/src/docs.mts
index b090fdd8c7..7f1fe9d506 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -38,12 +38,19 @@ import prettier from 'prettier';
 const SOURCE_DOCS_DIR = 'src/docs/';
 const FINAL_DOCS_DIR = 'docs/';
 const AUTOGENERATED_TEXT =
-  '# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.';
+  '# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in ${SOURCE_DOCS_DIR}.';
+
+const LOGMSG_TRANSFORMED = 'transformed';
+const LOGMSG_TO_BE_TRANSFORMED = 'to be transformed';
+const LOGMSG_COPIED = ' ...and copied to ${FINAL_DOCS_DIR}';
+
+const WARN_DOCSDIR_DOESNT_MATCH =
+  "Changed files were transformed in `${SOURCE_DOCS_DIR}` but do not match the files in `${FINAL_DOCS_DIR}`. Please run `yarn docs:build` after making changes to '${SOURCE_DOCS_DIR}' to update the `${FINAL_DOCS_DIR}` directory with the transformed files.";
 
 const verifyOnly = process.argv.includes('--verify');
 const git = process.argv.includes('--git');
 
-let filesWereChanged = false;
+let filesWereTransformed = false;
 
 /**
  * Given a source file name and path, return the documentation destination full path and file name
@@ -162,28 +169,33 @@ const transformHtml = (filename: string) => {
 
 /** Main method (entry point) */
 (async () => {
+  const sourceDirGlob = join(__dirname, SOURCE_DOCS_DIR, '**');
+  const includeFilesStartingWithDot = true;
+
   console.log('Transforming markdown files...');
-  const mdFiles = await globby(['./src/docs/**/*.md'], { dot: true });
+  const mdFiles = await globby([join(sourceDirGlob, '*.md')], { dot: includeFilesStartingWithDot });
   mdFiles.forEach(transformMarkdown);
 
   console.log('Transforming html files...');
-  const htmlFiles = await globby(['./src/docs/**/*.html'], { dot: true });
+  const htmlFiles = await globby([join(sourceDirGlob, '*.html')], {
+    dot: includeFilesStartingWithDot,
+  });
   htmlFiles.forEach(transformHtml);
 
   console.log('Transforming all other files...');
-  const otherFiles = await globby(['src/docs/**', '!**/*.md', '!**/*.html'], { dot: true });
+  const otherFiles = await globby([sourceDirGlob, '!**/*.md', '!**/*.html'], {
+    dot: includeFilesStartingWithDot,
+  });
   otherFiles.forEach((file) => {
     verifyAndCopy(file);
   });
   if (filesWereChanged) {
     if (verifyOnly) {
-      console.log(
-        "Changes detected in files in `src/docs`. Please run `yarn docs:build` after making changes to 'src/docs' to update the `docs` folder."
-      );
+      console.log(WARN_DOCSDIR_DOESNT_MATCH);
       process.exit(1);
     }
     if (git) {
-      console.log('Adding changes in docs folder to git');
+      console.log('Adding changes in ${FINAL_DOCS_DIR} folder to git');
       exec('git add docs');
     }
   }

From 411d641aa25dc203627ebfbc8a1c560984354890 Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Wed, 7 Sep 2022 08:35:51 -0700
Subject: [PATCH 08/27] simplfy method to copy transformation to /docs; extract
 logging

Extract the logging so that it if later we want to turn it on/off with a --verbose flag
---
 src/docs.mts | 65 ++++++++++++++++++++++++++++++++++------------------
 1 file changed, 43 insertions(+), 22 deletions(-)

diff --git a/src/docs.mts b/src/docs.mts
index 7f1fe9d506..e04296424f 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -68,32 +68,50 @@ const prepareOutFile = (file: string): string => {
 };
 
 /**
- * Verify that a file was changed and (potentially) write the new contents out to the file. Log a message to the console
- * If the file was not changed, do nothing. (No message is logged to the console.)
+ * Log messages to the console showing if the transformed file copied to the final documentation
+ * directory or still needs to be copied.
  *
- * @param file {string} name of the file that will be verified
- * @param content {string} new contents for the file
+ * @param {string} filename Name of the file that was transformed
+ * @param {boolean} wasCopied Whether or not the file was copied
+ */
+const logWasOrShouldBeTransformed = (filename: string, wasCopied: boolean) => {
+  let changeMsg: string;
+  let logMsg: string;
+  changeMsg = wasCopied ? LOGMSG_TRANSFORMED : LOGMSG_TO_BE_TRANSFORMED;
+  logMsg = `  File ${changeMsg}: ${filename}`;
+  if (wasCopied) {
+    logMsg += LOGMSG_COPIED;
+  }
+  console.log(logMsg);
+};
+
+/**
+ * If the file contents were transformed, set the _filesWereTransformed_ flag to true and copy the
+ * transformed contents to the final documentation directory if the doCopy flag is true. Log
+ * messages to the console.
+ *
+ * @param {string} file Name of the file that will be verified
+ * @param {string} [transformedContent] New contents for the file
+ * @param {boolean} [doCopy=false] Whether we should copy that transformedContents to the final
+ *   documentation directory. Default is `false`
  */
-const verifyAndCopy = (file: string, content?: string) => {
+const copyTransformedContents = (
+  file: string,
+  transformedContent?: string,
+  doCopy: boolean = false
+) => {
   const outFile = prepareOutFile(file);
   const existingBuffer = existsSync(outFile) ? readFileSync(outFile) : Buffer.from('#NEW FILE#');
-  const newBuffer = content ? Buffer.from(content) : readFileSync(file);
+  const newBuffer = transformedContent ? Buffer.from(transformedContent) : readFileSync(file);
   if (existingBuffer.equals(newBuffer)) {
-    // Files are same, skip.
-    return;
-  }
-  let changeMsg = 'changed';
-  if (verifyOnly) {
-    changeMsg = 'to be changed';
+    return; // Files are same, skip.
   }
-  let logMsg = `  File ${changeMsg}: ${outFile}`;
 
-  filesWereChanged = true;
-  if (!verifyOnly) {
+  filesWereTransformed = true;
+  if (doCopy) {
     writeFileSync(outFile, newBuffer);
-    logMsg += ' ...and copied to /docs';
   }
-  console.log(logMsg);
+  logWasOrShouldBeTransformed(outFile, doCopy);
 };
 
 const readSyncedUTF8file = (file: string): string => {
@@ -102,6 +120,7 @@ const readSyncedUTF8file = (file: string): string => {
 
 /**
  * Transform a markdown file and write the transformed file to the directory for published documentation
+ *
  * 1. Add a `mermaid-example` block before every `mermaid` or `mmd` block On the docsify site (one
  *    place where the documentation is published), this will show the code used for the mermaid diagram
  * 2. Add the text that says the file is automatically generated
@@ -125,7 +144,7 @@ const transformMarkdown = (file: string) => {
   // Add the AUTOGENERATED_TEXT to the start of the file
   const transformed = `${AUTOGENERATED_TEXT}\n${remark.stringify(out)}`;
 
-  verifyAndCopy(
+  copyTransformedContents(
     file,
     prettier.format(transformed, {
       parser: 'markdown',
@@ -140,6 +159,7 @@ const transformMarkdown = (file: string) => {
 
 /**
  * Transform an HTML file and write the transformed file to the directory for published documentation
+ *
  * - Add the text that says the file is automatically generated Verify that the file has been changed
  *   and write out the changes
  *
@@ -161,10 +181,10 @@ const transformHtml = (filename: string) => {
     const rootElement = htmlDoc.documentElement;
     rootElement.prepend(autoGeneratedComment);
     return jsdom.serialize();
-  }
+  };
 
   const transformedHTML = insertAutoGeneratedComment(filename);
-  verifyAndCopy(filename, transformedHTML);
+  copyTransformedContents(filename, transformedHTML);
 };
 
 /** Main method (entry point) */
@@ -187,9 +207,10 @@ const transformHtml = (filename: string) => {
     dot: includeFilesStartingWithDot,
   });
   otherFiles.forEach((file) => {
-    verifyAndCopy(file);
+    copyTransformedContents(file);
   });
-  if (filesWereChanged) {
+
+  if (filesWereTransformed) {
     if (verifyOnly) {
       console.log(WARN_DOCSDIR_DOESNT_MATCH);
       process.exit(1);

From c6ce5a80fa3ddcda81bd617355607124cbc1ec68 Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Wed, 7 Sep 2022 11:00:59 -0700
Subject: [PATCH 09/27] fix: pass in doCopy param

---
 src/docs.mts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/docs.mts b/src/docs.mts
index e04296424f..088e004b02 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -111,7 +111,7 @@ const copyTransformedContents = (
   if (doCopy) {
     writeFileSync(outFile, newBuffer);
   }
-  logWasOrShouldBeTransformed(outFile, doCopy);
+  logWasOrShouldBeTransformed(fileInFinalDocDir, doCopy);
 };
 
 const readSyncedUTF8file = (file: string): string => {
@@ -153,7 +153,8 @@ const transformMarkdown = (file: string) => {
       endOfLine: 'auto',
       printWidth: 100,
       singleQuote: true,
-    })
+    }),
+    !verifyOnly
   );
 };
 

From d0074356e9ed9e37e35c2d5963f33c3994cadd23 Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Wed, 7 Sep 2022 11:01:50 -0700
Subject: [PATCH 10/27] fix: cannot use __dirname with .mts and latest Node

---
 src/docs.mts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/docs.mts b/src/docs.mts
index 088e004b02..2baa87f017 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -190,7 +190,7 @@ const transformHtml = (filename: string) => {
 
 /** Main method (entry point) */
 (async () => {
-  const sourceDirGlob = join(__dirname, SOURCE_DOCS_DIR, '**');
+  const sourceDirGlob = join('.', SOURCE_DOCS_DIR, '**');
   const includeFilesStartingWithDot = true;
 
   console.log('Transforming markdown files...');

From 73abcd869ca324798fe068ffefe0f67ec5b7658f Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Wed, 7 Sep 2022 11:02:22 -0700
Subject: [PATCH 11/27] fix: also check other files

---
 src/docs.mts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/docs.mts b/src/docs.mts
index 2baa87f017..877f7a022c 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -207,8 +207,9 @@ const transformHtml = (filename: string) => {
   const otherFiles = await globby([sourceDirGlob, '!**/*.md', '!**/*.html'], {
     dot: includeFilesStartingWithDot,
   });
-  otherFiles.forEach((file) => {
-    copyTransformedContents(file);
+  otherFiles.forEach((file: string) => {
+    const transformedContents = readSyncedUTF8file(file); // no transformation is done; just get the contents
+    copyTransformedContents(file, transformedContents, !verifyOnly);
   });
 
   if (filesWereTransformed) {

From 7fe8f260fc1edd5b5ba616d557442329d6cd76c4 Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Wed, 7 Sep 2022 11:03:22 -0700
Subject: [PATCH 12/27] minor cleanup, clarify var names, add @todos

---
 src/docs.mts | 46 ++++++++++++++++++++++++++--------------------
 1 file changed, 26 insertions(+), 20 deletions(-)

diff --git a/src/docs.mts b/src/docs.mts
index 877f7a022c..738e4c9c94 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -20,13 +20,18 @@
  *   docs --git
  *   If the --git option is used, the command `git add docs` will be run after all transformations (and/or verifications) have completed successfully
  *   If not files were transformed, the git command is not run.
+ *
+ * @todo Ensure that the documentation source and final paths are correct by using process.cwd() to
+ *   get their absolute paths. Ensures that the location of those 2 directories is not dependent on
+ *   where this file resides.
+ *
+ * @todo Write a test file for this. (Will need to be able to deal with globby. Jest has trouble with it.
  */
 
 import { remark } from 'remark';
 import type { Code, Root } from 'mdast';
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { JSDOM } from 'jsdom';
-
 // @ts-ignore
 import flatmap from 'unist-util-flatmap';
 import { globby } from 'globby';
@@ -35,36 +40,35 @@ import { exec } from 'child_process';
 // @ts-ignore
 import prettier from 'prettier';
 
-const SOURCE_DOCS_DIR = 'src/docs/';
-const FINAL_DOCS_DIR = 'docs/';
-const AUTOGENERATED_TEXT =
-  '# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in ${SOURCE_DOCS_DIR}.';
+const SOURCE_DOCS_DIR = 'src/docs';
+const FINAL_DOCS_DIR = 'docs';
+
+const AUTOGENERATED_TEXT = `# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in ${SOURCE_DOCS_DIR}.`;
 
 const LOGMSG_TRANSFORMED = 'transformed';
 const LOGMSG_TO_BE_TRANSFORMED = 'to be transformed';
-const LOGMSG_COPIED = ' ...and copied to ${FINAL_DOCS_DIR}';
+const LOGMSG_COPIED = ` ...and copied to ${FINAL_DOCS_DIR}`;
 
-const WARN_DOCSDIR_DOESNT_MATCH =
-  "Changed files were transformed in `${SOURCE_DOCS_DIR}` but do not match the files in `${FINAL_DOCS_DIR}`. Please run `yarn docs:build` after making changes to '${SOURCE_DOCS_DIR}' to update the `${FINAL_DOCS_DIR}` directory with the transformed files.";
+const WARN_DOCSDIR_DOESNT_MATCH = `Changed files were transformed in ${SOURCE_DOCS_DIR} but do not match the files in ${FINAL_DOCS_DIR}. Please run yarn docs:build after making changes to ${SOURCE_DOCS_DIR} to update the ${FINAL_DOCS_DIR} directory with the transformed files.`;
 
-const verifyOnly = process.argv.includes('--verify');
-const git = process.argv.includes('--git');
+const verifyOnly: boolean = process.argv.includes('--verify');
+const git: boolean = process.argv.includes('--git');
 
 let filesWereTransformed = false;
 
 /**
  * Given a source file name and path, return the documentation destination full path and file name
- * Create the destination path if it does not already exist. Possible Improvement: combine with
- * lint-staged to only copy files that have changed
+ * Create the destination path if it does not already exist.
  *
  * @param {string} file - Name of the file (including full path)
  * @returns {string} Name of the file with the path changed from the source directory to final
  *   documentation directory
+ * @todo Possible Improvement: combine with lint-staged to only copy files that have changed
  */
-const prepareOutFile = (file: string): string => {
-  const outFile = join(FINAL_DOCS_DIR, file.replace(SOURCE_DOCS_DIR, ''));
-  mkdirSync(dirname(outFile), { recursive: true });
-  return outFile;
+const changeToFinalDocDir = (file: string): string => {
+  const newDir = file.replace(SOURCE_DOCS_DIR, FINAL_DOCS_DIR);
+  mkdirSync(dirname(newDir), { recursive: true });
+  return newDir;
 };
 
 /**
@@ -100,8 +104,10 @@ const copyTransformedContents = (
   transformedContent?: string,
   doCopy: boolean = false
 ) => {
-  const outFile = prepareOutFile(file);
-  const existingBuffer = existsSync(outFile) ? readFileSync(outFile) : Buffer.from('#NEW FILE#');
+  const fileInFinalDocDir = changeToFinalDocDir(file);
+  const existingBuffer = existsSync(fileInFinalDocDir)
+    ? readFileSync(fileInFinalDocDir)
+    : Buffer.from('#NEW FILE#');
   const newBuffer = transformedContent ? Buffer.from(transformedContent) : readFileSync(file);
   if (existingBuffer.equals(newBuffer)) {
     return; // Files are same, skip.
@@ -109,7 +115,7 @@ const copyTransformedContents = (
 
   filesWereTransformed = true;
   if (doCopy) {
-    writeFileSync(outFile, newBuffer);
+    writeFileSync(fileInFinalDocDir, newBuffer);
   }
   logWasOrShouldBeTransformed(fileInFinalDocDir, doCopy);
 };
@@ -185,7 +191,7 @@ const transformHtml = (filename: string) => {
   };
 
   const transformedHTML = insertAutoGeneratedComment(filename);
-  copyTransformedContents(filename, transformedHTML);
+  copyTransformedContents(filename, transformedHTML, !verifyOnly);
 };
 
 /** Main method (entry point) */

From d18624bbe97f26696c8399a959c5210b049b6bfb Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Mon, 5 Sep 2022 16:54:31 -0700
Subject: [PATCH 13/27] change references from /docs to /src/docs; rework doc
 section in CONTRIBUTING

---
 CONTRIBUTING.md         | 34 +++++++++++++++++++++++++++-------
 docs/development.md     | 14 +++++++-------
 docs/mindmap.md         | 10 +++++-----
 src/docs/development.md | 14 +++++++-------
 src/docs/mindmap.md     | 10 +++++-----
 5 files changed, 51 insertions(+), 31 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index fb7f3bf5aa..1d65e93f2a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -20,8 +20,8 @@ yarn test
 We make all changes via pull requests. As we have many pull requests from developers new to mermaid, the current approach is to have _knsv, Knut Sveidqvist_ as a main reviewer of changes and merging pull requests. More precisely like this:
 
 - Large changes reviewed by knsv or other developer asked to review by knsv
-- Smaller low-risk changes like dependencies, documentation etc can be merged by active collaborators
-- documentation (updates to the docs folder is also allowed via direct commits)
+- Smaller low-risk changes like dependencies, documentation, etc. can be merged by active collaborators
+- Documentation (updates to the `src/docs` folder is also allowed via direct commits)
 
 To commit code, create a branch, let it start with the type like feature or bug followed by the issue number for reference and some describing text.
 
@@ -37,12 +37,28 @@ Another:
 
 Less strict here, it is OK to commit directly in the `develop` branch if you are a collaborator.
 
-The documentation is located in the `docs` directory and published using GitHub Pages.
-The documentation site is powered by [Docsify](https://docsify.js.org), a simple documentation site generator.
+The documentation is written in **Markdown**. For more information about Markdown [see the GitHub Markdown help page](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax).
 
-The documentation is written in Markdown, for more information about Markdown [see the GitHub Markdown help page](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax).
+### Documentation source files are in /src/docs
 
-If you want to preview the documentation site on your machine, you need to install `docsify-cli`:
+The source files for the project documentation are located in the `/src/docs` directory. This is where you should make changes.
+The files under `/src/docs` are processed to generate the published documentation, and the resulting files are put into the `/docs` directory.
+
+```mermaid
+flowchart LR
+  classDef default fill:#fff,color:black,stroke:black
+
+  source["files in /src/docs\n(changes should be done here)"] -- automatic processing\nto generate the final documentation--> published["files in /docs\ndisplayed on the official documentation site"]
+
+```
+
+**_DO NOT CHANGE FILES IN `/docs`_**
+
+### The official documentation site
+
+**[The mermaid documentation site](https://mermaid-js.github.io/mermaid/) is powered by [Docsify](https://docsify.js.org), a simple documentation site generator.**
+
+If you want to preview the whole documentation site on your machine, you need to install `docsify-cli`:
 
 ```sh
 $ npm i docsify-cli -g
@@ -121,7 +137,11 @@ it('should render forks and joins', () => {
 
 Finally, if it is not in the documentation, no one will know about it and then **no one will use it**. Wouldn't that be sad? With all the effort that was put into the feature?
 
-The docs are located in the docs folder and are ofc written in markdown. Just pick the right section and start typing. If you want to add to the structure as in adding a new section and new file you do that via the \_navbar.md.
+The source files for documentation are in `/src/docs` and are written in markdown. Just pick the right section and start typing. See the [Committing Documentation](#committing-documentation) section for more about how the documentation is generated.
+
+#### Adding to or changing the documentation organization
+
+If you want to add a new section or change the organization (structure), then you need to make sure to **change the side navigation** in `src/docs/_sidebar.md`.
 
 The changes in master is reflected in https://mermaid-js.github.io/mermaid/ once released the updates are committed to https://mermaid-js.github.io/#/
 
diff --git a/docs/development.md b/docs/development.md
index d5cbe891e0..365f639d7e 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -8,7 +8,7 @@ So you want to help? That's great!
 
 Here are a few things to get you started on the right path.
 
-**The Docs Structure is dictated by [sidebar.md](https://github.com/mermaid-js/mermaid/edit/develop/docs/_sidebar.md)**
+**The Docs Structure is dictated by [sidebar.md](https://github.com/mermaid-js/mermaid/edit/develop/src/docs/_sidebar.md)**
 
 **Note: Commits and Pull Requests should be directed to the develop branch.**
 
@@ -46,9 +46,9 @@ Start with the type, such as **feature** or **bug**, followed by the issue numbe
 
 If it is not in the documentation, it's like it never happened. Wouldn't that be sad? With all the effort that was put into the feature?
 
-The docs are located in the `src/docs` folder and are written in Markdown. Just pick the right section and start typing. If you want to propose changes to the structure of the documentation, such as adding a new section or a new file you do that via the **[sidebar](https://github.com/mermaid-js/mermaid/edit/develop/docs/_sidebar.md)**.
+The docs are located in the `src/docs` folder and are written in Markdown. Just pick the right section and start typing. If you want to propose changes to the structure of the documentation, such as adding a new section or a new file you do that via the **[sidebar](https://github.com/mermaid-js/mermaid/edit/develop/src/docs/_sidebar.md)**.
 
-> **All the documents displayed in the github.io page are listed in [sidebar.md](https://github.com/mermaid-js/mermaid/edit/develop/docs/_sidebar.md)**.
+> **All the documents displayed in the GitHub.io page are listed in [sidebar.md](https://github.com/mermaid-js/mermaid/edit/develop/src/docs/_sidebar.md)**.
 
 The contents of <https://mermaid-js.github.io/mermaid/> are based on the docs from the `master` branch. Updates committed to the `master` branch are reflected in the [Mermaid Docs](https://mermaid-js.github.io/mermaid/) once released.
 
@@ -60,7 +60,7 @@ The documentation is located in the `src/docs` directory and organized according
 
 The `docs` folder will be automatically generated when committing to `src/docs` and should not be edited manually.
 
-We encourage contributions to the documentation at [mermaid-js/mermaid/docs](https://github.com/mermaid-js/mermaid/tree/develop/docs). We publish documentation using GitHub Pages with [Docsify](https://www.youtube.com/watch?v=TV88lp7egMw&t=3s)
+We encourage contributions to the documentation at [mermaid-js/mermaid/src/docs](https://github.com/mermaid-js/mermaid/tree/develop/src/docs). We publish documentation using GitHub Pages with [Docsify](https://www.youtube.com/watch?v=TV88lp7egMw&t=3s)
 
 ### Add Unit Tests for Parsing
 
@@ -73,7 +73,7 @@ This tests the rendering and visual appearance of the diagrams. This ensures tha
 To start working with the e2e tests:
 
 1.  Run `yarn dev` to start the dev server
-2.  Start **Cypress** by running `cypress open` in the **mermaid** folder.\
+2.  Start **Cypress** by running `cypress open` in the **mermaid** folder.
     (Make sure you have path to Cypress in order, the binary is located in `node_modules/.bin`).
 
 The rendering tests are very straightforward to create. There is a function `imgSnapshotTest`, which takes a diagram in text form and the mermaid options, and it renders that diagram in Cypress.
@@ -114,7 +114,7 @@ Markdown is used to format the text, for more information about Markdown [see th
 
 To edit Docs on your computer:
 
-1.  Find the Markdown file (.md) to edit in the [mermaid-js/mermaid/docs](https://github.com/mermaid-js/mermaid/tree/develop/docs) directory in the `develop` branch.
+1.  Find the Markdown file (.md) to edit in the [mermaid-js/mermaid/src/docs](https://github.com/mermaid-js/mermaid/tree/develop/src/docs) directory in the `develop` branch.
 2.  Create a fork of the develop branch.
 3.  Make changes or add new documentation.
 4.  Commit changes to your fork and push it to GitHub.
@@ -123,7 +123,7 @@ To edit Docs on your computer:
 To edit Docs on GitHub:
 
 1.  Login to [GitHub.com](https://www.github.com).
-2.  Navigate to [mermaid-js/mermaid/docs](https://github.com/mermaid-js/mermaid/tree/develop/docs).
+2.  Navigate to [mermaid-js/mermaid/src/docs](https://github.com/mermaid-js/mermaid/tree/develop/src/docs).
 3.  To edit a file, click the pencil icon at the top-right of the file contents panel.
 4.  Describe what you changed in the **Propose file change** section, located at the bottom of the page.
 5.  Submit your changes by clicking the button **Propose file change** at the bottom (by automatic creation of a fork and a new branch).
diff --git a/docs/mindmap.md b/docs/mindmap.md
index f9d732463f..6ab954f5b6 100644
--- a/docs/mindmap.md
+++ b/docs/mindmap.md
@@ -2,7 +2,7 @@
 
 # Mindmap
 
-**Edit this Page** [![N|Solid](img/GitHub-Mark-32px.png)](https://github.com/mermaid-js/mermaid/blob/develop/docs/mindmap.md)
+**Edit this Page** [![N|Solid](img/GitHub-Mark-32px.png)](https://github.com/mermaid-js/mermaid/blob/develop/src/docs/mindmap.md)
 
 > Mindmap: This is an experimental diagram for now. The syntax and properties can change in future releases. The syntax is stabel except for the icon integration which is the experimental part.
 
@@ -64,7 +64,7 @@ In the following example you can see how there are 3 dufferent levels. One with
                 B
                 C
 
-In summary is is a simple text outline where there are one node at the root level called `Root` which has one child `A`. A in turn has two children `B`and `C`. In the diagram below we can see this rendered as a mindmap.
+In summary is a simple text outline where there are one node at the root level called `Root` which has one child `A`. `A` in turn has two children `B`and `C`. In the diagram below we can see this rendered as a mindmap.
 
 ```mermaid-example
 mindmap
@@ -168,7 +168,7 @@ More shapes will be added, beginning with the shapes available in flowcharts.
 
 ## icons
 
-As with flowcharts you can add icons to your nodes but with an updated syntax. The styling for the font based icons are added during the integration so that they are available for the web page. _This is not something a diagram author can do but has to be done with the site administrator or the integrator_. Once the icon fonts are in place you add them to the mind map nodes using the `::icon()` syntax. You place the classes for the icon within the parethesis like in the following example where icons for material design and fontwaresome 4. is displayed. The intention is that this approach should be used for all diagrams supporting icons. **Expermental feature:** This wider scope is also the reason Mindmaps are experimental as this syntax and approach could change.
+As with flowcharts you can add icons to your nodes but with an updated syntax. The styling for the font based icons are added during the integration so that they are available for the web page. _This is not something a diagram author can do but has to be done with the site administrator or the integrator_. Once the icon fonts are in place you add them to the mind map nodes using the `::icon()` syntax. You place the classes for the icon within the parenthesis like in the following example where icons for material design and fontawesome 4 are displayed. The intention is that this approach should be used for all diagrams supporting icons. **Experimental feature:** This wider scope is also the reason Mindmaps are experimental as this syntax and approach could change.
 
 ```mermaid-example
 mindmap
@@ -190,7 +190,7 @@ mindmap
 
 ## Classes
 
-Again the syntax for adding classes is similar to flowcharts and you can add classes using a tripple colon following a numver of css classes separated by space. In the following example one of the nodes has two custom classes attached urgent turning the background red and the text whiet and large increasing the font size:
+Again the syntax for adding classes is similar to flowcharts. You can add classes using a triple colon following a number of css classes separated by space. In the following example one of the nodes has two custom classes attached urgent turning the background red and the text white and large increasing the font size:
 
 ```mermaid-example
 mindmap
@@ -222,7 +222,7 @@ The actual indentation does not really matter only compared with the previous ro
                 B
               C
 
-This outline is unclear as `B` clearly is a child of `A` but when we move on to `C` the clarity is lost. `C` is not a child of `B` with a highter indentation nor does ot haver the same indentation as `B`. The only thing that is clear is that the first node with smaller indentation, indicating a parent, is A. Then Mermaid relies on this known truth and compensates for the unclear indentation and selects `A` as a parent of `C` leading till the same diagram with `B` and `C` as sieblings.
+This outline is unclear as `B` clearly is a child of `A` but when we move on to `C` the clarity is lost. `C` is not a child of `B` with a higher indentation nor does it have the same indentation as `B`. The only thing that is clear is that the first node with smaller indentation, indicating a parent, is A. Then Mermaid relies on this known truth and compensates for the unclear indentation and selects `A` as a parent of `C` leading till the same diagram with `B` and `C` as siblings.
 
 ```mermaid-example
 mindmap
diff --git a/src/docs/development.md b/src/docs/development.md
index 96da46c11f..95e5fe4174 100644
--- a/src/docs/development.md
+++ b/src/docs/development.md
@@ -6,7 +6,7 @@ So you want to help? That's great!
 
 Here are a few things to get you started on the right path.
 
-**The Docs Structure is dictated by [sidebar.md](https://github.com/mermaid-js/mermaid/edit/develop/docs/_sidebar.md)**
+**The Docs Structure is dictated by [sidebar.md](https://github.com/mermaid-js/mermaid/edit/develop/src/docs/_sidebar.md)**
 
 **Note: Commits and Pull Requests should be directed to the develop branch.**
 
@@ -44,9 +44,9 @@ Start with the type, such as **feature** or **bug**, followed by the issue numbe
 
 If it is not in the documentation, it's like it never happened. Wouldn't that be sad? With all the effort that was put into the feature?
 
-The docs are located in the `src/docs` folder and are written in Markdown. Just pick the right section and start typing. If you want to propose changes to the structure of the documentation, such as adding a new section or a new file you do that via the **[sidebar](https://github.com/mermaid-js/mermaid/edit/develop/docs/_sidebar.md)**.
+The docs are located in the `src/docs` folder and are written in Markdown. Just pick the right section and start typing. If you want to propose changes to the structure of the documentation, such as adding a new section or a new file you do that via the **[sidebar](https://github.com/mermaid-js/mermaid/edit/develop/src/docs/_sidebar.md)**.
 
-> **All the documents displayed in the github.io page are listed in [sidebar.md](https://github.com/mermaid-js/mermaid/edit/develop/docs/_sidebar.md)**.
+> **All the documents displayed in the GitHub.io page are listed in [sidebar.md](https://github.com/mermaid-js/mermaid/edit/develop/src/docs/_sidebar.md)**.
 
 The contents of [https://mermaid-js.github.io/mermaid/](https://mermaid-js.github.io/mermaid/) are based on the docs from the `master` branch. Updates committed to the `master` branch are reflected in the [Mermaid Docs](https://mermaid-js.github.io/mermaid/) once released.
 
@@ -58,7 +58,7 @@ The documentation is located in the `src/docs` directory and organized according
 
 The `docs` folder will be automatically generated when committing to `src/docs` and should not be edited manually.
 
-We encourage contributions to the documentation at [mermaid-js/mermaid/docs](https://github.com/mermaid-js/mermaid/tree/develop/docs). We publish documentation using GitHub Pages with [Docsify](https://www.youtube.com/watch?v=TV88lp7egMw&t=3s)
+We encourage contributions to the documentation at [mermaid-js/mermaid/src/docs](https://github.com/mermaid-js/mermaid/tree/develop/src/docs). We publish documentation using GitHub Pages with [Docsify](https://www.youtube.com/watch?v=TV88lp7egMw&t=3s)
 
 ### Add Unit Tests for Parsing
 
@@ -71,7 +71,7 @@ This tests the rendering and visual appearance of the diagrams. This ensures tha
 To start working with the e2e tests:
 
 1. Run `yarn dev` to start the dev server
-2. Start **Cypress** by running `cypress open` in the **mermaid** folder.  
+2. Start **Cypress** by running `cypress open` in the **mermaid** folder.
    (Make sure you have path to Cypress in order, the binary is located in `node_modules/.bin`).
 
 The rendering tests are very straightforward to create. There is a function `imgSnapshotTest`, which takes a diagram in text form and the mermaid options, and it renders that diagram in Cypress.
@@ -112,7 +112,7 @@ Markdown is used to format the text, for more information about Markdown [see th
 
 To edit Docs on your computer:
 
-1. Find the Markdown file (.md) to edit in the [mermaid-js/mermaid/docs](https://github.com/mermaid-js/mermaid/tree/develop/docs) directory in the `develop` branch.
+1. Find the Markdown file (.md) to edit in the [mermaid-js/mermaid/src/docs](https://github.com/mermaid-js/mermaid/tree/develop/src/docs) directory in the `develop` branch.
 2. Create a fork of the develop branch.
 3. Make changes or add new documentation.
 4. Commit changes to your fork and push it to GitHub.
@@ -121,7 +121,7 @@ To edit Docs on your computer:
 To edit Docs on GitHub:
 
 1. Login to [GitHub.com](https://www.github.com).
-2. Navigate to [mermaid-js/mermaid/docs](https://github.com/mermaid-js/mermaid/tree/develop/docs).
+2. Navigate to [mermaid-js/mermaid/src/docs](https://github.com/mermaid-js/mermaid/tree/develop/src/docs).
 3. To edit a file, click the pencil icon at the top-right of the file contents panel.
 4. Describe what you changed in the **Propose file change** section, located at the bottom of the page.
 5. Submit your changes by clicking the button **Propose file change** at the bottom (by automatic creation of a fork and a new branch).
diff --git a/src/docs/mindmap.md b/src/docs/mindmap.md
index 1418085149..d7f1b48171 100644
--- a/src/docs/mindmap.md
+++ b/src/docs/mindmap.md
@@ -1,6 +1,6 @@
 # Mindmap
 
-**Edit this Page** [![N|Solid](img/GitHub-Mark-32px.png)](https://github.com/mermaid-js/mermaid/blob/develop/docs/mindmap.md)
+**Edit this Page** [![N|Solid](img/GitHub-Mark-32px.png)](https://github.com/mermaid-js/mermaid/blob/develop/src/docs/mindmap.md)
 
 > Mindmap: This is an experimental diagram for now. The syntax and properties can change in future releases. The syntax is stabel except for the icon integration which is the experimental part.
 
@@ -43,7 +43,7 @@ mindmap
             C
 ```
 
-In summary is is a simple text outline where there are one node at the root level called `Root` which has one child `A`. A in turn has two children `B`and `C`. In the diagram below we can see this rendered as a mindmap.
+In summary is a simple text outline where there are one node at the root level called `Root` which has one child `A`. `A` in turn has two children `B`and `C`. In the diagram below we can see this rendered as a mindmap.
 
 ```mermaid
 mindmap
@@ -109,7 +109,7 @@ More shapes will be added, beginning with the shapes available in flowcharts.
 
 ## icons
 
-As with flowcharts you can add icons to your nodes but with an updated syntax. The styling for the font based icons are added during the integration so that they are available for the web page. _This is not something a diagram author can do but has to be done with the site administrator or the integrator_. Once the icon fonts are in place you add them to the mind map nodes using the `::icon()` syntax. You place the classes for the icon within the parethesis like in the following example where icons for material design and fontwaresome 4. is displayed. The intention is that this approach should be used for all diagrams supporting icons. **Expermental feature:** This wider scope is also the reason Mindmaps are experimental as this syntax and approach could change.
+As with flowcharts you can add icons to your nodes but with an updated syntax. The styling for the font based icons are added during the integration so that they are available for the web page. _This is not something a diagram author can do but has to be done with the site administrator or the integrator_. Once the icon fonts are in place you add them to the mind map nodes using the `::icon()` syntax. You place the classes for the icon within the parenthesis like in the following example where icons for material design and fontawesome 4 are displayed. The intention is that this approach should be used for all diagrams supporting icons. **Experimental feature:** This wider scope is also the reason Mindmaps are experimental as this syntax and approach could change.
 
 ```mermaid-example
 mindmap
@@ -122,7 +122,7 @@ mindmap
 
 ## Classes
 
-Again the syntax for adding classes is similar to flowcharts and you can add classes using a tripple colon following a numver of css classes separated by space. In the following example one of the nodes has two custom classes attached urgent turning the background red and the text whiet and large increasing the font size:
+Again the syntax for adding classes is similar to flowcharts. You can add classes using a triple colon following a number of css classes separated by space. In the following example one of the nodes has two custom classes attached urgent turning the background red and the text white and large increasing the font size:
 
 ```mermaid-example
 mindmap
@@ -147,7 +147,7 @@ mindmap
           C
 ```
 
-This outline is unclear as `B` clearly is a child of `A` but when we move on to `C` the clarity is lost. `C` is not a child of `B` with a highter indentation nor does ot haver the same indentation as `B`. The only thing that is clear is that the first node with smaller indentation, indicating a parent, is A. Then Mermaid relies on this known truth and compensates for the unclear indentation and selects `A` as a parent of `C` leading till the same diagram with `B` and `C` as sieblings.
+This outline is unclear as `B` clearly is a child of `A` but when we move on to `C` the clarity is lost. `C` is not a child of `B` with a higher indentation nor does it have the same indentation as `B`. The only thing that is clear is that the first node with smaller indentation, indicating a parent, is A. Then Mermaid relies on this known truth and compensates for the unclear indentation and selects `A` as a parent of `C` leading till the same diagram with `B` and `C` as siblings.
 
 ```mermaid
 mindmap

From be28160a4a9386246e487c6ba8c0c7170450b460 Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Mon, 5 Sep 2022 17:01:03 -0700
Subject: [PATCH 14/27] unmangle sentence about doc changes committed and
 showing up on docsify site

---
 CONTRIBUTING.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1d65e93f2a..1d55fe3b35 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -143,7 +143,8 @@ The source files for documentation are in `/src/docs` and are written in markdow
 
 If you want to add a new section or change the organization (structure), then you need to make sure to **change the side navigation** in `src/docs/_sidebar.md`.
 
-The changes in master is reflected in https://mermaid-js.github.io/mermaid/ once released the updates are committed to https://mermaid-js.github.io/#/
+
+When changes are committed and then released, they become part of the `master` branch and become part of the published documentation on https://mermaid-js.github.io/mermaid/
 
 ## Last words
 

From e690da638dc6467e93db5687aa0413d3eaeaea3d Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Wed, 7 Sep 2022 06:40:26 -0700
Subject: [PATCH 15/27] (formatting) prettier fix

---
 CONTRIBUTING.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1d55fe3b35..8171aeca99 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -143,7 +143,6 @@ The source files for documentation are in `/src/docs` and are written in markdow
 
 If you want to add a new section or change the organization (structure), then you need to make sure to **change the side navigation** in `src/docs/_sidebar.md`.
 
-
 When changes are committed and then released, they become part of the `master` branch and become part of the published documentation on https://mermaid-js.github.io/mermaid/
 
 ## Last words

From 5f81e3d5ed4123a562651bd66831365c6648e56a Mon Sep 17 00:00:00 2001
From: Sidharth Vinod <sidharthv96@gmail.com>
Date: Wed, 7 Sep 2022 20:51:46 +0530
Subject: [PATCH 16/27] chore: Run postbuild with prepare

As postbuild was not running with prepare, PR that updated `documentation` package was green,  although it should've failed.
---
 package.json | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/package.json b/package.json
index cacde6635f..163e509bd0 100644
--- a/package.json
+++ b/package.json
@@ -28,11 +28,11 @@
     "build": "concurrently \"yarn build:dev\" \"yarn build:prod\"",
     "docs:build": "ts-node-esm src/docs.mts",
     "docs:verify": "ts-node-esm src/docs.mts --verify",
-    "postbuild": "documentation build src/mermaidAPI.ts src/config.ts src/defaultConfig.ts --shallow -f md --markdown-toc false > src/docs/Setup.md; yarn docs:build",
+    "postbuild": "documentation build src/mermaidAPI.ts src/config.ts src/defaultConfig.ts --shallow -f md --markdown-toc false > src/docs/Setup.md && prettier --write src/docs/Setup.md && yarn docs:build",
     "build:watch": "yarn build:dev --watch",
     "release": "yarn build",
-    "lint": "eslint --cache --ignore-path .gitignore .; prettier --check .",
-    "lint:fix": "eslint --fix --ignore-path .gitignore .; prettier --write .",
+    "lint": "eslint --cache --ignore-path .gitignore . && prettier --check .",
+    "lint:fix": "eslint --fix --ignore-path .gitignore . && prettier --write .",
     "e2e:depr": "yarn lint && jest e2e --config e2e/jest.config.js",
     "cypress": "cypress run",
     "cypress:open": "cypress open",
@@ -43,7 +43,7 @@
     "test": "yarn lint && jest src/.*",
     "test:watch": "jest --watch src",
     "prepublishOnly": "yarn build && yarn test",
-    "prepare": "concurrently \"husky install\" \"yarn build:prod\"",
+    "prepare": "concurrently \"husky install\" \"yarn build:prod\" \"yarn postbuild\"",
     "pre-commit": "lint-staged"
   },
   "repository": {

From a800cb6fe62aa5fb7781cd8f40721acb4ea8d641 Mon Sep 17 00:00:00 2001
From: Sidharth Vinod <sidharthv96@gmail.com>
Date: Wed, 7 Sep 2022 20:54:19 +0530
Subject: [PATCH 17/27] Update prettier

---
 package.json |  4 ++--
 yarn.lock    | 10 +++++-----
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/package.json b/package.json
index 163e509bd0..a791f05747 100644
--- a/package.json
+++ b/package.json
@@ -115,8 +115,8 @@
     "lint-staged": "^13.0.0",
     "moment": "^2.23.0",
     "path-browserify": "^1.0.1",
-    "prettier": "^2.3.2",
-    "prettier-plugin-jsdoc": "^0.3.30",
+    "prettier": "^2.7.1",
+    "prettier-plugin-jsdoc": "^0.4.2",
     "remark": "^14.0.2",
     "start-server-and-test": "^1.12.6",
     "terser-webpack-plugin": "^5.3.6",
diff --git a/yarn.lock b/yarn.lock
index 2834342cac..58c3d2818f 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -9873,16 +9873,16 @@ prelude-ls@~1.1.2:
   resolved "https://registry.yarnpkg.com/prelude-ls/-/prelude-ls-1.1.2.tgz#21932a549f5e52ffd9a827f570e04be62a97da54"
   integrity sha1-IZMqVJ9eUv/ZqCf1cOBL5iqX2lQ=
 
-prettier-plugin-jsdoc@^0.3.30:
-  version "0.3.38"
-  resolved "https://registry.yarnpkg.com/prettier-plugin-jsdoc/-/prettier-plugin-jsdoc-0.3.38.tgz#b8adbe9efc1dc11f3cc5ff0b07e0233a0fdf533d"
-  integrity sha512-h81ZV/nFk5gr3fzWMWzWoz/M/8FneAZxscT7DVSy+5jMIuWYnBFZfSswVKYZyTaZ5r6+6k4hpFTDWhRp85C1tg==
+prettier-plugin-jsdoc@^0.4.2:
+  version "0.4.2"
+  resolved "https://registry.yarnpkg.com/prettier-plugin-jsdoc/-/prettier-plugin-jsdoc-0.4.2.tgz#c5668fc622ed10b87d988279476f96af96b058b7"
+  integrity sha512-w2jnAQm3z0GAG0bhzVJeehzDtrhGMSxJjit5ApCc2oxWfc7+jmLAkbtdOXaSpfwZz3IWkk+PiQPeRrLNpbM+Mw==
   dependencies:
     binary-searching "^2.0.5"
     comment-parser "^1.3.1"
     mdast-util-from-markdown "^1.2.0"
 
-prettier@^2.3.2:
+prettier@^2.7.1:
   version "2.7.1"
   resolved "https://registry.yarnpkg.com/prettier/-/prettier-2.7.1.tgz#e235806850d057f97bb08368a4f7d899f7760c64"
   integrity sha512-ujppO+MkdPqoVINuDFDRLClm7D78qbDt0/NR+wp5FqEZOoTNAjPHWj17QRhu7geIHJfcNhRk1XVQmF8Bp3ye+g==

From 6376c9ae43420aa5a6c95a66ceac776e9496fe88 Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Wed, 7 Sep 2022 14:15:09 -0700
Subject: [PATCH 18/27] switch order of params so the last one can be omitted

---
 src/docs.mts | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/src/docs.mts b/src/docs.mts
index 738e4c9c94..cf5f54ae91 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -100,9 +100,9 @@ const logWasOrShouldBeTransformed = (filename: string, wasCopied: boolean) => {
  *   documentation directory. Default is `false`
  */
 const copyTransformedContents = (
-  file: string,
-  transformedContent?: string,
-  doCopy: boolean = false
+  filename: string,
+  doCopy: boolean = false,
+  transformedContent?: string
 ) => {
   const fileInFinalDocDir = changeToFinalDocDir(file);
   const existingBuffer = existsSync(fileInFinalDocDir)
@@ -152,6 +152,7 @@ const transformMarkdown = (file: string) => {
 
   copyTransformedContents(
     file,
+    !verifyOnly,
     prettier.format(transformed, {
       parser: 'markdown',
       useTabs: false,
@@ -159,8 +160,7 @@ const transformMarkdown = (file: string) => {
       endOfLine: 'auto',
       printWidth: 100,
       singleQuote: true,
-    }),
-    !verifyOnly
+    })
   );
 };
 
@@ -191,7 +191,7 @@ const transformHtml = (filename: string) => {
   };
 
   const transformedHTML = insertAutoGeneratedComment(filename);
-  copyTransformedContents(filename, transformedHTML, !verifyOnly);
+  copyTransformedContents(filename, !verifyOnly, transformedHTML);
 };
 
 /** Main method (entry point) */
@@ -214,8 +214,7 @@ const transformHtml = (filename: string) => {
     dot: includeFilesStartingWithDot,
   });
   otherFiles.forEach((file: string) => {
-    const transformedContents = readSyncedUTF8file(file); // no transformation is done; just get the contents
-    copyTransformedContents(file, transformedContents, !verifyOnly);
+    copyTransformedContents(file, !verifyOnly); // no transformation
   });
 
   if (filesWereTransformed) {

From fd567f833e76fd4ce4f9155ec0f781ba6c42158d Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Wed, 7 Sep 2022 14:15:54 -0700
Subject: [PATCH 19/27] (minor) clarify var names (file -> filename); comments

---
 src/docs.mts | 50 +++++++++++++++++++++-----------------------------
 1 file changed, 21 insertions(+), 29 deletions(-)

diff --git a/src/docs.mts b/src/docs.mts
index cf5f54ae91..0c62ea2784 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -1,9 +1,8 @@
 /**
- * @file Transform documentation source files into files suitable for publishing and optionally copy
- *   the transformed files from the source directory to the directory used for the final, published
- *   documentation directory. The list of files transformed and copied to final documentation
- *   directory are logged to the console. If a file in the source directory has the same contents in
- *   the final directory, nothing is done (the final directory is up-to-date).
+ * @file Transform documentation source files into files suitable for publishing and optionally copy the transformed files from the source directory
+ *   to the directory used for the final, published documentation directory. The list of files transformed and copied to final documentation directory
+ *   are logged to the console. If a file in the source directory has the same contents in the final directory, nothing is done (the final directory
+ *   is up-to-date).
  * @example
  *   docs
  *   Run with no option flags
@@ -21,11 +20,10 @@
  *   If the --git option is used, the command `git add docs` will be run after all transformations (and/or verifications) have completed successfully
  *   If not files were transformed, the git command is not run.
  *
- * @todo Ensure that the documentation source and final paths are correct by using process.cwd() to
- *   get their absolute paths. Ensures that the location of those 2 directories is not dependent on
- *   where this file resides.
+ * @todo Ensure that the documentation source and final paths are correct by using process.cwd() to get their absolute paths. Ensures that the
+ *   location of those 2 directories is not dependent on where this file resides.
  *
- * @todo Write a test file for this. (Will need to be able to deal with globby. Jest has trouble with it.
+ * @todo Write a test file for this. (Will need to be able to deal .mts file. Jest has trouble with it.)
  */
 
 import { remark } from 'remark';
@@ -57,12 +55,10 @@ const git: boolean = process.argv.includes('--git');
 let filesWereTransformed = false;
 
 /**
- * Given a source file name and path, return the documentation destination full path and file name
- * Create the destination path if it does not already exist.
+ * Given a source file name and path, return the documentation destination full path and file name Create the destination path if it does not already exist.
  *
  * @param {string} file - Name of the file (including full path)
- * @returns {string} Name of the file with the path changed from the source directory to final
- *   documentation directory
+ * @returns {string} Name of the file with the path changed from the source directory to final documentation directory
  * @todo Possible Improvement: combine with lint-staged to only copy files that have changed
  */
 const changeToFinalDocDir = (file: string): string => {
@@ -72,8 +68,7 @@ const changeToFinalDocDir = (file: string): string => {
 };
 
 /**
- * Log messages to the console showing if the transformed file copied to the final documentation
- * directory or still needs to be copied.
+ * Log messages to the console showing if the transformed file copied to the final documentation directory or still needs to be copied.
  *
  * @param {string} filename Name of the file that was transformed
  * @param {boolean} wasCopied Whether or not the file was copied
@@ -90,25 +85,23 @@ const logWasOrShouldBeTransformed = (filename: string, wasCopied: boolean) => {
 };
 
 /**
- * If the file contents were transformed, set the _filesWereTransformed_ flag to true and copy the
- * transformed contents to the final documentation directory if the doCopy flag is true. Log
- * messages to the console.
+ * If the file contents were transformed, set the _filesWereTransformed_ flag to true and copy the transformed contents to the final documentation
+ * directory if the doCopy flag is true. Log messages to the console.
  *
- * @param {string} file Name of the file that will be verified
+ * @param {string} filename Name of the file that will be verified
  * @param {string} [transformedContent] New contents for the file
- * @param {boolean} [doCopy=false] Whether we should copy that transformedContents to the final
- *   documentation directory. Default is `false`
+ * @param {boolean} [doCopy=false] Whether we should copy that transformedContents to the final documentation directory. Default is `false`
  */
 const copyTransformedContents = (
   filename: string,
   doCopy: boolean = false,
   transformedContent?: string
 ) => {
-  const fileInFinalDocDir = changeToFinalDocDir(file);
+  const fileInFinalDocDir = changeToFinalDocDir(filename);
   const existingBuffer = existsSync(fileInFinalDocDir)
     ? readFileSync(fileInFinalDocDir)
     : Buffer.from('#NEW FILE#');
-  const newBuffer = transformedContent ? Buffer.from(transformedContent) : readFileSync(file);
+  const newBuffer = transformedContent ? Buffer.from(transformedContent) : readFileSync(filename);
   if (existingBuffer.equals(newBuffer)) {
     return; // Files are same, skip.
   }
@@ -120,15 +113,15 @@ const copyTransformedContents = (
   logWasOrShouldBeTransformed(fileInFinalDocDir, doCopy);
 };
 
-const readSyncedUTF8file = (file: string): string => {
-  return readFileSync(file, 'utf8');
+const readSyncedUTF8file = (filename: string): string => {
+  return readFileSync(filename, 'utf8');
 };
 
 /**
  * Transform a markdown file and write the transformed file to the directory for published documentation
  *
- * 1. Add a `mermaid-example` block before every `mermaid` or `mmd` block On the docsify site (one
- *    place where the documentation is published), this will show the code used for the mermaid diagram
+ * 1. Add a `mermaid-example` block before every `mermaid` or `mmd` block On the docsify site (one place where the documentation is published), this will
+ *    show the code used for the mermaid diagram
  * 2. Add the text that says the file is automatically generated
  * 3. Use prettier to format the file Verify that the file has been changed and write out the changes
  *
@@ -167,8 +160,7 @@ const transformMarkdown = (file: string) => {
 /**
  * Transform an HTML file and write the transformed file to the directory for published documentation
  *
- * - Add the text that says the file is automatically generated Verify that the file has been changed
- *   and write out the changes
+ * - Add the text that says the file is automatically generated Verify that the file has been changed and write out the changes
  *
  * @param filename {string} name of the HTML file to transform
  */

From 9acf63f7d6656877784a57f37aa9329a8f088b2d Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Thu, 8 Sep 2022 07:44:36 -0700
Subject: [PATCH 20/27] (formatting only) sort imports just to force a new CI
 lint check

---
 src/docs.mts | 61 +++++++++++++++++++++++++++++++---------------------
 1 file changed, 36 insertions(+), 25 deletions(-)

diff --git a/src/docs.mts b/src/docs.mts
index 0c62ea2784..fe1922bdbc 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -1,8 +1,9 @@
 /**
- * @file Transform documentation source files into files suitable for publishing and optionally copy the transformed files from the source directory
- *   to the directory used for the final, published documentation directory. The list of files transformed and copied to final documentation directory
- *   are logged to the console. If a file in the source directory has the same contents in the final directory, nothing is done (the final directory
- *   is up-to-date).
+ * @file Transform documentation source files into files suitable for publishing and optionally copy
+ *   the transformed files from the source directory to the directory used for the final, published
+ *   documentation directory. The list of files transformed and copied to final documentation
+ *   directory are logged to the console. If a file in the source directory has the same contents in
+ *   the final directory, nothing is done (the final directory is up-to-date).
  * @example
  *   docs
  *   Run with no option flags
@@ -20,23 +21,24 @@
  *   If the --git option is used, the command `git add docs` will be run after all transformations (and/or verifications) have completed successfully
  *   If not files were transformed, the git command is not run.
  *
- * @todo Ensure that the documentation source and final paths are correct by using process.cwd() to get their absolute paths. Ensures that the
- *   location of those 2 directories is not dependent on where this file resides.
+ * @todo Ensure that the documentation source and final paths are correct by using process.cwd() to
+ *   get their absolute paths. Ensures that the location of those 2 directories is not dependent on
+ *   where this file resides.
  *
- * @todo Write a test file for this. (Will need to be able to deal .mts file. Jest has trouble with it.)
+ * @todo Write a test file for this. (Will need to be able to deal .mts file. Jest has trouble with
+ *   it.)
  */
-
-import { remark } from 'remark';
-import type { Code, Root } from 'mdast';
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
-import { JSDOM } from 'jsdom';
-// @ts-ignore
-import flatmap from 'unist-util-flatmap';
+import { exec } from 'child_process';
 import { globby } from 'globby';
+import { JSDOM } from 'jsdom';
+import type { Code, Root } from 'mdast';
 import { join, dirname } from 'path';
-import { exec } from 'child_process';
 // @ts-ignore
 import prettier from 'prettier';
+import { remark } from 'remark';
+// @ts-ignore
+import flatmap from 'unist-util-flatmap';
 
 const SOURCE_DOCS_DIR = 'src/docs';
 const FINAL_DOCS_DIR = 'docs';
@@ -55,10 +57,12 @@ const git: boolean = process.argv.includes('--git');
 let filesWereTransformed = false;
 
 /**
- * Given a source file name and path, return the documentation destination full path and file name Create the destination path if it does not already exist.
+ * Given a source file name and path, return the documentation destination full path and file name
+ * Create the destination path if it does not already exist.
  *
  * @param {string} file - Name of the file (including full path)
- * @returns {string} Name of the file with the path changed from the source directory to final documentation directory
+ * @returns {string} Name of the file with the path changed from the source directory to final
+ *   documentation directory
  * @todo Possible Improvement: combine with lint-staged to only copy files that have changed
  */
 const changeToFinalDocDir = (file: string): string => {
@@ -68,7 +72,8 @@ const changeToFinalDocDir = (file: string): string => {
 };
 
 /**
- * Log messages to the console showing if the transformed file copied to the final documentation directory or still needs to be copied.
+ * Log messages to the console showing if the transformed file copied to the final documentation
+ * directory or still needs to be copied.
  *
  * @param {string} filename Name of the file that was transformed
  * @param {boolean} wasCopied Whether or not the file was copied
@@ -85,12 +90,14 @@ const logWasOrShouldBeTransformed = (filename: string, wasCopied: boolean) => {
 };
 
 /**
- * If the file contents were transformed, set the _filesWereTransformed_ flag to true and copy the transformed contents to the final documentation
- * directory if the doCopy flag is true. Log messages to the console.
+ * If the file contents were transformed, set the _filesWereTransformed_ flag to true and copy the
+ * transformed contents to the final documentation directory if the doCopy flag is true. Log
+ * messages to the console.
  *
  * @param {string} filename Name of the file that will be verified
  * @param {string} [transformedContent] New contents for the file
- * @param {boolean} [doCopy=false] Whether we should copy that transformedContents to the final documentation directory. Default is `false`
+ * @param {boolean} [doCopy=false] Whether we should copy that transformedContents to the final
+ *   documentation directory. Default is `false`
  */
 const copyTransformedContents = (
   filename: string,
@@ -118,10 +125,12 @@ const readSyncedUTF8file = (filename: string): string => {
 };
 
 /**
- * Transform a markdown file and write the transformed file to the directory for published documentation
+ * Transform a markdown file and write the transformed file to the directory for published
+ * documentation
  *
- * 1. Add a `mermaid-example` block before every `mermaid` or `mmd` block On the docsify site (one place where the documentation is published), this will
- *    show the code used for the mermaid diagram
+ * 1. Add a `mermaid-example` block before every `mermaid` or `mmd` block On the docsify site (one
+ *    place where the documentation is published), this will show the code used for the mermaid
+ *    diagram
  * 2. Add the text that says the file is automatically generated
  * 3. Use prettier to format the file Verify that the file has been changed and write out the changes
  *
@@ -158,9 +167,11 @@ const transformMarkdown = (file: string) => {
 };
 
 /**
- * Transform an HTML file and write the transformed file to the directory for published documentation
+ * Transform an HTML file and write the transformed file to the directory for published
+ * documentation
  *
- * - Add the text that says the file is automatically generated Verify that the file has been changed and write out the changes
+ * - Add the text that says the file is automatically generated Verify that the file has been changed
+ *   and write out the changes
  *
  * @param filename {string} name of the HTML file to transform
  */

From 2826bf6823e1270ff0d8d1b45395cce521f80e6c Mon Sep 17 00:00:00 2001
From: Sidharth Vinod <sidharthv96@gmail.com>
Date: Thu, 8 Sep 2022 21:51:42 +0530
Subject: [PATCH 21/27] fix: Formatting issue

---
 src/docs.mts | 33 +++++++++++++++++++--------------
 1 file changed, 19 insertions(+), 14 deletions(-)

diff --git a/src/docs.mts b/src/docs.mts
index fe1922bdbc..dfd6a761fd 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -54,6 +54,15 @@ const WARN_DOCSDIR_DOESNT_MATCH = `Changed files were transformed in ${SOURCE_DO
 const verifyOnly: boolean = process.argv.includes('--verify');
 const git: boolean = process.argv.includes('--git');
 
+// TODO: Read from .prettierrc?
+const prettierConfig: prettier.Config = {
+  useTabs: false,
+  tabWidth: 2,
+  endOfLine: 'auto',
+  printWidth: 100,
+  singleQuote: true,
+};
+
 let filesWereTransformed = false;
 
 /**
@@ -151,19 +160,11 @@ const transformMarkdown = (file: string) => {
 
   // Add the AUTOGENERATED_TEXT to the start of the file
   const transformed = `${AUTOGENERATED_TEXT}\n${remark.stringify(out)}`;
-
-  copyTransformedContents(
-    file,
-    !verifyOnly,
-    prettier.format(transformed, {
-      parser: 'markdown',
-      useTabs: false,
-      tabWidth: 2,
-      endOfLine: 'auto',
-      printWidth: 100,
-      singleQuote: true,
-    })
-  );
+  const formatted = prettier.format(transformed, {
+    parser: 'markdown',
+    ...prettierConfig,
+  });
+  copyTransformedContents(file, !verifyOnly, formatted);
 };
 
 /**
@@ -194,7 +195,11 @@ const transformHtml = (filename: string) => {
   };
 
   const transformedHTML = insertAutoGeneratedComment(filename);
-  copyTransformedContents(filename, !verifyOnly, transformedHTML);
+  const formattedHTML = prettier.format(transformedHTML, {
+    parser: 'html',
+    ...prettierConfig,
+  });
+  copyTransformedContents(filename, !verifyOnly, formattedHTML);
 };
 
 /** Main method (entry point) */

From b0559df9033f120bd2b5e150a99db635a7900902 Mon Sep 17 00:00:00 2001
From: Sidharth Vinod <sidharthv96@gmail.com>
Date: Thu, 8 Sep 2022 21:52:31 +0530
Subject: [PATCH 22/27] chore: Updated doc files

---
 docs/8.6.0_docs.md                                 | 2 +-
 docs/CHANGELOG.md                                  | 2 +-
 docs/Configuration.md                              | 2 +-
 docs/README.md                                     | 2 +-
 docs/SUMMARY.md                                    | 2 +-
 docs/Setup.md                                      | 2 +-
 docs/Tutorials.md                                  | 2 +-
 docs/_navbar.md                                    | 2 +-
 docs/_sidebar.md                                   | 2 +-
 docs/accessibility.md                              | 2 +-
 docs/breakingChanges.md                            | 2 +-
 docs/c4c.md                                        | 2 +-
 docs/classDiagram.md                               | 2 +-
 docs/developer-docs/configuration.md               | 2 +-
 docs/development.md                                | 2 +-
 docs/diagrams-and-syntax-and-examples/flowchart.md | 2 +-
 docs/directives.md                                 | 2 +-
 docs/entityRelationshipDiagram.md                  | 2 +-
 docs/examples.md                                   | 2 +-
 docs/faq.md                                        | 2 +-
 docs/flowchart.md                                  | 2 +-
 docs/gantt.md                                      | 2 +-
 docs/gitgraph.md                                   | 2 +-
 docs/index.html                                    | 2 +-
 docs/integrations.md                               | 2 +-
 docs/introduction.md                               | 2 +-
 docs/landing/index.html                            | 6 +++---
 docs/mermaidCLI.md                                 | 2 +-
 docs/mindmap.md                                    | 2 +-
 docs/n00b-advanced.md                              | 2 +-
 docs/n00b-gettingStarted.md                        | 2 +-
 docs/n00b-overview.md                              | 2 +-
 docs/n00b-syntaxReference.md                       | 2 +-
 docs/newDiagram.md                                 | 2 +-
 docs/pie.md                                        | 2 +-
 docs/requirementDiagram.md                         | 2 +-
 docs/security.md                                   | 2 +-
 docs/sequenceDiagram.md                            | 2 +-
 docs/stateDiagram.md                               | 2 +-
 docs/theming.md                                    | 2 +-
 docs/upgrading.md                                  | 2 +-
 docs/usage.md                                      | 2 +-
 docs/user-journey.md                               | 2 +-
 43 files changed, 45 insertions(+), 45 deletions(-)

diff --git a/docs/8.6.0_docs.md b/docs/8.6.0_docs.md
index b532a1c94e..9cced28ca6 100644
--- a/docs/8.6.0_docs.md
+++ b/docs/8.6.0_docs.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Version 8.6.0 Changes
 
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index d676920b79..20f7afe3a3 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Change Log
 
diff --git a/docs/Configuration.md b/docs/Configuration.md
index 0df2de104a..1cbaa228f5 100644
--- a/docs/Configuration.md
+++ b/docs/Configuration.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Configuration
 
diff --git a/docs/README.md b/docs/README.md
index 9e149dfdb2..e222764889 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # About Mermaid
 
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 0d32a70101..1b6153b89c 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Summary
 
diff --git a/docs/Setup.md b/docs/Setup.md
index 1f948ee018..e02cc1561c 100644
--- a/docs/Setup.md
+++ b/docs/Setup.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
diff --git a/docs/Tutorials.md b/docs/Tutorials.md
index 0211d35d01..0eac9ccfe6 100644
--- a/docs/Tutorials.md
+++ b/docs/Tutorials.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Tutorials
 
diff --git a/docs/_navbar.md b/docs/_navbar.md
index 6ec266461f..222926fc48 100644
--- a/docs/_navbar.md
+++ b/docs/_navbar.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 - Getting started
 
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
index 40e46d835e..a97bd8d726 100644
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 - 📔 Introduction
 
diff --git a/docs/accessibility.md b/docs/accessibility.md
index 820fe364ab..70ebef9d17 100644
--- a/docs/accessibility.md
+++ b/docs/accessibility.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Accessibility Options
 
diff --git a/docs/breakingChanges.md b/docs/breakingChanges.md
index f5bb4ddb3e..01088b9dc4 100644
--- a/docs/breakingChanges.md
+++ b/docs/breakingChanges.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Breaking changes
 
diff --git a/docs/c4c.md b/docs/c4c.md
index 1b4251785e..48688f1a08 100644
--- a/docs/c4c.md
+++ b/docs/c4c.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # C4 Diagrams
 
diff --git a/docs/classDiagram.md b/docs/classDiagram.md
index 1576aaa174..6c9ae96fe1 100644
--- a/docs/classDiagram.md
+++ b/docs/classDiagram.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Class diagrams
 
diff --git a/docs/developer-docs/configuration.md b/docs/developer-docs/configuration.md
index a10954416c..e764e200a7 100644
--- a/docs/developer-docs/configuration.md
+++ b/docs/developer-docs/configuration.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Configuration
 
diff --git a/docs/development.md b/docs/development.md
index 365f639d7e..70762be865 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Development and Contribution 🙌
 
diff --git a/docs/diagrams-and-syntax-and-examples/flowchart.md b/docs/diagrams-and-syntax-and-examples/flowchart.md
index 3aef42ef77..0f798d27fe 100644
--- a/docs/diagrams-and-syntax-and-examples/flowchart.md
+++ b/docs/diagrams-and-syntax-and-examples/flowchart.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 ---
 
diff --git a/docs/directives.md b/docs/directives.md
index 943dac53f6..8ef732008d 100644
--- a/docs/directives.md
+++ b/docs/directives.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Directives
 
diff --git a/docs/entityRelationshipDiagram.md b/docs/entityRelationshipDiagram.md
index 34e6a3ac6b..1f24796b68 100644
--- a/docs/entityRelationshipDiagram.md
+++ b/docs/entityRelationshipDiagram.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Entity Relationship Diagrams
 
diff --git a/docs/examples.md b/docs/examples.md
index 174a2c986f..d717083c6a 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Examples
 
diff --git a/docs/faq.md b/docs/faq.md
index a1b6e48374..ac5eeeb80b 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Frequently Asked Questions
 
diff --git a/docs/flowchart.md b/docs/flowchart.md
index 4d469f55e8..3ff17ad028 100644
--- a/docs/flowchart.md
+++ b/docs/flowchart.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Flowcharts - Basic Syntax
 
diff --git a/docs/gantt.md b/docs/gantt.md
index b0a302d9f1..9d598d9776 100644
--- a/docs/gantt.md
+++ b/docs/gantt.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Gantt diagrams
 
diff --git a/docs/gitgraph.md b/docs/gitgraph.md
index c423c25154..5f86cf53c8 100644
--- a/docs/gitgraph.md
+++ b/docs/gitgraph.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Gitgraph Diagrams
 
diff --git a/docs/index.html b/docs/index.html
index 39d454533e..8d291f8e57 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -1,6 +1,6 @@
 <!DOCTYPE html>
 <html lang="en">
-  <head>
+  <!--# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.--><head>
     <meta charset="UTF-8" />
     <title>
       mermaid - Markdownish syntax for generating flowcharts, sequence diagrams, class diagrams,
diff --git a/docs/integrations.md b/docs/integrations.md
index 16e7357798..57d3bd316c 100644
--- a/docs/integrations.md
+++ b/docs/integrations.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Integrations
 
diff --git a/docs/introduction.md b/docs/introduction.md
index 38c7c7a0e0..992fbafc1f 100644
--- a/docs/introduction.md
+++ b/docs/introduction.md
@@ -1 +1 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
diff --git a/docs/landing/index.html b/docs/landing/index.html
index 9b1e3749f9..2431ad9bd2 100644
--- a/docs/landing/index.html
+++ b/docs/landing/index.html
@@ -1,6 +1,6 @@
 <!DOCTYPE html>
 <html lang="en">
-  <head>
+  <!--# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.--><head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta http-equiv="X-UA-Compatible" content="ie=edge" />
@@ -64,7 +64,7 @@ <h1 class="my-4 text-5xl font-bold leading-tight p-shadow">
                 using Mermaid.js.
               </p>
               <a
-                href="https://www.amazon.com/Official-Guide-Mermaid-js-beautiful-flowcharts-dp-1801078025/dp/1801078025/ref=mt_other?_encoding=UTF8&me=&qid=1628153965"
+                href="https://www.amazon.com/Official-Guide-Mermaid-js-beautiful-flowcharts-dp-1801078025/dp/1801078025/ref=mt_other?_encoding=UTF8&amp;me=&amp;qid=1628153965"
               >
                 <button
                   style="background: #ffa41c; border: 1px solid #ff8f00"
@@ -322,7 +322,7 @@ <h3 class="my-4 text-3xl leading-tight">
         </p>
       </h3>
       <a
-        href="https://www.amazon.com/Official-Guide-Mermaid-js-beautiful-flowcharts-dp-1801078025/dp/1801078025/ref=mt_other?_encoding=UTF8&me=&qid=1628153965"
+        href="https://www.amazon.com/Official-Guide-Mermaid-js-beautiful-flowcharts-dp-1801078025/dp/1801078025/ref=mt_other?_encoding=UTF8&amp;me=&amp;qid=1628153965"
       >
         <button
           style="background: #ffa41c; border: 1px solid #ff8f00"
diff --git a/docs/mermaidCLI.md b/docs/mermaidCLI.md
index e3249315b7..0d32c54728 100644
--- a/docs/mermaidCLI.md
+++ b/docs/mermaidCLI.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # mermaid CLI
 
diff --git a/docs/mindmap.md b/docs/mindmap.md
index 6ab954f5b6..85dba5eb36 100644
--- a/docs/mindmap.md
+++ b/docs/mindmap.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Mindmap
 
diff --git a/docs/n00b-advanced.md b/docs/n00b-advanced.md
index 4e9d74b98c..b8970142a6 100644
--- a/docs/n00b-advanced.md
+++ b/docs/n00b-advanced.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Advanced n00b mermaid (Coming soon..)
 
diff --git a/docs/n00b-gettingStarted.md b/docs/n00b-gettingStarted.md
index f3ade55592..5055425394 100644
--- a/docs/n00b-gettingStarted.md
+++ b/docs/n00b-gettingStarted.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # A Mermaid User-Guide for Beginners
 
diff --git a/docs/n00b-overview.md b/docs/n00b-overview.md
index 913fcc2f63..c109b63f20 100644
--- a/docs/n00b-overview.md
+++ b/docs/n00b-overview.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Overview for Beginners
 
diff --git a/docs/n00b-syntaxReference.md b/docs/n00b-syntaxReference.md
index 9f18e3d282..d25c6425e6 100644
--- a/docs/n00b-syntaxReference.md
+++ b/docs/n00b-syntaxReference.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Diagram Syntax
 
diff --git a/docs/newDiagram.md b/docs/newDiagram.md
index e2191f1de4..285cb7637a 100644
--- a/docs/newDiagram.md
+++ b/docs/newDiagram.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Adding a New Diagram/Chart 📊
 
diff --git a/docs/pie.md b/docs/pie.md
index 1e13e38729..79dcbfee53 100644
--- a/docs/pie.md
+++ b/docs/pie.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Pie chart diagrams
 
diff --git a/docs/requirementDiagram.md b/docs/requirementDiagram.md
index c510183d95..d319678716 100644
--- a/docs/requirementDiagram.md
+++ b/docs/requirementDiagram.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Requirement Diagram
 
diff --git a/docs/security.md b/docs/security.md
index e2990eb5b5..ee9033ca21 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Security
 
diff --git a/docs/sequenceDiagram.md b/docs/sequenceDiagram.md
index ae0bd5e458..97968a6766 100644
--- a/docs/sequenceDiagram.md
+++ b/docs/sequenceDiagram.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Sequence diagrams
 
diff --git a/docs/stateDiagram.md b/docs/stateDiagram.md
index 6af3b0bc49..8ea9fd2398 100644
--- a/docs/stateDiagram.md
+++ b/docs/stateDiagram.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # State diagrams
 
diff --git a/docs/theming.md b/docs/theming.md
index 287499effe..9ba136ec44 100644
--- a/docs/theming.md
+++ b/docs/theming.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Theme Configuration
 
diff --git a/docs/upgrading.md b/docs/upgrading.md
index fd7f72d823..c4d7bd3bda 100644
--- a/docs/upgrading.md
+++ b/docs/upgrading.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Upgrading
 
diff --git a/docs/usage.md b/docs/usage.md
index 02bd1bb133..e59670d028 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # Usage
 
diff --git a/docs/user-journey.md b/docs/user-journey.md
index 9e213f425f..e0d924f85f 100644
--- a/docs/user-journey.md
+++ b/docs/user-journey.md
@@ -1,4 +1,4 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.
 
 # User Journey Diagram
 

From f8eaccb4c1bdf7fb0545c82adb5368db1ba9a3d3 Mon Sep 17 00:00:00 2001
From: Sidharth Vinod <sidharthv96@gmail.com>
Date: Thu, 8 Sep 2022 21:54:51 +0530
Subject: [PATCH 23/27] fix: Run precommit hook for doc.mts changes too

---
 .lintstagedrc.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.lintstagedrc.json b/.lintstagedrc.json
index db16ea99ae..b88abda4b2 100644
--- a/.lintstagedrc.json
+++ b/.lintstagedrc.json
@@ -1,4 +1,5 @@
 {
   "src/docs/**": ["yarn docs:build --git"],
-  "*.{ts,js,json,html,md}": ["eslint --fix", "prettier --write"]
+  "src/docs.mts": ["yarn docs:build --git"],
+  "*.{ts,js,json,html,md,mts}": ["eslint --fix", "prettier --write"]
 }

From 8ca91d6303cc2a9a16bebf94411a9fd563fd766a Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)"
 <registrations@ashleycaroline.com>
Date: Fri, 9 Sep 2022 18:32:26 -0700
Subject: [PATCH 24/27] add eslint-disable no-console for file

---
 src/docs.mts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/docs.mts b/src/docs.mts
index dfd6a761fd..dc7ec29e32 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -1,3 +1,5 @@
+/* eslint-disable no-console */
+
 /**
  * @file Transform documentation source files into files suitable for publishing and optionally copy
  *   the transformed files from the source directory to the directory used for the final, published

From 6ad9208119969a7952ecbf4ae5f7c0780383edb0 Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)" <ashley.engelund@gmail.com>
Date: Sun, 11 Sep 2022 11:37:23 -0700
Subject: [PATCH 25/27] eslint fixes

---
 src/docs.mts | 14 ++++----------
 1 file changed, 4 insertions(+), 10 deletions(-)

diff --git a/src/docs.mts b/src/docs.mts
index dc7ec29e32..6fcea6e607 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -36,10 +36,9 @@ import { globby } from 'globby';
 import { JSDOM } from 'jsdom';
 import type { Code, Root } from 'mdast';
 import { join, dirname } from 'path';
-// @ts-ignore
 import prettier from 'prettier';
 import { remark } from 'remark';
-// @ts-ignore
+// @ts-ignore No typescript declaration file
 import flatmap from 'unist-util-flatmap';
 
 const SOURCE_DOCS_DIR = 'src/docs';
@@ -90,9 +89,8 @@ const changeToFinalDocDir = (file: string): string => {
  * @param {boolean} wasCopied Whether or not the file was copied
  */
 const logWasOrShouldBeTransformed = (filename: string, wasCopied: boolean) => {
-  let changeMsg: string;
+  const changeMsg = wasCopied ? LOGMSG_TRANSFORMED : LOGMSG_TO_BE_TRANSFORMED;
   let logMsg: string;
-  changeMsg = wasCopied ? LOGMSG_TRANSFORMED : LOGMSG_TO_BE_TRANSFORMED;
   logMsg = `  File ${changeMsg}: ${filename}`;
   if (wasCopied) {
     logMsg += LOGMSG_COPIED;
@@ -106,15 +104,11 @@ const logWasOrShouldBeTransformed = (filename: string, wasCopied: boolean) => {
  * messages to the console.
  *
  * @param {string} filename Name of the file that will be verified
- * @param {string} [transformedContent] New contents for the file
  * @param {boolean} [doCopy=false] Whether we should copy that transformedContents to the final
  *   documentation directory. Default is `false`
+ * @param {string} [transformedContent] New contents for the file
  */
-const copyTransformedContents = (
-  filename: string,
-  doCopy: boolean = false,
-  transformedContent?: string
-) => {
+const copyTransformedContents = (filename: string, doCopy = false, transformedContent?: string) => {
   const fileInFinalDocDir = changeToFinalDocDir(filename);
   const existingBuffer = existsSync(fileInFinalDocDir)
     ? readFileSync(fileInFinalDocDir)

From 9cc7da09fcf259abd634bcd9d2ce9c8e5ed9716a Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)" <ashley.engelund@gmail.com>
Date: Sun, 11 Sep 2022 14:10:34 -0700
Subject: [PATCH 26/27] formatting

---
 src/docs.mts | 72 ++++++++++++++++++++++++++++------------------------
 1 file changed, 39 insertions(+), 33 deletions(-)

diff --git a/src/docs.mts b/src/docs.mts
index 6fcea6e607..318f03de0d 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -1,10 +1,11 @@
 /* eslint-disable no-console */
 
 /**
- * @file Transform documentation source files into files suitable for publishing and optionally copy
- *   the transformed files from the source directory to the directory used for the final, published
- *   documentation directory. The list of files transformed and copied to final documentation
- *   directory are logged to the console. If a file in the source directory has the same contents in
+ * @file Transform documentation source files into files suitable for publishing
+ *   and optionally copy the transformed files from the source directory to the
+ *   directory used for the final, published documentation directory. The list
+ *   of files transformed and copied to final documentation directory are logged
+ *   to the console. If a file in the source directory has the same contents in
  *   the final directory, nothing is done (the final directory is up-to-date).
  * @example
  *   docs
@@ -23,12 +24,12 @@
  *   If the --git option is used, the command `git add docs` will be run after all transformations (and/or verifications) have completed successfully
  *   If not files were transformed, the git command is not run.
  *
- * @todo Ensure that the documentation source and final paths are correct by using process.cwd() to
- *   get their absolute paths. Ensures that the location of those 2 directories is not dependent on
- *   where this file resides.
+ * @todo Ensure that the documentation source and final paths are correct by
+ *   using process.cwd() to get their absolute paths. Ensures that the location
+ *   of those 2 directories is not dependent on where this file resides.
  *
- * @todo Write a test file for this. (Will need to be able to deal .mts file. Jest has trouble with
- *   it.)
+ * @todo Write a test file for this. (Will need to be able to deal .mts file.
+ *   Jest has trouble with it.)
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { exec } from 'child_process';
@@ -67,13 +68,14 @@ const prettierConfig: prettier.Config = {
 let filesWereTransformed = false;
 
 /**
- * Given a source file name and path, return the documentation destination full path and file name
- * Create the destination path if it does not already exist.
+ * Given a source file name and path, return the documentation destination full
+ * path and file name Create the destination path if it does not already exist.
  *
  * @param {string} file - Name of the file (including full path)
- * @returns {string} Name of the file with the path changed from the source directory to final
- *   documentation directory
- * @todo Possible Improvement: combine with lint-staged to only copy files that have changed
+ * @returns {string} Name of the file with the path changed from the source
+ *   directory to final documentation directory
+ * @todo Possible Improvement: combine with lint-staged to only copy files that
+ *   have changed
  */
 const changeToFinalDocDir = (file: string): string => {
   const newDir = file.replace(SOURCE_DOCS_DIR, FINAL_DOCS_DIR);
@@ -82,8 +84,8 @@ const changeToFinalDocDir = (file: string): string => {
 };
 
 /**
- * Log messages to the console showing if the transformed file copied to the final documentation
- * directory or still needs to be copied.
+ * Log messages to the console showing if the transformed file copied to the
+ * final documentation directory or still needs to be copied.
  *
  * @param {string} filename Name of the file that was transformed
  * @param {boolean} wasCopied Whether or not the file was copied
@@ -99,13 +101,14 @@ const logWasOrShouldBeTransformed = (filename: string, wasCopied: boolean) => {
 };
 
 /**
- * If the file contents were transformed, set the _filesWereTransformed_ flag to true and copy the
- * transformed contents to the final documentation directory if the doCopy flag is true. Log
- * messages to the console.
+ * If the file contents were transformed, set the _filesWereTransformed_ flag to
+ * true and copy the transformed contents to the final documentation directory
+ * if the doCopy flag is true. Log messages to the console.
  *
  * @param {string} filename Name of the file that will be verified
- * @param {boolean} [doCopy=false] Whether we should copy that transformedContents to the final
- *   documentation directory. Default is `false`
+ * @param {boolean} [doCopy=false] Whether we should copy that
+ *   transformedContents to the final documentation directory. Default is
+ *   `false`. Default is `false`
  * @param {string} [transformedContent] New contents for the file
  */
 const copyTransformedContents = (filename: string, doCopy = false, transformedContent?: string) => {
@@ -130,14 +133,15 @@ const readSyncedUTF8file = (filename: string): string => {
 };
 
 /**
- * Transform a markdown file and write the transformed file to the directory for published
- * documentation
+ * Transform a markdown file and write the transformed file to the directory for
+ * published documentation
  *
- * 1. Add a `mermaid-example` block before every `mermaid` or `mmd` block On the docsify site (one
- *    place where the documentation is published), this will show the code used for the mermaid
- *    diagram
+ * 1. Add a `mermaid-example` block before every `mermaid` or `mmd` block On the
+ *    docsify site (one place where the documentation is published), this will
+ *    show the code used for the mermaid diagram
  * 2. Add the text that says the file is automatically generated
- * 3. Use prettier to format the file Verify that the file has been changed and write out the changes
+ * 3. Use prettier to format the file Verify that the file has been changed and
+ *    write out the changes
  *
  * @param file {string} name of the file that will be verified
  */
@@ -164,17 +168,17 @@ const transformMarkdown = (file: string) => {
 };
 
 /**
- * Transform an HTML file and write the transformed file to the directory for published
- * documentation
+ * Transform an HTML file and write the transformed file to the directory for
+ * published documentation
  *
- * - Add the text that says the file is automatically generated Verify that the file has been changed
- *   and write out the changes
+ * - Add the text that says the file is automatically generated Verify that the
+ *   file has been changed and write out the changes
  *
  * @param filename {string} name of the HTML file to transform
  */
 const transformHtml = (filename: string) => {
   /**
-   * Insert the '...auto generated...' comment into an HTML file after the <html> element
+   * Insert the '...auto generated...' comment into an HTML file after the<html> element
    *
    * @param fileName {string} file name that should have the comment inserted
    * @returns {string} The contents of the file with the comment inserted
@@ -204,7 +208,9 @@ const transformHtml = (filename: string) => {
   const includeFilesStartingWithDot = true;
 
   console.log('Transforming markdown files...');
-  const mdFiles = await globby([join(sourceDirGlob, '*.md')], { dot: includeFilesStartingWithDot });
+  const mdFiles = await globby([join(sourceDirGlob, '*.md')], {
+    dot: includeFilesStartingWithDot,
+  });
   mdFiles.forEach(transformMarkdown);
 
   console.log('Transforming html files...');

From 7f56112f8ed232472447521d1004746b665b2f96 Mon Sep 17 00:00:00 2001
From: Ashley Engelund <weedySeaDragon@users.noreply.github.com>
Date: Mon, 12 Sep 2022 09:17:40 -0700
Subject: [PATCH 27/27] change wording of console log message (use comma)

Co-authored-by: Sidharth Vinod <sidharthv96@gmail.com>
---
 src/docs.mts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/docs.mts b/src/docs.mts
index 318f03de0d..06a1f4bff8 100644
--- a/src/docs.mts
+++ b/src/docs.mts
@@ -49,7 +49,7 @@ const AUTOGENERATED_TEXT = `# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please
 
 const LOGMSG_TRANSFORMED = 'transformed';
 const LOGMSG_TO_BE_TRANSFORMED = 'to be transformed';
-const LOGMSG_COPIED = ` ...and copied to ${FINAL_DOCS_DIR}`;
+const LOGMSG_COPIED = `, and copied to ${FINAL_DOCS_DIR}`;
 
 const WARN_DOCSDIR_DOESNT_MATCH = `Changed files were transformed in ${SOURCE_DOCS_DIR} but do not match the files in ${FINAL_DOCS_DIR}. Please run yarn docs:build after making changes to ${SOURCE_DOCS_DIR} to update the ${FINAL_DOCS_DIR} directory with the transformed files.`;