docs: Add frontmatter config docs

cSpell.json

@@ -44,6 +44,7 @@
     "faber",
     "flatmap",
     "foswiki",
+    "frontmatter",
     "ftplugin",
     "gantt",
     "gitea",
@@ -154,7 +155,11 @@
     "zenuml"
   ],
   "patterns": [
-    { "name": "Markdown links", "pattern": "\\((.*)\\)", "description": "" },
+    {
+      "name": "Markdown links",
+      "pattern": "\\((.*)\\)",
+      "description": ""
+    },
     {
       "name": "Markdown code blocks",
       "pattern": "/^(\\s*`{3,}).*[\\s\\S]*?^\\1/gmx",
@@ -165,14 +170,25 @@
       "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": "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": "Multi-line code blocks",
+      "pattern": "/^\\s*```[\\s\\S]*?^\\s*```/gm"
+    },
     {
       "name": "HTML Tags",
       "pattern": "<[^>]*>",

demos/er.html

@@ -21,6 +21,8 @@
     <pre class="mermaid">
       ---
       title: This is a title
+      config:
+        theme: forest
       ---
       erDiagram
         %% title This is a title

demos/flowchart.html

@@ -123,6 +123,13 @@ <h3>graph</h3>
 
     <h3>flowchart</h3>
     <pre class="mermaid">
+    ---
+    title: This is another complicated flow
+    config:
+      theme: base
+      flowchart:
+        curve: cardinal
+    ---
     flowchart LR
     sid-B3655226-6C29-4D00-B685-3D5C734DC7E1["
 

packages/mermaid/src/config.ts

@@ -187,7 +187,6 @@ export const sanitize = (options: any) => {
  */
 export const addDirective = (directive: MermaidConfig) => {
   sanitizeDirective(directive);
-
   // If the directive has a fontFamily, but no themeVariables, add the fontFamily to the themeVariables
   if (directive.fontFamily && (!directive.themeVariables || !directive.themeVariables.fontFamily)) {
     directive.themeVariables = { fontFamily: directive.fontFamily };

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.