Add title support using YAML frontmatter

mermaid-js · Nov 19, 2022 · 70f0247 · 70f0247
1 parent 09ed41b
commit 70f0247
Show file tree

Hide file tree

Showing 48 changed files with 477 additions and 5 deletions.
diff --git a/__mocks__/d3.ts b/__mocks__/d3.ts
@@ -53,6 +53,18 @@ export const MockD3 = (name, parent) => {
     get __parent() {
       return parent;
     },
+    node() {
+      return {
+        getBBox() {
+          return {
+            x: 5,
+            y: 10,
+            height: 15,
+            width: 20,
+          };
+        },
+      };
+    },
   };
   elem.append = (name) => {
     const mockElem = MockD3(name, elem);

diff --git a/cypress/integration/rendering/classDiagram-v2.spec.js b/cypress/integration/rendering/classDiagram-v2.spec.js
@@ -496,4 +496,16 @@ describe('Class diagram V2', () => {
     );
     cy.get('svg');
   });
+
+  it('1433: should render a simple class with a title', () => {
+    imgSnapshotTest(
+      `---
+       title: simple class diagram
+       ---
+       classDiagram-v2
+       class Class10
+      `,
+      {}
+    );
+  });
 });
diff --git a/cypress/integration/rendering/erDiagram.spec.js b/cypress/integration/rendering/erDiagram.spec.js
@@ -273,4 +273,17 @@ describe('Entity Relationship Diagram', () => {
     );
     cy.get('svg');
   });
+
+  it('1433: should render a simple ER diagram with a title', () => {
+    imgSnapshotTest(
+      `---
+       title: simple ER diagram
+       ---
+       erDiagram
+       CUSTOMER ||--o{ ORDER : places
+       ORDER ||--|{ LINE-ITEM : contains
+      `,
+      {}
+    );
+  });
 });
diff --git a/cypress/integration/rendering/flowchart-v2.spec.js b/cypress/integration/rendering/flowchart-v2.spec.js
@@ -663,4 +663,15 @@ flowchart RL
       { htmlLabels: true, flowchart: { htmlLabels: true }, securityLevel: 'loose' }
     );
   });
+  it('1433: should render a titled flowchart with titleTopMargin set to 0', () => {
+    imgSnapshotTest(
+      `---
+      title: Simple flowchart
+      ---
+      flowchart TD
+      A --> B
+      `,
+      { titleTopMargin: 0 }
+    );
+  });
 });
diff --git a/cypress/integration/rendering/gitGraph.spec.js b/cypress/integration/rendering/gitGraph.spec.js
@@ -322,4 +322,15 @@ describe('Git Graph diagram', () => {
       {}
     );
   });
+  it('1433: should render a simple gitgraph with a title', () => {
+    imgSnapshotTest(
+      `---
+      title: simple gitGraph
+      ---
+      gitGraph
+       commit
+      `,
+      {}
+    );
+  });
 });
diff --git a/cypress/integration/rendering/stateDiagram-v2.spec.js b/cypress/integration/rendering/stateDiagram-v2.spec.js
@@ -559,4 +559,16 @@ stateDiagram-v2
       );
     });
   });
+  it('1433: should render a simple state diagram with a title', () => {
+    imgSnapshotTest(
+      `---
+       title: simple state diagram
+       ---
+       stateDiagram-v2
+       [*] --> State1
+       State1 --> [*]
+      `,
+      {}
+    );
+  });
 });
diff --git a/demos/classchart.html b/demos/classchart.html
@@ -17,6 +17,9 @@
     <h1>Class diagram demos</h1>
 
     <pre class="mermaid">
+    ---
+    title: Demo Class Diagram
+    ---
 		classDiagram
       accTitle: Demo Class Diagram
       accDescr: This class diagram show the abstract Animal class, and 3 classes that inherit from it: Duck, Fish, and Zebra.

diff --git a/demos/er.html b/demos/er.html
@@ -20,6 +20,9 @@
   <body>
     <pre class="mermaid">
 
+---
+title: This is a title
+---
 erDiagram
   %% title This is a title
   %% accDescription Test a description

diff --git a/demos/flowchart.html b/demos/flowchart.html
@@ -17,6 +17,9 @@ <h1>Comparison "graph vs. flowchart"</h1>
     <h2>Sample 1</h2>
     <h3>graph</h3>
     <pre class="mermaid">
+    ---
+    title: This is a complicated flow
+    ---
     graph LR
       accTitle: This is a complicated flow
       accDescr: This is the descriptoin for the complicated flow.
@@ -221,6 +224,9 @@ <h3>flowchart</h3>
     <h2>Sample 2</h2>
     <h3>graph</h3>
     <pre class="mermaid">
+    ---
+    title: What to buy
+    ---
     graph TD
       accTitle: What to buy
       accDescr: Options of what to buy with Christmas money

diff --git a/demos/git.html b/demos/git.html
@@ -16,6 +16,9 @@
   <body>
     <h1>Git diagram demo</h1>
     <pre class="mermaid">
+    ---
+    title: Simple Git diagram
+    ---
     gitGraph:
     options
     {

diff --git a/demos/journey.html b/demos/journey.html
@@ -16,8 +16,10 @@
   <body>
     <h1>Journey diagram demo</h1>
     <pre class="mermaid">
-         journey
-    title My working day
+     ---
+     title: My working day 
+     ---
+     journey
       accTitle: Very simple journey demo
       accDescr: 2 main sections: work and home, each with just a few tasks
 

diff --git a/demos/state.html b/demos/state.html
@@ -17,6 +17,9 @@
     <h1>State diagram demos</h1>
     <h2>Very simple showing change from State1 to State2</h2>
     <pre class="mermaid">
+    ---
+    title: Very simple diagram
+    ---
 		stateDiagram
 		  accTitle: This is the accessible title
       accDescr:This is an accessible description
@@ -43,6 +46,9 @@ <h4>And these are how they are applied:</h4>
       </code>
     </p>
     <pre class="mermaid">
+    ---
+    title: Very simple diagram
+    ---
 		stateDiagram-v2
 		  accTitle: This is the accessible title
       accDescr: This is an accessible description

diff --git a/docs/config/setup/modules/defaultConfig.md b/docs/config/setup/modules/defaultConfig.md
@@ -14,7 +14,7 @@
 
 #### Defined in
 
-[defaultConfig.ts:1881](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/defaultConfig.ts#L1881)
+[defaultConfig.ts:1933](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/defaultConfig.ts#L1933)
 
 ---
 

diff --git a/docs/syntax/classDiagram.md b/docs/syntax/classDiagram.md
@@ -14,6 +14,9 @@ The class diagram is the main building block of object-oriented modeling. It is
 Mermaid can render class diagrams.
 
 ```mermaid-example
+---
+title: Animal example
+---
 classDiagram
     note "From Duck till Zebra"
     Animal <|-- Duck
@@ -40,6 +43,9 @@ classDiagram
 ```
 
 ```mermaid
+---
+title: Animal example
+---
 classDiagram
     note "From Duck till Zebra"
     Animal <|-- Duck
@@ -77,6 +83,9 @@ A single instance of a class in the diagram contains three compartments:
 - The bottom compartment contains the operations the class can execute. They are also left-aligned and the first letter is lowercase.
 
 ```mermaid-example
+---
+title: Bank example
+---
 classDiagram
     class BankAccount
     BankAccount : +String owner
@@ -87,6 +96,9 @@ classDiagram
 ```
 
 ```mermaid
+---
+title: Bank example
+---
 classDiagram
     class BankAccount
     BankAccount : +String owner

diff --git a/docs/syntax/entityRelationshipDiagram.md b/docs/syntax/entityRelationshipDiagram.md
@@ -13,13 +13,19 @@ Note that practitioners of ER modelling almost always refer to _entity types_ si
 Mermaid can render ER diagrams
 
 ```mermaid-example
+---
+title: Order example
+---
 erDiagram
     CUSTOMER ||--o{ ORDER : places
     ORDER ||--|{ LINE-ITEM : contains
     CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
 ```
 
 ```mermaid
+---
+title: Order example
+---
 erDiagram
     CUSTOMER ||--o{ ORDER : places
     ORDER ||--|{ LINE-ITEM : contains

diff --git a/docs/syntax/flowchart.md b/docs/syntax/flowchart.md
@@ -15,11 +15,17 @@ It can also accommodate different arrow types, multi directional arrows, and lin
 ### A node (default)
 
 ```mermaid-example
+---
+title: Node
+---
 flowchart LR
     id
 ```
 
 ```mermaid
+---
+title: Node
+---
 flowchart LR
     id
 ```
@@ -33,11 +39,17 @@ found for the node that will be used. Also if you define edges for the node late
 one previously defined will be used when rendering the box.
 
 ```mermaid-example
+---
+title: Node with text
+---
 flowchart LR
     id1[This is the text in the box]
 ```
 
 ```mermaid
+---
+title: Node with text
+---
 flowchart LR
     id1[This is the text in the box]
 ```

diff --git a/docs/syntax/gitgraph.md b/docs/syntax/gitgraph.md
@@ -13,6 +13,9 @@ These kind of diagram are particularly helpful to developers and devops teams to
 Mermaid can render Git diagrams
 
 ```mermaid-example
+    ---
+    title: Example Git diagram
+    ---
     gitGraph
        commit
        commit
@@ -27,6 +30,9 @@ Mermaid can render Git diagrams
 ```
 
 ```mermaid
+    ---
+    title: Example Git diagram
+    ---
     gitGraph
        commit
        commit

diff --git a/docs/syntax/stateDiagram.md b/docs/syntax/stateDiagram.md
@@ -11,6 +11,9 @@
 Mermaid can render state diagrams. The syntax tries to be compliant with the syntax used in plantUml as this will make it easier for users to share diagrams between mermaid and plantUml.
 
 ```mermaid-example
+---
+title: Simple sample
+---
 stateDiagram-v2
     [*] --> Still
     Still --> [*]
@@ -22,6 +25,9 @@ stateDiagram-v2
 ```
 
 ```mermaid
+---
+title: Simple sample
+---
 stateDiagram-v2
     [*] --> Still
     Still --> [*]

diff --git a/package.json b/package.json
@@ -60,6 +60,7 @@
     "@types/eslint": "^8.4.10",
     "@types/express": "^4.17.14",
     "@types/jsdom": "^20.0.1",
+    "@types/js-yaml": "^4.0.5",
     "@types/lodash": "^4.14.188",
     "@types/mdast": "^3.0.10",
     "@types/node": "^18.11.9",
@@ -90,6 +91,7 @@
     "jest": "^29.3.1",
     "jison": "^0.4.18",
     "jsdom": "^20.0.2",
+    "js-yaml": "^4.1.0",
     "lint-staged": "^13.0.3",
     "path-browserify": "^1.0.1",
     "pnpm": "^7.15.0",

diff --git a/packages/mermaid/src/Diagram.ts b/packages/mermaid/src/Diagram.ts
@@ -2,6 +2,7 @@ import * as configApi from './config';
 import { log } from './logger';
 import { getDiagram, registerDiagram } from './diagram-api/diagramAPI';
 import { detectType, getDiagramLoader } from './diagram-api/detectType';
+import { extractFrontMatter } from './diagram-api/frontmatter';
 import { isDetailedError, type DetailedError } from './utils';
 
 export type ParseErrorFunction = (err: string | DetailedError, hash?: any) => void;
@@ -29,6 +30,16 @@ export class Diagram {
     this.db.clear?.();
     this.renderer = diagram.renderer;
     this.parser = diagram.parser;
+    const originalParse = this.parser.parse.bind(this.parser);
+    // Wrap the jison parse() method to handle extracting frontmatter.
+    //
+    // This can't be done in this.parse() because some code
+    // directly calls diagram.parser.parse(), bypassing this.parse().
+    //
+    // Similarly, we can't do this in getDiagramFromText() because some code
+    // calls diagram.db.clear(), which would reset anything set by
+    // extractFrontMatter().
+    this.parser.parse = (text: string) => originalParse(extractFrontMatter(text, this.db));
     this.parser.parser.yy = this.db;
     if (diagram.init) {
       diagram.init(cnf);