docs: Add frontmatter config docs

cSpell.json

@@ -44,6 +44,7 @@
     "faber",
     "flatmap",
     "foswiki",
+    "frontmatter",
     "ftplugin",
     "gantt",
     "gitea",

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\<MERMAID_RELEASE_VERSION>+) - 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

docs/config/directives.md

@@ -6,6 +6,9 @@
 
 # Directives
 
+> **Warning**
+> Directives are deprecated from v\<MERMAID_RELEASE_VERSION>. 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.

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)
 
 ---
 

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<MERMAID_RELEASE_VERSION>+) - 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

packages/mermaid/src/docs/config/directives.md

@@ -1,5 +1,9 @@
 # Directives
 
+```warning
+Directives are deprecated from v<MERMAID_RELEASE_VERSION>. 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.