Merge pull request #3420 from weedySeaDragon/docs/3418_auto_generated_comment_html_files

Docs: add '..auto generated..' to .html documentation files

.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"]
 }

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
 

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
 

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
 

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
 

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
 

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. -->
 

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
 

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
 

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
 

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
 

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
 

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
 

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
 

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
 

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 🙌
 

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.
 
 ---
 

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
 

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
 

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
 

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
 

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
 

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
 

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
 

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,

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
 

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.

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 @@
                 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 @@
         </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"

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
 

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
 

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..)
 

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
 

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
 

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
 

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 📊
 

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
 

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
 

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
 

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
 

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
 

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
 

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
 

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
 

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
 

src/docs.mts

@@ -1,42 +1,152 @@
 /* eslint-disable no-console */
 
-import { remark } from 'remark';
-import type { Code, Root } from 'mdast';
+/**
+ * @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 --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.
+ *
+ * @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.)
+ */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
-// @ts-ignore: no typings
-import flatmap from 'unist-util-flatmap';
-import { globby } from 'globby';
-import { join, dirname } from 'path';
 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 prettier from 'prettier';
+import { remark } from 'remark';
+// @ts-ignore No typescript declaration file
+import flatmap from 'unist-util-flatmap';
 
-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/', ''));
-  mkdirSync(dirname(outFile), { recursive: true });
-  return outFile;
+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 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: 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,
 };
 
-const verifyAndCopy = (file: string, content?: string) => {
-  const outFile = prepareOutFile(file);
-  const existingBuffer = existsSync(outFile) ? readFileSync(outFile) : Buffer.from('#NEW FILE#');
-  const newBuffer = content ? Buffer.from(content) : readFileSync(file);
+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.
+ *
+ * @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 changeToFinalDocDir = (file: string): string => {
+  const newDir = file.replace(SOURCE_DOCS_DIR, FINAL_DOCS_DIR);
+  mkdirSync(dirname(newDir), { recursive: true });
+  return newDir;
+};
+
+/**
+ * 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
+ */
+const logWasOrShouldBeTransformed = (filename: string, wasCopied: boolean) => {
+  const changeMsg = wasCopied ? LOGMSG_TRANSFORMED : LOGMSG_TO_BE_TRANSFORMED;
+  let logMsg: string;
+  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} 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`. Default is `false`
+ * @param {string} [transformedContent] New contents for the file
+ */
+const copyTransformedContents = (filename: string, doCopy = false, transformedContent?: string) => {
+  const fileInFinalDocDir = changeToFinalDocDir(filename);
+  const existingBuffer = existsSync(fileInFinalDocDir)
+    ? readFileSync(fileInFinalDocDir)
+    : Buffer.from('#NEW FILE#');
+  const newBuffer = transformedContent ? Buffer.from(transformedContent) : readFileSync(filename);
   if (existingBuffer.equals(newBuffer)) {
-    // Files are same, skip.
-    return;
+    return; // Files are same, skip.
   }
-  console.log(`File changed: ${outFile}`);
-  fileChanged = true;
-  if (!verify) {
-    writeFileSync(outFile, newBuffer);
+
+  filesWereTransformed = true;
+  if (doCopy) {
+    writeFileSync(fileInFinalDocDir, newBuffer);
   }
+  logWasOrShouldBeTransformed(fileInFinalDocDir, doCopy);
 };
 
-const transform = (file: string) => {
-  const doc = 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
+ * 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 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')) {
@@ -48,38 +158,82 @@ 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
-  )}`;
-  verifyAndCopy(
-    file,
-    prettier.format(transformed, {
-      parser: 'markdown',
-      useTabs: false,
-      tabWidth: 2,
-      endOfLine: 'auto',
-      printWidth: 100,
-      singleQuote: true,
-    })
-  );
+  // Add the AUTOGENERATED_TEXT to the start of the file
+  const transformed = `${AUTOGENERATED_TEXT}\n${remark.stringify(out)}`;
+  const formatted = prettier.format(transformed, {
+    parser: 'markdown',
+    ...prettierConfig,
+  });
+  copyTransformedContents(file, !verifyOnly, formatted);
 };
 
-(async () => {
-  const mdFiles = await globby(['./src/docs/**/*.md'], { dot: true });
-  mdFiles.forEach(transform);
-  const nonMDFiles = await globby(['src/docs/**', '!**/*.md'], { dot: true });
-  nonMDFiles.forEach((file) => {
-    verifyAndCopy(file);
+/**
+ * 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
+ */
+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
+   */
+  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);
+
+    const rootElement = htmlDoc.documentElement;
+    rootElement.prepend(autoGeneratedComment);
+    return jsdom.serialize();
+  };
+
+  const transformedHTML = insertAutoGeneratedComment(filename);
+  const formattedHTML = prettier.format(transformedHTML, {
+    parser: 'html',
+    ...prettierConfig,
   });
-  if (fileChanged) {
-    if (verify) {
-      console.log(
-        "Changes detected in files in `docs`. Please run `yarn docs:build` after making changes to 'src/docs' to update the `docs` folder."
-      );
+  copyTransformedContents(filename, !verifyOnly, formattedHTML);
+};
+
+/** Main method (entry point) */
+(async () => {
+  const sourceDirGlob = join('.', SOURCE_DOCS_DIR, '**');
+  const includeFilesStartingWithDot = true;
+
+  console.log('Transforming markdown files...');
+  const mdFiles = await globby([join(sourceDirGlob, '*.md')], {
+    dot: includeFilesStartingWithDot,
+  });
+  mdFiles.forEach(transformMarkdown);
+
+  console.log('Transforming html files...');
+  const htmlFiles = await globby([join(sourceDirGlob, '*.html')], {
+    dot: includeFilesStartingWithDot,
+  });
+  htmlFiles.forEach(transformHtml);
+
+  console.log('Transforming all other files...');
+  const otherFiles = await globby([sourceDirGlob, '!**/*.md', '!**/*.html'], {
+    dot: includeFilesStartingWithDot,
+  });
+  otherFiles.forEach((file: string) => {
+    copyTransformedContents(file, !verifyOnly); // no transformation
+  });
+
+  if (filesWereTransformed) {
+    if (verifyOnly) {
+      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');
     }
   }