Merge pull request #3600 from SeanKilleen/docs-spellcheck

Automated docs spell-checking via GitHub Actions (and address all reported issues)

.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

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": "\\<a(.*)\\>",
+      "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"]
+}

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

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
 

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 `<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:
 

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.
 

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

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

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.