diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000000..1e08a5c16b --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,28 @@ +name: Documentation Checks + +on: + push: + branches: + - develop + paths: + - 'packages/mermaid/src/docs/**/*' + pull_request: + branches: + - develop + paths: + - 'packages/mermaid/src/docs/**/*' +jobs: + spellcheck: + name: 'Docs: Spellcheck' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + name: Check out the code + - uses: actions/setup-node@v1 + name: Setup node + with: + node-version: '16' + - run: npm install -g cspell + name: Install cSpell + - run: cspell --config ./cSpell.json "packages/mermaid/src/docs/**/*.md" --no-progress + name: Run cSpell diff --git a/cSpell.json b/cSpell.json new file mode 100644 index 0000000000..5abf6e2838 --- /dev/null +++ b/cSpell.json @@ -0,0 +1,95 @@ +{ + "version": "0.2", + "language": "en", + "words": [ + "customizability", + "Gantt", + "jison", + "knsv", + "Knut", + "mindmap", + "Mindmaps", + "mitigations", + "sandboxed", + "Sveidqvist", + "verdana", + "Visio" + ], + "ignoreWords": [ + "Adamiecki", + "applitools", + "Asciidoctor", + "Astah", + "Bisheng", + "codedoc", + "Docsy", + "Doku", + "Gitea", + "Gitgraph", + "Grav", + "Inkdrop", + "Jaoude", + "mdbook", + "mermerd", + "mkdocs", + "phpbb", + "Plantuml", + "Playfair's", + "Podlite", + "redmine", + "sphinxcontrib", + "Tuleap" + ], + "patterns": [ + { + "name": "Markdown links", + "pattern": "\\((.*)\\)", + "description": "" + }, + { + "name": "Markdown code blocks", + "pattern": "/^(\\s*`{3,}).*[\\s\\S]*?^\\1/gmx", + "description": "Taken from the cSpell example at https://cspell.org/configuration/patterns/#verbose-regular-expressions" + }, + { + "name": "Inline code blocks", + "pattern": "\\`([^\\`\\r\\n]+?)\\`", + "description": "https://stackoverflow.com/questions/41274241/how-to-capture-inline-markdown-code-but-not-a-markdown-code-fence-with-regex" + }, + { + "name": "Link contents", + "pattern": "\\", + "description": "" + }, + { + "name": "Snippet references", + "pattern": "-- snippet:(.*)", + "description": "" + }, + { + "name": "Snippet references 2", + "pattern": "\\<\\[sample:(.*)", + "description": "another kind of snippet reference" + }, + { + "name": "Multi-line code blocks", + "pattern": "/^\\s*```[\\s\\S]*?^\\s*```/gm" + }, + { + "name": "HTML Tags", + "pattern": "<[^>]*>", + "description": "Reference: https://stackoverflow.com/questions/11229831/regular-expression-to-remove-html-tags-from-a-string" + } + ], + "ignoreRegExpList": [ + "Markdown links", + "Markdown code blocks", + "Inline code blocks", + "Link contents", + "Snippet references", + "Snippet references 2", + "Multi-line code blocks", + "HTML Tags" + ], + "ignorePaths": ["packages/mermaid/src/docs/CHANGELOG.md"] +} diff --git a/docs/README.md b/docs/README.md index 00e03c76d1..62f5b9d9b5 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 npmjs.org. +The above command generates files into the `dist` folder and publishes them to \. ## 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 sanitise 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 sanitize 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 89a3e91460..dec5134989 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 behaviour. +deterministic. This is the default behavior. **Notes**: -This matters if your files are checked into sourcecontrol e.g. git and should not change unless +This matters if your files are checked into source control 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 boundarys to place in each row. +**Notes:** How many boundaries to place in each row. Default value: 2 diff --git a/docs/accessibility.md b/docs/accessibility.md index bce3da25d7..09d80df652 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 coressponding `` and `<desc>` tag in the SVG.** +**When these two options are defined, they will add a corresponding `<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 40dbb6fe6c..4f9e09ab5e 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 skinparam updates +- \[ ] Custom tags/stereotypes support and skin param 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 49c1034922..09df7cf9fe 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) -- [Jetsbrain IDE eg Pycharm](https://www.jetbrains.com/go/guide/tips/mermaid-js-support-in-markdown/) +- [JetBrains 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 f56a2186d6..94baf43e01 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 stabel 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 stable 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 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. +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. mindmap Root diff --git a/packages/mermaid/src/docs/README.md b/packages/mermaid/src/docs/README.md index e8bba38dae..9040eea392 100644 --- a/packages/mermaid/src/docs/README.md +++ b/packages/mermaid/src/docs/README.md @@ -263,7 +263,7 @@ Update version number in `package.json`. npm publish ``` -The above command generates files into the `dist` folder and publishes them to npmjs.org. +The above command generates files into the `dist` folder and publishes them to <npmjs.org>. ## Related projects @@ -279,7 +279,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 sanitise 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 sanitize 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/packages/mermaid/src/docs/Setup.md b/packages/mermaid/src/docs/Setup.md index aae2ae9c09..0c8f50bb80 100644 --- a/packages/mermaid/src/docs/Setup.md +++ b/packages/mermaid/src/docs/Setup.md @@ -72,15 +72,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. @@ -119,11 +119,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 behaviour. +deterministic. This is the default behavior. **Notes**: -This matters if your files are checked into sourcecontrol e.g. git and should not change unless +This matters if your files are checked into source control e.g. git and should not change unless content is changed. Default value: false @@ -210,16 +210,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 @@ -735,16 +735,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 @@ -761,16 +761,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 @@ -992,7 +992,7 @@ Default value: 4 | --------------- | ----------- | ------- | -------- | ------------------ | | c4BoundaryInRow | See Notes | Integer | Required | Any Positive Value | -**Notes:** How many boundarys to place in each row. +**Notes:** How many boundaries to place in each row. Default value: 2 diff --git a/packages/mermaid/src/docs/accessibility.md b/packages/mermaid/src/docs/accessibility.md index 387871de42..ade20a8395 100644 --- a/packages/mermaid/src/docs/accessibility.md +++ b/packages/mermaid/src/docs/accessibility.md @@ -17,7 +17,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 coressponding `<title>` and `<desc>` tag in the SVG.** +**When these two options are defined, they will add a corresponding `<title>` and `<desc>` tag in the SVG.** Let us take a look at the following example with a flowchart diagram: diff --git a/packages/mermaid/src/docs/c4c.md b/packages/mermaid/src/docs/c4c.md index 0ab805182c..f9850f2cd3 100644 --- a/packages/mermaid/src/docs/c4c.md +++ b/packages/mermaid/src/docs/c4c.md @@ -131,7 +131,7 @@ The following unfinished features are not supported in the short term. - - [x] Rel_Back - - [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 skinparam updates +- [ ] Custom tags/stereotypes support and skin param 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. - - [ ] AddRelTag(tagStereo, ?textColor, ?lineColor, ?lineStyle, ?sprite, ?techn, ?legendText, ?legendSprite): Introduces a new Relationship tag. The styles of the tagged relationships are updated and the tag is displayed in the calculated legend. - - [x] UpdateElementStyle(elementName, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?techn, ?legendText, ?legendSprite): This call updates the default style of the elements (component, ...) and creates no additional legend entry. diff --git a/packages/mermaid/src/docs/integrations.md b/packages/mermaid/src/docs/integrations.md index 2b25cb600b..fc300cd6be 100644 --- a/packages/mermaid/src/docs/integrations.md +++ b/packages/mermaid/src/docs/integrations.md @@ -31,7 +31,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) -- [Jetsbrain IDE eg Pycharm](https://www.jetbrains.com/go/guide/tips/mermaid-js-support-in-markdown/) +- [JetBrains 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/packages/mermaid/src/docs/mindmap.md b/packages/mermaid/src/docs/mindmap.md index 85a05e04b5..af7a3df85e 100644 --- a/packages/mermaid/src/docs/mindmap.md +++ b/packages/mermaid/src/docs/mindmap.md @@ -1,6 +1,6 @@ # Mindmap -> 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. +> 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. "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 @@ -31,7 +31,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 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. +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. ``` mindmap