From 622b441eb074f60bcde92e33dc5c218c2149301a Mon Sep 17 00:00:00 2001 From: lemontreejs Date: Sat, 8 Oct 2022 20:06:57 +0530 Subject: [PATCH] fix: docs path in windows --- docs/README.md | 4 +-- docs/Setup.md | 46 +++++++++++++++++------------------ docs/accessibility.md | 2 +- docs/c4c.md | 2 +- docs/integrations.md | 2 +- docs/mindmap.md | 4 +-- packages/mermaid/src/docs.mts | 23 +++++++++++++++--- 7 files changed, 50 insertions(+), 33 deletions(-) diff --git a/docs/README.md b/docs/README.md index 62f5b9d9b..00e03c76d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -347,7 +347,7 @@ Update version number in `package.json`. npm publish ``` -The above command generates files into the `dist` folder and publishes them to \. +The above command generates files into the `dist` folder and publishes them to npmjs.org. ## Related projects @@ -363,7 +363,7 @@ Detailed information about how to contribute can be found in the [contribution g ## Security and safe diagrams -For public sites, it can be precarious to retrieve text from users on the internet, storing that content for presentation in a browser at a later stage. The reason is that the user content can contain embedded malicious scripts that will run when the data is presented. For Mermaid this is a risk, specially as mermaid diagrams contain many characters that are used in html which makes the standard sanitation unusable as it also breaks the diagrams. We still make an effort to sanitize the incoming code and keep refining the process but it is hard to guarantee that there are no loop holes. +For public sites, it can be precarious to retrieve text from users on the internet, storing that content for presentation in a browser at a later stage. The reason is that the user content can contain embedded malicious scripts that will run when the data is presented. For Mermaid this is a risk, specially as mermaid diagrams contain many characters that are used in html which makes the standard sanitation unusable as it also breaks the diagrams. We still make an effort to sanitise the incoming code and keep refining the process but it is hard to guarantee that there are no loop holes. As an extra level of security for sites with external users we are happy to introduce a new security level in which the diagram is rendered in a sandboxed iframe preventing JavaScript in the code from being executed. This is a great step forward for better security. diff --git a/docs/Setup.md b/docs/Setup.md index dec513498..89a3e9146 100644 --- a/docs/Setup.md +++ b/docs/Setup.md @@ -74,15 +74,15 @@ Theme , the CSS style sheet | Parameter | Description | Type | Required | Values | | ------------- | --------------------------------- | ------ | -------- | ------------------------------------------ | -| securityLevel | Level of trust for parsed diagram | string | Required | `sandbox`, `strict`, `loose`, `antiscript` | +| securityLevel | Level of trust for parsed diagram | string | Required | 'sandbox', 'strict', 'loose', 'antiscript' | **Notes**: -- **`strict`**: (**default**) tags in text are encoded, click functionality is disabled -- **`loose`**: tags in text are allowed, click functionality is enabled -- **`antiscript`**: html tags in text are allowed, (only script element is removed), click +- **strict**: (**default**) tags in text are encoded, click functionality is disabled +- **loose**: tags in text are allowed, click functionality is enabled +- **antiscript**: html tags in text are allowed, (only script element is removed), click functionality is enabled -- **`sandbox`**: With this security level all rendering takes place in a sandboxed iframe. This +- **sandbox**: With this security level all rendering takes place in a sandboxed iframe. This prevent any JavaScript from running in the context. This may hinder interactive functionality of the diagram like scripts, popups in sequence diagram or links to other tabs/targets etc. @@ -121,11 +121,11 @@ Default value: \['secure', 'securityLevel', 'startOnLoad', 'maxTextSize'] This option controls if the generated ids of nodes in the SVG are generated randomly or based on a seed. If set to false, the IDs are generated based on the current date and thus are not -deterministic. This is the default behavior. +deterministic. This is the default behaviour. **Notes**: -This matters if your files are checked into source control e.g. git and should not change unless +This matters if your files are checked into sourcecontrol e.g. git and should not change unless content is changed. Default value: false @@ -212,16 +212,16 @@ Default value: true ### defaultRenderer -| Parameter | Description | Type | Required | Values | -| --------------- | ----------- | ------- | -------- | --------------------------- | -| defaultRenderer | See notes | boolean | 4 | `dagre-d3`, `dagre-wrapper` | +| Parameter | Description | Type | Required | Values | +| --------------- | ----------- | ------- | -------- | ----------------------- | +| defaultRenderer | See notes | boolean | 4 | dagre-d3, dagre-wrapper | **Notes:** Decides which rendering engine that is to be used for the rendering. Legal values are: -`dagre-d3` `dagre-wrapper` - wrapper for `dagre` implemented in mermaid +dagre-d3 dagre-wrapper - wrapper for dagre implemented in mermaid -Default value: `dagre-wrapper` +Default value: 'dagre-wrapper' ## sequence @@ -737,16 +737,16 @@ Default value: true ## defaultRenderer -| Parameter | Description | Type | Required | Values | -| --------------- | ----------- | ------- | -------- | --------------------------- | -| defaultRenderer | See notes | boolean | 4 | `dagre-d3`, `dagre-wrapper` | +| Parameter | Description | Type | Required | Values | +| --------------- | ----------- | ------- | -------- | ----------------------- | +| defaultRenderer | See notes | boolean | 4 | dagre-d3, dagre-wrapper | **Notes**: Decides which rendering engine that is to be used for the rendering. Legal values are: -`dagre-d3` `dagre-wrapper` - wrapper for `dagre` implemented in mermaid +dagre-d3 dagre-wrapper - wrapper for dagre implemented in mermaid -Default value: `dagre-d3` +Default value: 'dagre-d3' ## useMaxWidth @@ -763,16 +763,16 @@ Default value: true ## defaultRenderer -| Parameter | Description | Type | Required | Values | -| --------------- | ----------- | ------- | -------- | --------------------------- | -| defaultRenderer | See notes | boolean | 4 | `dagre-d3`, `dagre-wrapper` | +| Parameter | Description | Type | Required | Values | +| --------------- | ----------- | ------- | -------- | ----------------------- | +| defaultRenderer | See notes | boolean | 4 | dagre-d3, dagre-wrapper | **Notes:** Decides which rendering engine that is to be used for the rendering. Legal values are: -`dagre-d3` `dagre-wrapper` - wrapper for `dagre` implemented in mermaid +dagre-d3 dagre-wrapper - wrapper for dagre implemented in mermaid -Default value: `dagre-d3` +Default value: 'dagre-d3' ## er @@ -994,7 +994,7 @@ Default value: 4 | --------------- | ----------- | ------- | -------- | ------------------ | | c4BoundaryInRow | See Notes | Integer | Required | Any Positive Value | -**Notes:** How many boundaries to place in each row. +**Notes:** How many boundarys to place in each row. Default value: 2 diff --git a/docs/accessibility.md b/docs/accessibility.md index 09d80df65..bce3da25d 100644 --- a/docs/accessibility.md +++ b/docs/accessibility.md @@ -19,7 +19,7 @@ The diagram authors can now add the accessibility options in the diagram definit - `accTitle: "Your Accessibility Title"` or - `accDescr: "Your Accessibility Description"` -**When these two options are defined, they will add a corresponding `` and `<desc>` tag in the SVG.** +**When these two options are defined, they will add a coressponding `<title>` and `<desc>` tag in the SVG.** Let us take a look at the following example with a flowchart diagram: diff --git a/docs/c4c.md b/docs/c4c.md index 4f9e09ab5..40dbb6fe6 100644 --- a/docs/c4c.md +++ b/docs/c4c.md @@ -220,7 +220,7 @@ The following unfinished features are not supported in the short term. - - \[x] RelIndex \* Compatible with C4-Plantuml syntax, but ignores the index parameter. The sequence number is determined by the order in which the rel statements are written. -- \[ ] Custom tags/stereotypes support and skin param updates +- \[ ] Custom tags/stereotypes support and skinparam updates - - \[ ] AddElementTag(tagStereo, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?techn, ?legendText, ?legendSprite): Introduces a new element tag. The styles of the tagged elements are updated and the tag is displayed in the calculated legend. diff --git a/docs/integrations.md b/docs/integrations.md index 09df7cf9f..49c103492 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -33,7 +33,7 @@ They also serve as proof of concept, for the variety of things that can be built - [Mermaid Macro](https://www.redmine.org/plugins/redmine_mermaid_macro) - [redmine-mermaid](https://github.com/styz/redmine_mermaid) - [markdown-for-mermaid-plugin](https://github.com/jamieh-mongolian/markdown-for-mermaid-plugin) -- [JetBrains IDE eg Pycharm](https://www.jetbrains.com/go/guide/tips/mermaid-js-support-in-markdown/) +- [Jetsbrain IDE eg Pycharm](https://www.jetbrains.com/go/guide/tips/mermaid-js-support-in-markdown/) - [mermerd](https://github.com/KarnerTh/mermerd) ## CRM/ERP/Similar diff --git a/docs/mindmap.md b/docs/mindmap.md index 94baf43e0..f56a2186d 100644 --- a/docs/mindmap.md +++ b/docs/mindmap.md @@ -2,7 +2,7 @@ # Mindmap -> Mindmap: This is an experimental diagram for now. The syntax and properties can change in future releases. The syntax is stable except for the icon integration which is the experimental part. +> 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. "A mind map is a diagram used to visually organize information into a hierarchy, showing relationships among pieces of the whole. It is often created around a single concept, drawn as an image in the center of a blank page, to which associated representations of ideas such as images, words and parts of words are added. Major ideas are connected directly to the central concept, and other ideas branch out from those major ideas." Wikipedia @@ -54,7 +54,7 @@ mindmap The syntax for creating Mindmaps is simple and relies on indentation for setting the levels in the hierarchy. -In the following example you can see how there are 3 different levels. One with starting at the left of the text and another level with two rows starting at the same column, defining the node A. At the end there is one more level where the text is indented further then the previous lines defining the nodes B and C. +In the following example you can see how there are 3 dufferent levels. One with starting at the left of the text and another level with two rows starting at the same column, defining the node A. At the end there is one more level where the text is indented further then the prevoius lines defining the nodes B and C. mindmap Root diff --git a/packages/mermaid/src/docs.mts b/packages/mermaid/src/docs.mts index 72357135d..74a8658b5 100644 --- a/packages/mermaid/src/docs.mts +++ b/packages/mermaid/src/docs.mts @@ -41,12 +41,27 @@ import { remark } from 'remark'; // @ts-ignore No typescript declaration file import flatmap from 'unist-util-flatmap'; +/** + * Windows uses '\\' as path delimitter. + * The package `globby` requires all paths to contain forward-slashes only. + * Also it is better if the `AUTOGENERATED_TEXT` has same paths (type of slashes) in all platforms. + * But while actually using the paths, they should be used with platform-specific delimiters. + * So replace all '\\' with '/' for `globby` and `AUTOGENERATED_TEXT` only to maintain uniformity. + * @param path + * @returns normalized path + */ +const normalizeUniform = (path: string) => { + return path.replace(/\\/g, '/'); +}; + // These paths are from the root of the mono-repo, not from the // mermaid sub-directory const SOURCE_DOCS_DIR = join(...'packages/mermaid/src/docs'.split('/')); 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 AUTOGENERATED_TEXT = `# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in ${normalizeUniform( + SOURCE_DOCS_DIR +)}.`; const LOGMSG_TRANSFORMED = 'transformed'; const LOGMSG_TO_BE_TRANSFORMED = 'to be transformed'; @@ -78,7 +93,9 @@ let filesWereTransformed = false; * @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); + // `SOURCE_DOCS_DIR` will have `\\` delimiter in Windows, but path returned by `globby` will have `/` + // So use `normalizeUniform` + const newDir = file.replace(normalizeUniform(SOURCE_DOCS_DIR), FINAL_DOCS_DIR); mkdirSync(dirname(newDir), { recursive: true }); return newDir; }; @@ -205,7 +222,7 @@ const transformHtml = (filename: string) => { const getFilesFromGlobs = async (globs: string[]): Promise<string[]> => { return await globby( - globs.map((glob) => glob.replace(/\\/g, '/')), + globs.map((glob) => normalizeUniform(glob)), { dot: true, }