mirrors
/
mermaid
mirror of https://github.com/mermaid-js/mermaid.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

transform HTML (insert comment); add console msgs and clarify; add file doc

This commit is contained in:
Ashley Engelund (weedySeaDragon @ github) 2022-09-05 18:39:36 -07:00
parent d38f0e9e03
commit 6554a41f6d
1 changed files with 65 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
src/docs.mts
View File

@ -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);
}