diff --git a/docs/index.html.todo b/docs/index.html.todo deleted file mode 100644 index 8728338f9..000000000 --- a/docs/index.html.todo +++ /dev/null @@ -1,179 +0,0 @@ - - - - - - mermaid - Markdownish syntax for generating flowcharts, sequence diagrams, class diagrams, - gantt charts and git graphs. - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - diff --git a/packages/mermaid/src/docs.mts b/packages/mermaid/src/docs.mts index aa57a3c01..846e92212 100644 --- a/packages/mermaid/src/docs.mts +++ b/packages/mermaid/src/docs.mts @@ -35,7 +35,7 @@ import { exec } from 'child_process'; import { globby } from 'globby'; import { JSDOM } from 'jsdom'; import type { Code, Root } from 'mdast'; -import { posix, dirname, relative } from 'path'; +import { posix, dirname, relative, join } from 'path'; import prettier from 'prettier'; import { remark } from 'remark'; import chokidar from 'chokidar'; @@ -66,8 +66,11 @@ 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 'pnpm --filter mermaid run docs:build' after making changes to ${SOURCE_DOCS_DIR} to update the ${FINAL_DOCS_DIR} directory with the transformed files.`; const prettierConfig = prettier.resolveConfig.sync('.') ?? {}; +// From https://github.com/vuejs/vitepress/blob/428eec3750d6b5648a77ac52d88128df0554d4d1/src/node/markdownToVue.ts#L20-L21 +const includesRE = //g; +const includedFiles: Set = new Set(); -let filesWereTransformed = false; +const filesTransformed: Set = new Set(); const generateHeader = (file: string): string => { // path from file in docs/* to repo root, e.g ../ or ../../ */ @@ -117,10 +120,10 @@ const logWasOrShouldBeTransformed = (filename: string, wasCopied: boolean) => { * 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 + * @param filename Name of the file that will be verified + * @param doCopy?=false Whether we should copy that transformedContents to the final * documentation directory. Default is `false` - * @param {string} [transformedContent] New contents for the file + * @param transformedContent? New contents for the file */ const copyTransformedContents = (filename: string, doCopy = false, transformedContent?: string) => { const fileInFinalDocDir = changeToFinalDocDir(filename); @@ -132,7 +135,7 @@ const copyTransformedContents = (filename: string, doCopy = false, transformedCo return; // Files are same, skip. } - filesWereTransformed = true; + filesTransformed.add(fileInFinalDocDir); if (doCopy) { writeFileSync(fileInFinalDocDir, newBuffer); } @@ -151,6 +154,19 @@ const transformToBlockQuote = (content: string, type: string) => { const injectPlaceholders = (text: string): string => text.replace(//g, MERMAID_MAJOR_VERSION).replace(//g, CDN_URL); +const transformIncludeStatements = (file: string, text: string): string => { + // resolve includes - src https://github.com/vuejs/vitepress/blob/428eec3750d6b5648a77ac52d88128df0554d4d1/src/node/markdownToVue.ts#L65-L76 + return text.replace(includesRE, (m, m1) => { + try { + const includePath = join(dirname(file), m1); + const content = readSyncedUTF8file(includePath); + includedFiles.add(changeToFinalDocDir(includePath)); + return content; + } catch (error) { + throw new Error(`Failed to resolve include "${m1}" in "${file}": ${error}`); + } + }); +}; /** * Transform a markdown file and write the transformed file to the directory for published * documentation @@ -164,8 +180,7 @@ const injectPlaceholders = (text: string): string => * @param file {string} name of the file that will be verified */ const transformMarkdown = (file: string) => { - const doc = injectPlaceholders(readSyncedUTF8file(file)); - + const doc = injectPlaceholders(transformIncludeStatements(file, readSyncedUTF8file(file))); const ast: Root = remark.parse(doc); const out = flatmap(ast, (c: Code) => { if (c.type !== 'code' || !c.lang) { @@ -270,6 +285,12 @@ const getFilesFromGlobs = async (globs: string[]): Promise => { console.log(`${action} ${mdFiles.length} markdown files...`); mdFiles.forEach(transformMarkdown); + for (const includedFile of includedFiles) { + rmSync(includedFile, { force: true }); + filesTransformed.delete(includedFile); + console.log(`Removed ${includedFile} as it was used inside an @include block.`); + } + const htmlFileGlobs = getGlobs([posix.join(sourceDirGlob, '*.html')]); const htmlFiles = await getFilesFromGlobs(htmlFileGlobs); console.log(`${action} ${htmlFiles.length} html files...`); @@ -282,7 +303,7 @@ const getFilesFromGlobs = async (globs: string[]): Promise => { copyTransformedContents(file, !verifyOnly); // no transformation }); - if (filesWereTransformed) { + if (filesTransformed.size > 0) { if (verifyOnly) { console.log(WARN_DOCSDIR_DOESNT_MATCH); process.exit(1); diff --git a/packages/mermaid/src/docs/index.html.todo b/packages/mermaid/src/docs/index.html.todo deleted file mode 100644 index 8728338f9..000000000 --- a/packages/mermaid/src/docs/index.html.todo +++ /dev/null @@ -1,179 +0,0 @@ - - - - - - mermaid - Markdownish syntax for generating flowcharts, sequence diagrams, class diagrams, - gantt charts and git graphs. - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - diff --git a/packages/mermaid/src/docs/intro/examples.md b/packages/mermaid/src/docs/intro/examples.md new file mode 100644 index 000000000..f4cb3b929 --- /dev/null +++ b/packages/mermaid/src/docs/intro/examples.md @@ -0,0 +1,100 @@ +## Diagram Types + +### [Flowchart](../syntax/flowchart.md?id=flowcharts-basic-syntax) + +```mermaid-example +graph TD; + A-->B; + A-->C; + B-->D; + C-->D; +``` + +### [Sequence diagram](../syntax/sequenceDiagram.md) + +```mermaid-example +sequenceDiagram + participant Alice + participant Bob + Alice->>John: Hello John, how are you? + loop Healthcheck + John->>John: Fight against hypochondria + end + Note right of John: Rational thoughts
prevail! + John-->>Alice: Great! + John->>Bob: How about you? + Bob-->>John: Jolly good! +``` + +### [Gantt diagram](../syntax/gantt.md) + +```mermaid-example +gantt +dateFormat YYYY-MM-DD +title Adding GANTT diagram to mermaid +excludes weekdays 2014-01-10 + +section A section +Completed task :done, des1, 2014-01-06,2014-01-08 +Active task :active, des2, 2014-01-09, 3d +Future task : des3, after des2, 5d +Future task2 : des4, after des3, 5d +``` + +### [Class diagram](../syntax/classDiagram.md) + +```mermaid-example +classDiagram +Class01 <|-- AveryLongClass : Cool +Class03 *-- Class04 +Class05 o-- Class06 +Class07 .. Class08 +Class09 --> C2 : Where am i? +Class09 --* C3 +Class09 --|> Class07 +Class07 : equals() +Class07 : Object[] elementData +Class01 : size() +Class01 : int chimp +Class01 : int gorilla +Class08 <--> C2: Cool label +``` + +### [Git graph](../syntax/gitgraph.md) + +```mermaid-example + gitGraph + commit + commit + branch develop + commit + commit + commit + checkout main + commit + commit +``` + +### [Entity Relationship Diagram - :exclamation: experimental](../syntax/entityRelationshipDiagram.md) + +```mermaid-example +erDiagram + CUSTOMER ||--o{ ORDER : places + ORDER ||--|{ LINE-ITEM : contains + CUSTOMER }|..|{ DELIVERY-ADDRESS : uses + +``` + +### [User Journey Diagram](../syntax/userJourney.md) + +```mermaid-example +journey + title My working day + section Go to work + Make tea: 5: Me + Go upstairs: 3: Me + Do work: 1: Me, Cat + section Go home + Go downstairs: 5: Me + Sit down: 5: Me +``` diff --git a/packages/mermaid/src/docs/intro/index.md b/packages/mermaid/src/docs/intro/index.md index b58321e75..df1aa3b62 100644 --- a/packages/mermaid/src/docs/intro/index.md +++ b/packages/mermaid/src/docs/intro/index.md @@ -44,106 +44,7 @@ In our release process we rely heavily on visual regression tests using [applito -## Diagram Types - -### [Flowchart](../syntax/flowchart.md?id=flowcharts-basic-syntax) - -```mermaid-example -graph TD; - A-->B; - A-->C; - B-->D; - C-->D; -``` - -### [Sequence diagram](../syntax/sequenceDiagram.md) - -```mermaid-example -sequenceDiagram - participant Alice - participant Bob - Alice->>John: Hello John, how are you? - loop Healthcheck - John->>John: Fight against hypochondria - end - Note right of John: Rational thoughts
prevail! - John-->>Alice: Great! - John->>Bob: How about you? - Bob-->>John: Jolly good! -``` - -### [Gantt diagram](../syntax/gantt.md) - -```mermaid-example -gantt -dateFormat YYYY-MM-DD -title Adding GANTT diagram to mermaid -excludes weekdays 2014-01-10 - -section A section -Completed task :done, des1, 2014-01-06,2014-01-08 -Active task :active, des2, 2014-01-09, 3d -Future task : des3, after des2, 5d -Future task2 : des4, after des3, 5d -``` - -### [Class diagram](../syntax/classDiagram.md) - -```mermaid-example -classDiagram -Class01 <|-- AveryLongClass : Cool -Class03 *-- Class04 -Class05 o-- Class06 -Class07 .. Class08 -Class09 --> C2 : Where am i? -Class09 --* C3 -Class09 --|> Class07 -Class07 : equals() -Class07 : Object[] elementData -Class01 : size() -Class01 : int chimp -Class01 : int gorilla -Class08 <--> C2: Cool label -``` - -### [Git graph](../syntax/gitgraph.md) - -```mermaid-example - gitGraph - commit - commit - branch develop - commit - commit - commit - checkout main - commit - commit -``` - -### [Entity Relationship Diagram - :exclamation: experimental](../syntax/entityRelationshipDiagram.md) - -```mermaid-example -erDiagram - CUSTOMER ||--o{ ORDER : places - ORDER ||--|{ LINE-ITEM : contains - CUSTOMER }|..|{ DELIVERY-ADDRESS : uses - -``` - -### [User Journey Diagram](../syntax/userJourney.md) - -```mermaid-example -journey - title My working day - section Go to work - Make tea: 5: Me - Go upstairs: 3: Me - Do work: 1: Me, Cat - section Go home - Go downstairs: 5: Me - Sit down: 5: Me -``` + ## Installation