From 8ac7dc81e08deb8b2659fa8af6275d0646a5f15f Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Mon, 21 Aug 2023 15:02:05 +0530 Subject: [PATCH] docs: Add frontmatter config docs --- cSpell.json | 1 + docs/config/configuration.md | 33 ++++++++++++++++++- docs/config/directives.md | 3 ++ docs/config/setup/modules/config.md | 2 +- .../mermaid/src/docs/config/configuration.md | 20 ++++++++++- .../mermaid/src/docs/config/directives.md | 4 +++ 6 files changed, 60 insertions(+), 3 deletions(-) diff --git a/cSpell.json b/cSpell.json index af7a9ca46..52012a337 100644 --- a/cSpell.json +++ b/cSpell.json @@ -44,6 +44,7 @@ "faber", "flatmap", "foswiki", + "frontmatter", "ftplugin", "gantt", "gitea", diff --git a/docs/config/configuration.md b/docs/config/configuration.md index c7b780143..1e85427ea 100644 --- a/docs/config/configuration.md +++ b/docs/config/configuration.md @@ -10,10 +10,41 @@ When mermaid starts, configuration is extracted to determine a configuration to - The default configuration - Overrides at the site level are set by the initialize call, and will be applied to all diagrams in the site/app. The term for this is the **siteConfig**. -- Directives - diagram authors can update select configuration parameters directly in the diagram code via directives. These are applied to the render config. +- Frontmatter (v\+) - diagram authors can update select configuration parameters in the frontmatter of the diagram. These are applied to the render config. +- Directives (Deprecated by Frontmatter) - diagram authors can update select configuration parameters directly in the diagram code via directives. These are applied to the render config. **The render config** is configuration that is used when rendering by applying these configurations. +## Frontmatter config + +The entire mermaid configuration (except the secure configs) can be overridden by the diagram author in the frontmatter of the diagram. The frontmatter is a YAML block at the top of the diagram. + +```mermaid-example +--- +title: Hello Title +config: + theme: base + themeVariables: + primaryColor: "#00ff00" +--- +flowchart + Hello --> World + +``` + +```mermaid +--- +title: Hello Title +config: + theme: base + themeVariables: + primaryColor: "#00ff00" +--- +flowchart + Hello --> World + +``` + ## Theme configuration ## Starting mermaid diff --git a/docs/config/directives.md b/docs/config/directives.md index 27fd767c7..414565d53 100644 --- a/docs/config/directives.md +++ b/docs/config/directives.md @@ -6,6 +6,9 @@ # Directives +> **Warning** +> Directives are deprecated from v\. Please use the `config` key in frontmatter to pass configuration. See [Configuration](./configuration.md) for more details. + ## Directives Directives give a diagram author the capability to alter the appearance of a diagram before rendering by changing the applied configuration. diff --git a/docs/config/setup/modules/config.md b/docs/config/setup/modules/config.md index f1de64e2d..e779224c1 100644 --- a/docs/config/setup/modules/config.md +++ b/docs/config/setup/modules/config.md @@ -118,7 +118,7 @@ The siteConfig #### Defined in -[config.ts:218](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/config.ts#L218) +[config.ts:217](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/config.ts#L217) --- diff --git a/packages/mermaid/src/docs/config/configuration.md b/packages/mermaid/src/docs/config/configuration.md index d248944dd..e52f2c6d5 100644 --- a/packages/mermaid/src/docs/config/configuration.md +++ b/packages/mermaid/src/docs/config/configuration.md @@ -4,10 +4,28 @@ When mermaid starts, configuration is extracted to determine a configuration to - The default configuration - Overrides at the site level are set by the initialize call, and will be applied to all diagrams in the site/app. The term for this is the **siteConfig**. -- Directives - diagram authors can update select configuration parameters directly in the diagram code via directives. These are applied to the render config. +- Frontmatter (v+) - diagram authors can update select configuration parameters in the frontmatter of the diagram. These are applied to the render config. +- Directives (Deprecated by Frontmatter) - diagram authors can update select configuration parameters directly in the diagram code via directives. These are applied to the render config. **The render config** is configuration that is used when rendering by applying these configurations. +## Frontmatter config + +The entire mermaid configuration (except the secure configs) can be overridden by the diagram author in the frontmatter of the diagram. The frontmatter is a YAML block at the top of the diagram. + +```mermaid-example +--- +title: Hello Title +config: + theme: base + themeVariables: + primaryColor: "#00ff00" +--- +flowchart + Hello --> World + +``` + ## Theme configuration ## Starting mermaid diff --git a/packages/mermaid/src/docs/config/directives.md b/packages/mermaid/src/docs/config/directives.md index c85d1d245..5ce9fba6d 100644 --- a/packages/mermaid/src/docs/config/directives.md +++ b/packages/mermaid/src/docs/config/directives.md @@ -1,5 +1,9 @@ # Directives +```warning +Directives are deprecated from v. Please use the `config` key in frontmatter to pass configuration. See [Configuration](./configuration.md) for more details. +``` + ## Directives Directives give a diagram author the capability to alter the appearance of a diagram before rendering by changing the applied configuration.