Merge pull request #6495 from generrosity/patch-1

DOC: more complete gantt example

docs/intro/syntax-reference.md

@@ -14,7 +14,11 @@ 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.
+
+Line comments can ignore anything on the line after '%% '.
+
+Unknown words and misspellings will break a diagram, while parameters silently fail.
 
 **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,10 +76,50 @@ 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 syntax. It requires any indentation to be consistent and settings are case sensitive. Mermaid will silently ignore misspelling, but badly formed parameters will break the diagram.
+
+```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)
 
 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.

docs/syntax/gantt.md

@@ -598,4 +598,86 @@ gantt
     5    : 0, 5
 ```
 
+### Timeline (with comments, CSS, config in frontmatter)
+
+```mermaid-example
+---
+    # Frontmatter config, YAML comments
+    title: Ignored if specified in chart
+    displayMode: compact     #gantt specific setting but works at this level too
+    config:
+#        theme: forest
+#        themeCSS: " #item36 { fill: CadetBlue } "
+        themeCSS: " // YAML supports multiline strings using a newline markers: \n
+            #item36 { fill: CadetBlue }       \n
+
+            // Custom marker workaround CSS from forum (below)    \n
+            rect[id^=workaround] { height: calc(100% - 50px) ; transform: translate(9px, 25px); y: 0; width: 1.5px; stroke: none; fill: red; }   \n
+            text[id^=workaround] { fill: red; y: 100%; font-size: 15px;}
+        "
+        gantt:
+            useWidth: 400
+            rightPadding: 0
+            topAxis: true  #false
+            numberSectionStyles: 2
+---
+gantt
+    title Timeline - Gantt Sampler
+    dateFormat YYYY
+    axisFormat %y
+    %% this next line doesn't recognise 'decade' or 'year', but will silently ignore
+    tickInterval 1decade
+
+    section Issue19062
+    71   :            item71, 1900, 1930
+    section Issue19401
+    36   :            item36, 1913, 1935
+    section Issue1300
+    94   :            item94, 1910, 1915
+    5    :            item5,  1920, 1925
+    0    : milestone, item0,  1918, 1s
+    9    : vert,              1906, 1s   %% not yet official
+    64   : workaround,        1923, 1s   %% custom CSS object https://github.com/mermaid-js/mermaid/issues/3250
+```
+
+```mermaid
+---
+    # Frontmatter config, YAML comments
+    title: Ignored if specified in chart
+    displayMode: compact     #gantt specific setting but works at this level too
+    config:
+#        theme: forest
+#        themeCSS: " #item36 { fill: CadetBlue } "
+        themeCSS: " // YAML supports multiline strings using a newline markers: \n
+            #item36 { fill: CadetBlue }       \n
+
+            // Custom marker workaround CSS from forum (below)    \n
+            rect[id^=workaround] { height: calc(100% - 50px) ; transform: translate(9px, 25px); y: 0; width: 1.5px; stroke: none; fill: red; }   \n
+            text[id^=workaround] { fill: red; y: 100%; font-size: 15px;}
+        "
+        gantt:
+            useWidth: 400
+            rightPadding: 0
+            topAxis: true  #false
+            numberSectionStyles: 2
+---
+gantt
+    title Timeline - Gantt Sampler
+    dateFormat YYYY
+    axisFormat %y
+    %% this next line doesn't recognise 'decade' or 'year', but will silently ignore
+    tickInterval 1decade
+
+    section Issue19062
+    71   :            item71, 1900, 1930
+    section Issue19401
+    36   :            item36, 1913, 1935
+    section Issue1300
+    94   :            item94, 1910, 1915
+    5    :            item5,  1920, 1925
+    0    : milestone, item0,  1918, 1s
+    9    : vert,              1906, 1s   %% not yet official
+    64   : workaround,        1923, 1s   %% custom CSS object https://github.com/mermaid-js/mermaid/issues/3250
+```
+
 <!--- cspell:ignore isadded --->

packages/mermaid/src/docs/intro/syntax-reference.md

@@ -8,7 +8,11 @@ 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.
+
+Line comments can ignore anything on the line after '%% '.
+
+Unknown words and misspellings will break a diagram, while parameters silently fail.
 
 **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.
 
@@ -54,10 +58,34 @@ 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 syntax. It requires any indentation to be consistent and settings are case sensitive. Mermaid will silently ignore misspelling, but badly formed parameters will break the diagram.
+
+```mermaid-example
+---
+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)
 
 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.

packages/mermaid/src/docs/syntax/gantt.md

@@ -471,4 +471,46 @@ gantt
     5    : 0, 5
 ```
 
+### Timeline (with comments, CSS, config in frontmatter)
+
+```mermaid-example
+---
+    # Frontmatter config, YAML comments
+    title: Ignored if specified in chart
+    displayMode: compact     #gantt specific setting but works at this level too
+    config:
+#        theme: forest
+#        themeCSS: " #item36 { fill: CadetBlue } "
+        themeCSS: " // YAML supports multiline strings using a newline markers: \n
+            #item36 { fill: CadetBlue }       \n
+
+            // Custom marker workaround CSS from forum (below)    \n
+            rect[id^=workaround] { height: calc(100% - 50px) ; transform: translate(9px, 25px); y: 0; width: 1.5px; stroke: none; fill: red; }   \n
+            text[id^=workaround] { fill: red; y: 100%; font-size: 15px;}
+        "
+        gantt:
+            useWidth: 400
+            rightPadding: 0
+            topAxis: true  #false
+            numberSectionStyles: 2
+---
+gantt
+    title Timeline - Gantt Sampler
+    dateFormat YYYY
+    axisFormat %y
+    %% this next line doesn't recognise 'decade' or 'year', but will silently ignore
+    tickInterval 1decade
+
+    section Issue19062
+    71   :            item71, 1900, 1930
+    section Issue19401
+    36   :            item36, 1913, 1935
+    section Issue1300
+    94   :            item94, 1910, 1915
+    5    :            item5,  1920, 1925
+    0    : milestone, item0,  1918, 1s
+    9    : vert,              1906, 1s   %% not yet official
+    64   : workaround,        1923, 1s   %% custom CSS object https://github.com/mermaid-js/mermaid/issues/3250
+```
+
 <!--- cspell:ignore isadded --->