diff --git a/docs/intro/syntax-reference.md b/docs/intro/syntax-reference.md
index 18548c3c9..9c51fbe4e 100644
--- a/docs/intro/syntax-reference.md
+++ b/docs/intro/syntax-reference.md
@@ -14,7 +14,13 @@ Diagram Examples can be found in the [Mermaid Live Editor](https://mermaid.live)
 
 ## Syntax Structure
 
-One would notice that all **Diagrams definitions begin** with a declaration of the **diagram type**, followed by the definitions of the diagram and its contents. This declaration notifies the parser which kind of diagram the code is supposed to generate.
+One would notice that all **Diagrams definitions begin** with a declaration of the **diagram type**, followed by the definitions of the diagram and its contents. This declaration notifies the parser which kind of diagram the code is supposed to generate. The only exception to this a [Frontmatter](#frontmatter-for-diagram-code) configuration.
+
+Code is case insensitive. Indents are completely ignored but recommended for structure and readability.
+
+Line comments can ignore anything on the line after '%% '.
+
+Unknown words and misspellings will break a diagram, while parameters silently fail. Strings shouldn't be quoted and will parse based on expected parameters.
 
 **Example** : The code below is for an Entity Relationship Diagram, specified by the `erDiagram` declaration. What follows is the definition of the different `Entities` represented in it.
 
@@ -72,12 +78,54 @@ The following are the most commonly used methods, and they are all tied to Merma
 
 Here you can edit certain values to change the behavior and appearance of the diagram.
 
+Each of these techniques are functionally equivalent, but better for different deployments.
+
 ### [The initialize() call](./getting-started.md#_3-calling-the-javascript-api)
 
 Used when Mermaid is called via an API, or through a `<script>` tag.
 
+### Frontmatter for diagram code
+
+Frontmatter is the term for adding YAML metadata at the start of code. This allows for reconfiguration of a diagram before it is rendered. You can pass metadata Frontmatter with your definition by adding `---` to the lines before and after the definition. This 'triple dash' MUST be the only character on the first line.
+
+Frontmatter uses YAML coding syntax. It requires any indenting to be consistent, settings are case sensitive. Mermaid will silently ignore misspelling, but badly formed parameters will break the diagram. Strings will inconsistently require quotation marks.
+
+```mermaid-example
+---
+title: Frontmatter Example
+displayMode: compact
+config:
+  theme: forest
+gantt:
+    useWidth: 400
+    compact: true
+---
+gantt
+    section Waffle
+        Iron  : 1982, 3y
+        House : 1986, 3y
+```
+
+```mermaid
+---
+title: Frontmatter Example
+displayMode: compact
+config:
+  theme: forest
+gantt:
+    useWidth: 400
+    compact: true
+---
+gantt
+    section Waffle
+        Iron  : 1982, 3y
+        House : 1986, 3y
+```
+
 ### [Directives](../config/directives.md)
 
+Note: After 2025, directives will stop working. See [pull request #4691](https://github.com/mermaid-js/mermaid/pull/6491)
+
 Allows for the limited reconfiguration of a diagram just before it is rendered. It can alter the font style, color and other aesthetic aspects of the diagram. You can pass a directive alongside your definition inside `%%{ }%%`. It can be done either above or below your diagram definition.
 
 ### [Theme Manipulation](../config/theming.md)
diff --git a/docs/syntax/gantt.md b/docs/syntax/gantt.md
index 5a704e792..5f7a5cee1 100644
--- a/docs/syntax/gantt.md
+++ b/docs/syntax/gantt.md
@@ -602,19 +602,13 @@ gantt
 
 ```mermaid-example
 ---
-    # 'Triple dash' MUST be first to start mermaid frontmatter.
-    # YAML requires consistent indenting
-    # Settings are caseSensitive, silently ignore misspellings; incorrect parameters will break diagram, and inconsistently require strings to be quoted
-    # Reminder to test diagrams online: https://mermaid.live
-    # 'init' and chart 'config' settings belong here.
+    # Frontmatter config, YAML comments
     title: Ignored if specified in chart
     displayMode: compact     #gantt specific setting but works at this level too
     config:
-        # yaml style comment
 #        theme: forest
 #        themeCSS: " #item36 { fill: CadetBlue } "
         themeCSS: " // YAML supports multiline strings using a newline markers: \n
-            // Comment in CSS using slashes   \n
             #item36 { fill: CadetBlue }       \n
 
             // Custom marker workaround CSS from forum (below)    \n
@@ -627,11 +621,6 @@ gantt
             topAxis: true  #false
             numberSectionStyles: 2
 ---
-%% nb: As of 2025, using directives "%%{" here for 'init' not longer supported - use frontmatter (triple-dash) instead.
-
-%% Comment for Mermaid (double percent + at least a space)
-%% Script is case insensitive. Indents are completely ignored.
-%% misspelling or unknown words will break diagrams, while parameters silently fail. Strings shouldn't be quoted and will auto-detect based on expected parameters
 gantt
     title Timeline - Gantt Sampler
     dateFormat YYYY
@@ -653,19 +642,13 @@ gantt
 
 ```mermaid
 ---
-    # 'Triple dash' MUST be first to start mermaid frontmatter.
-    # YAML requires consistent indenting
-    # Settings are caseSensitive, silently ignore misspellings; incorrect parameters will break diagram, and inconsistently require strings to be quoted
-    # Reminder to test diagrams online: https://mermaid.live
-    # 'init' and chart 'config' settings belong here.
+    # Frontmatter config, YAML comments
     title: Ignored if specified in chart
     displayMode: compact     #gantt specific setting but works at this level too
     config:
-        # yaml style comment
 #        theme: forest
 #        themeCSS: " #item36 { fill: CadetBlue } "
         themeCSS: " // YAML supports multiline strings using a newline markers: \n
-            // Comment in CSS using slashes   \n
             #item36 { fill: CadetBlue }       \n
 
             // Custom marker workaround CSS from forum (below)    \n
@@ -678,11 +661,6 @@ gantt
             topAxis: true  #false
             numberSectionStyles: 2
 ---
-%% nb: As of 2025, using directives "%%{" here for 'init' not longer supported - use frontmatter (triple-dash) instead.
-
-%% Comment for Mermaid (double percent + at least a space)
-%% Script is case insensitive. Indents are completely ignored.
-%% misspelling or unknown words will break diagrams, while parameters silently fail. Strings shouldn't be quoted and will auto-detect based on expected parameters
 gantt
     title Timeline - Gantt Sampler
     dateFormat YYYY
diff --git a/packages/mermaid/src/docs/intro/syntax-reference.md b/packages/mermaid/src/docs/intro/syntax-reference.md
index b26937547..171c1c403 100644
--- a/packages/mermaid/src/docs/intro/syntax-reference.md
+++ b/packages/mermaid/src/docs/intro/syntax-reference.md
@@ -10,7 +10,7 @@ Diagram Examples can be found in the [Mermaid Live Editor](https://mermaid.live)
 
 One would notice that all **Diagrams definitions begin** with a declaration of the **diagram type**, followed by the definitions of the diagram and its contents. This declaration notifies the parser which kind of diagram the code is supposed to generate. The only exception to this a [Frontmatter](#frontmatter-for-diagram-code) configuration.
 
-Code is case insensitive. Indents are completely ignored but recommended for structure and readability. 
+Code is case insensitive. Indents are completely ignored but recommended for structure and readability.
 
 Line comments can ignore anything on the line after '%% '.
 
@@ -60,7 +60,7 @@ The following are the most commonly used methods, and they are all tied to Merma
 
 Here you can edit certain values to change the behavior and appearance of the diagram.
 
-Each of these techniques are functionally equivalent, but better for different deployments.  
+Each of these techniques are functionally equivalent, but better for different deployments.
 
 ### [The initialize() call](./getting-started.md#_3-calling-the-javascript-api)