From 870cfdc44ce387805fb685a0fc23e0dacf75ec99 Mon Sep 17 00:00:00 2001 From: Emerson Bottero Date: Thu, 20 Oct 2022 02:13:18 -0300 Subject: [PATCH] docs: transform custom blocks, warning notes jison --- README.md | 2 +- .../src/docs/.vitepress/blocks-markdown.ts | 25 +++++++++ .../mermaid/src/docs/.vitepress/config.ts | 17 +++++- .../docs/.vitepress/mermaid-markdown-all.ts | 56 +++++++++---------- .../mermaid/src/docs/community/newDiagram.md | 13 +++-- .../mermaid/src/docs/config/8.6.0_docs.md | 38 ++++++------- packages/mermaid/src/docs/config/theming.md | 4 +- packages/mermaid/src/docs/config/usage.md | 24 ++++---- packages/mermaid/src/docs/intro/index.md | 2 +- packages/mermaid/src/docs/syntax/flowchart.md | 2 +- .../src/docs/syntax/sequenceDiagram.md | 4 +- 11 files changed, 111 insertions(+), 76 deletions(-) create mode 100644 packages/mermaid/src/docs/.vitepress/blocks-markdown.ts diff --git a/README.md b/README.md index 90ae1ad4c..97ad1f6c4 100644 --- a/README.md +++ b/README.md @@ -354,7 +354,7 @@ To report a vulnerability, please e-mail security@mermaid.live with a descriptio A quick note from Knut Sveidqvist: -> _Many thanks to the [d3](https://d3js.org/) and [dagre-d3](https://github.com/cpettitt/dagre-d3) projects for providing the graphical layout and drawing libraries!_ >_Thanks also to the [js-sequence-diagram](https://bramp.github.io/js-sequence-diagrams) project for usage of the grammar for the sequence diagrams. Thanks to Jessica Peter for inspiration and starting point for gantt rendering._ >_Thank you to [Tyler Long](https://github.com/tylerlong) who has been a collaborator since April 2017._ +> _Many thanks to the [d3](https://d3js.org/) and [dagre-d3](https://github.com/cpettitt/dagre-d3) projects for providing the graphical layout and drawing libraries!_ >_Thanks also to the [js-sequence-diagram](https://bramp.github.io/js-sequence-diagrams) project for usage of the grammar for the sequence diagrams. Thanks to Jessica Peter for inspiration and starting point for gantt rendering._ > _Thank you to [Tyler Long](https://github.com/tylerlong) who has been a collaborator since April 2017._ > > _Thank you to the ever-growing list of [contributors](https://github.com/knsv/mermaid/graphs/contributors) that brought the project this far!_ diff --git a/packages/mermaid/src/docs/.vitepress/blocks-markdown.ts b/packages/mermaid/src/docs/.vitepress/blocks-markdown.ts new file mode 100644 index 000000000..870f1582c --- /dev/null +++ b/packages/mermaid/src/docs/.vitepress/blocks-markdown.ts @@ -0,0 +1,25 @@ +const CustomMarkdown = (md) => { + const fence = md.renderer.rules.fence.bind(md.renderer.rules); + + md.renderer.rules.fence = (tokens, index, options, env, slf) => { + const token = tokens[index]; + + if (token.info.trim() === 'warning') { + return `

WARNING

${token.content}}

`; + } + + if (token.info.trim() === 'note') { + return `

NOTE

${token.content}}

`; + } + + if (token.info.trim() === 'jison') { + return `
jison
${token.content
+        .replace(//g, '>')}}
`; + } + + return fence(tokens, index, options, env, slf); + }; +}; + +export default CustomMarkdown; diff --git a/packages/mermaid/src/docs/.vitepress/config.ts b/packages/mermaid/src/docs/.vitepress/config.ts index e15be5ece..23b5d6a85 100644 --- a/packages/mermaid/src/docs/.vitepress/config.ts +++ b/packages/mermaid/src/docs/.vitepress/config.ts @@ -1,13 +1,24 @@ import { version } from '../../../package.json'; -import MermaidMarkdown from './mermaid-markdown-all'; +import MermaidExample from './mermaid-markdown-all'; +import { MermaidMarkdown } from 'vitepress-plugin-mermaid'; +import CustomMarkdown from './blocks-markdown'; import { defineConfig } from 'vitepress'; +const allMarkdownTransformers = { + config: async (md) => { + MermaidMarkdown(md); + await MermaidExample(md); + CustomMarkdown(md); + }, +}; + export default defineConfig({ lang: 'en-US', title: 'Mermaid', description: 'Create diagrams and visualizations using text and code.', - base: '/mermaid-docs/', - markdown: MermaidMarkdown, + base: '/mermaid-js/', + markdown: allMarkdownTransformers, + head: [['link', { rel: 'icon', type: 'image/x-icon', href: '/mermaid-js/favicon.ico' }]], themeConfig: { nav: nav(), editLink: { diff --git a/packages/mermaid/src/docs/.vitepress/mermaid-markdown-all.ts b/packages/mermaid/src/docs/.vitepress/mermaid-markdown-all.ts index a7848fce7..4d2b855a8 100644 --- a/packages/mermaid/src/docs/.vitepress/mermaid-markdown-all.ts +++ b/packages/mermaid/src/docs/.vitepress/mermaid-markdown-all.ts @@ -1,4 +1,3 @@ -import { MermaidMarkdown } from 'vitepress-plugin-mermaid'; // import { deflate } from 'pako'; // import { fromUint8Array } from 'js-base64'; import shiki from 'shiki'; @@ -18,39 +17,38 @@ import shiki from 'shiki'; // return fromUint8Array(compressed, true); // }; -export default { - config: async (md) => { - MermaidMarkdown(md); - const fence = md.renderer.rules.fence.bind(md.renderer.rules); +const MermaidExample = async (md) => { + const fence = md.renderer.rules.fence.bind(md.renderer.rules); - const highlighter = await shiki.getHighlighter({ theme: 'material-palenight' }); + const highlighter = await shiki.getHighlighter({ theme: 'material-palenight' }); - md.renderer.rules.fence = (tokens, index, options, env, slf) => { - const token = tokens[index]; + md.renderer.rules.fence = (tokens, index, options, env, slf) => { + const token = tokens[index]; + // console.log("==>",token.info); - if (token.info.trim() === 'mermaid-example') { - let code = highlighter.codeToHtml(token.content, { lang: 'mermaid' }); - code = code.replace('#2e3440ff', 'transparent'); - code = code.replace('#292D3E', 'transparent'); - console.log(token.content); + if (token.info.trim() === 'mermaid-example') { + let code = highlighter.codeToHtml(token.content, { lang: 'mermaid' }); + code = code.replace('#2e3440ff', 'transparent'); + code = code.replace('#292D3E', 'transparent'); - code = - '
Code:
' + - `
` + - // tODO: compute edit link! - // `✒️` + - `mermaid` + - code + - '
'; + code = + '
Code:
' + + `
` + + // TODO: compute edit link! + // `✒️` + + `mermaid` + + code + + '
'; - // return code; - return `${code} + // return code; + return `${code}
Render:
`; - } - return fence(tokens, index, options, env, slf); - }; - }, + } + return fence(tokens, index, options, env, slf); + }; }; + +export default MermaidExample; diff --git a/packages/mermaid/src/docs/community/newDiagram.md b/packages/mermaid/src/docs/community/newDiagram.md index 96ec9d75d..a902f1961 100644 --- a/packages/mermaid/src/docs/community/newDiagram.md +++ b/packages/mermaid/src/docs/community/newDiagram.md @@ -15,7 +15,7 @@ For instance: There are some jison specific sub steps here where the parser stores the data encountered when parsing the diagram, this data is later used by the renderer. You can during the parsing call a object provided to the parser by the user of the parser. This object can be called during parsing for storing data. -``` +```jison statement : 'participant' actor { $$='actor'; } | signal { $$='signal'; } @@ -26,9 +26,9 @@ statement In the extract of the grammar above, it is defined that a call to the setTitle method in the data object will be done when parsing and the title keyword is encountered. -::: tip +```note Make sure that the `parseError` function for the parser is defined and calling `mermaid.parseError`. This way a common way of detecting parse errors is provided for the end-user. -::: +``` For more info look in the example diagram type: @@ -120,8 +120,7 @@ Here some pointers on how to handle these different areas. Here is example handling from flowcharts: Jison: -``` - +```jison /* lexical grammar */ %lex %x open_directive @@ -179,7 +178,8 @@ accDescr { In a similar way to the directives the jison syntax are quite similar between the diagrams. -``` +```jison + * lexical grammar */ %lex %x acc_title @@ -199,6 +199,7 @@ statement : acc_title acc_title_value { $$=$2.trim();yy.setTitle($$); } | acc_descr acc_descr_value { $$=$2.trim();yy.setAccDescription($$); } | acc_descr_multiline_value { $$=$1.trim();yy.setAccDescription($$); } + ``` The functions for setting title and description are provided by a common module. This is the import from flowDb.js: diff --git a/packages/mermaid/src/docs/config/8.6.0_docs.md b/packages/mermaid/src/docs/config/8.6.0_docs.md index 5b2f03caf..40d1cc946 100644 --- a/packages/mermaid/src/docs/config/8.6.0_docs.md +++ b/packages/mermaid/src/docs/config/8.6.0_docs.md @@ -46,9 +46,9 @@ Implementors can only modify configurations using directives, and cannot change The Two types of directives: are `init` (or `initialize`) and `wrap`. -::: note +```note All directives are enclosed in `%%{ }%%` -::: +``` Older versions of mermaid will not parse directives because `%%` will comment out the directive. This makes the update backwards-compatible. @@ -60,7 +60,7 @@ Older versions of mermaid will not parse directives because `%%` will comment ou | --------- | ----------------------- | --------- | -------- | ----------------------------------------------- | | init | modifies configurations | Directive | Optional | Any parameters not included in the secure array | -::: note +```note init would be an argument-directive: `%%{init: { **insert argument here**}}%%` The json object that is passed as {**argument** } must be valid, quoted json or it will be ignored. @@ -71,7 +71,7 @@ The json object that is passed as {**argument** } must be valid, quoted json or Configurations that are passed through init cannot change the parameters in a secure array at a higher level. In the event of a collision, mermaid will give priority to secure arrays and parse the request without changing the values of those parameters in conflict. When deployed within code, init is called before the graph/diagram description. -::: +``` **for example**: @@ -93,15 +93,15 @@ When deployed within code, init is called before the graph/diagram description. | --------- | ----------------------------- | --------- | -------- | ---------- | | wrap | a callable text-wrap function | Directive | Optional | %%{wrap}%% | -::: note +```note Wrap is a function that is currently only deployable for sequence diagrams. -Wrap respects a manually added , so if the user wants to break up their text, they have full control over line breaks by adding tags. +`Wrap respects a manually added
, so if the user wants to break up their text, they have full control over line breaks by adding
tags.` It is a non-argument directive and can be executed thusly: `%%{wrap}%%` . -::: +``` **An example of text wrapping in a sequence diagram**: @@ -143,13 +143,13 @@ Example of **object.Assign**: | --------------- | ------------------------------------- | ----------- | --------------------------------------- | ---------- | ---------- | | `setSiteConfig` | Sets the siteConfig to desired values | Put Request | Any Values, except ones in secure array | conf | siteConfig | -::: note +```note Sets the siteConfig. The siteConfig is a protected configuration for repeat use. Calls to reset() will reset the currentConfig to siteConfig. Calls to reset(configApi.defaultConfig) will reset siteConfig and currentConfig to the defaultConfig Note: currentConfig is set in this function。 Default value: will mirror Global Config -::: +``` ## getSiteConfig @@ -157,9 +157,9 @@ Default value: will mirror Global Config | --------------- | --------------------------------------------------- | ----------- | ---------------------------------- | | `getSiteConfig` | Returns the current `siteConfig` base configuration | Get Request | Returns Any Values in `siteConfig` | -::: note +```note Returns any values in siteConfig. -::: +``` ## setConfig @@ -167,11 +167,11 @@ Returns any values in siteConfig. | ----------- | ------------------------------------------ | ----------- | --------------------------------- | ---------- | ---------------------------------------------- | | `setConfig` | Sets the `currentConfig` to desired values | Put Request | Any Values, those in secure array | conf | `currentConfig` merged with the sanitized conf | -::: note +```note Sets the currentConfig. The parameter conf is sanitized based on the siteConfig.secure keys. Any values found in conf with key found in siteConfig.secure will be replaced with the corresponding siteConfig value. -::: +``` ## getConfig @@ -179,9 +179,9 @@ siteConfig value. | ----------- | --------------------------- | ----------- | ------------------------------- | | `getConfig` | Obtains the `currentConfig` | Get Request | Any Values from `currentConfig` | -::: note +```note Returns any values in currentConfig. -::: +``` ## sanitize @@ -189,10 +189,10 @@ Returns any values in currentConfig. | ---------- | ---------------------------------------- | -------------- | ------ | | `sanitize` | Sets the `siteConfig` to desired values. | Put Request(?) | None | -::: note +```note modifies options in-place Ensures options parameter does not attempt to override siteConfig secure keys. -::: +``` ## reset @@ -206,8 +206,8 @@ Ensures options parameter does not attempt to override siteConfig secure keys. | --------- | ------------------------------------------------------------ | ---------- | -------- | -------------------------------------------- | | `conf` | base set of values, which `currentConfig` could be reset to. | Dictionary | Required | Any Values, with respect to the secure Array | -::: note +```note default: current siteConfig (optional, default `getSiteConfig()`) -::: s +``` ## For more information, read [Setup](setup/README). diff --git a/packages/mermaid/src/docs/config/theming.md b/packages/mermaid/src/docs/config/theming.md index f68288ca7..78f3546cc 100644 --- a/packages/mermaid/src/docs/config/theming.md +++ b/packages/mermaid/src/docs/config/theming.md @@ -108,9 +108,9 @@ You can create your own themes, by changing any of the given variables below. If ## Theme Variables Reference Table -::: note +```note Variables that are unique to some diagrams can be affected by changes in Theme Variables -::: +``` | Variable | Default/Base/Factor value | Calc | Description | | -------------------- | ------------------------------ | ---- | -------------------------------------------------------------------------------------------------------------------------------- | diff --git a/packages/mermaid/src/docs/config/usage.md b/packages/mermaid/src/docs/config/usage.md index 50b1a13ea..e7c745f78 100644 --- a/packages/mermaid/src/docs/config/usage.md +++ b/packages/mermaid/src/docs/config/usage.md @@ -115,10 +115,10 @@ Values: - **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 prevent any JavaScript 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. -::: note +```note This changes the default behaviour of mermaid so that after upgrade to 8.2, unless the `securityLevel` is not changed, tags in flowcharts are encoded as tags and clicking is disabled. **sandbox** security level is still in the beta version. -::: +``` **If you are taking responsibility for the diagram source security you can set the `securityLevel` to a value of your choosing . This allows clicks and tags are allowed.** @@ -183,9 +183,9 @@ Or with no config object, and a jQuery selection: mermaid.init(undefined, $('#someId .yetAnotherClass')); ``` -::: warning +```warning This type of integration is deprecated. Instead the preferred way of handling more complex integration is to use the mermaidAPI instead. -::: +``` ## Usage with webpack @@ -339,9 +339,9 @@ on what kind of integration you use. ``` -::: tip +```note This is the preferred way of configuring mermaid. -::: +``` ### The following methods are deprecated and are kept only for backwards compatibility. @@ -357,9 +357,9 @@ approach are: mermaid.startOnLoad = true; ``` -::: warning +```warning This way of setting the configuration is deprecated. Instead the preferred way is to use the initialize method. This functionality is only kept for backwards compatibility. -::: +``` ## Using the mermaid_config @@ -373,9 +373,9 @@ approach are: mermaid_config.startOnLoad = true; ``` -::: warning +```warning This way of setting the configuration is deprecated. Instead the preferred way is to use the initialize method. This functionality is only kept for backwards compatibility. -::: +``` ## Using the mermaid.init call @@ -388,6 +388,6 @@ To set some configuration via the mermaid object. The two parameters that are su mermaid_config.startOnLoad = true; ``` -::: warning +```warning This way of setting the configuration is deprecated. Instead the preferred way is to use the initialize method. This functionality is only kept for backwards compatibility. -::: +``` diff --git a/packages/mermaid/src/docs/intro/index.md b/packages/mermaid/src/docs/intro/index.md index c65ed1830..68a5e3f5a 100644 --- a/packages/mermaid/src/docs/intro/index.md +++ b/packages/mermaid/src/docs/intro/index.md @@ -281,7 +281,7 @@ To report a vulnerability, please e-mail security@mermaid.live with a descriptio A quick note from Knut Sveidqvist: -> _Many thanks to the [d3](https://d3js.org/) and [dagre-d3](https://github.com/cpettitt/dagre-d3) projects for providing the graphical layout and drawing libraries!_ >_Thanks also to the [js-sequence-diagram](https://bramp.github.io/js-sequence-diagrams) project for usage of the grammar for the sequence diagrams. Thanks to Jessica Peter for inspiration and starting point for gantt rendering._ >_Thank you to [Tyler Long](https://github.com/tylerlong) who has been a collaborator since April 2017._ +> _Many thanks to the [d3](https://d3js.org/) and [dagre-d3](https://github.com/cpettitt/dagre-d3) projects for providing the graphical layout and drawing libraries!_ >_Thanks also to the [js-sequence-diagram](https://bramp.github.io/js-sequence-diagrams) project for usage of the grammar for the sequence diagrams. Thanks to Jessica Peter for inspiration and starting point for gantt rendering._ > _Thank you to [Tyler Long](https://github.com/tylerlong) who has been a collaborator since April 2017._ > > _Thank you to the ever-growing list of [contributors](https://github.com/knsv/mermaid/graphs/contributors) that brought the project this far!_ diff --git a/packages/mermaid/src/docs/syntax/flowchart.md b/packages/mermaid/src/docs/syntax/flowchart.md index 478e76ef3..25252e54d 100644 --- a/packages/mermaid/src/docs/syntax/flowchart.md +++ b/packages/mermaid/src/docs/syntax/flowchart.md @@ -4,7 +4,7 @@ All Flowcharts are composed of **nodes**, the geometric shapes and **edges**, th It can also accommodate different arrow types, multi directional arrows, and linking to and from subgraphs. -> **Important note**: Do not type the word "end" as a Flowchart node. Capitalize all or any one the letters to keep the flowchart from breaking, i.e, "End" or "END". Or you can apply this [workaround](https://github.com/mermaid-js/mermaid/issues/1444#issuecomment-639528897).\*\* +> **Important note**: Do not type the word "end" as a Flowchart node. Capitalize all or any one the letters to keep the flowchart from breaking, i.e, "End" or "END". Or you can apply this [workaround](https://github.com/mermaid-js/mermaid/issues/1444#issuecomment-639528897). ### A node (default) diff --git a/packages/mermaid/src/docs/syntax/sequenceDiagram.md b/packages/mermaid/src/docs/syntax/sequenceDiagram.md index 98deaca37..35c3cc9a1 100644 --- a/packages/mermaid/src/docs/syntax/sequenceDiagram.md +++ b/packages/mermaid/src/docs/syntax/sequenceDiagram.md @@ -11,11 +11,11 @@ sequenceDiagram Alice-)John: See you later! ``` -::: note +```note A note on nodes, the word "end" could potentially break the diagram, due to the way that the mermaid language is scripted. If unavoidable, one must use parentheses(), quotation marks "", or brackets {},[], to enclose the word "end". i.e : (end), [end], {end}. -::: +``` ## Syntax