Add support for Mermaid configuration options, version and style

index.js

@@ -1,4 +1,5 @@
 const doctrine = require('doctrine')
+const env = require('jsdoc/env');
 
 /**
  * @constant {string} JSDOC_MERMAID_TAG
@@ -7,16 +8,16 @@ const doctrine = require('doctrine')
 const JSDOC_MERMAID_TAG = /@mermaid\b/
 
 /**
- * @constant {string} MERMAID_VERSION
- * @description Semver Mermaid version
+ * @constant {string} MERMAID_HTML_SCRIPT
+ * @description Html tag that includes mermaid library
  */
-const MERMAID_VERSION = '8.4.8'
+const MERMAID_HTML_SCRIPT = '<script src="https://unpkg.com/mermaid${MERMAID_VERSION}/dist/mermaid.min.js"></script>'
 
 /**
- * @constant {string} MERMAID_HTML_SCRIPT
- * @description Html tag that include mermaid library
+ * @constant {string} MERMAID_INIT_SCRIPT
+ * @description Html script that include initializes Mermaid with config options
  */
-const MERMAID_HTML_SCRIPT = `<script src="https://unpkg.com/mermaid@${MERMAID_VERSION}/dist/mermaid.min.js"></script>`
+const MERMAID_INIT_SCRIPT = '<script>mermaid.initialize(${MERMAID_CONFIG});</script>\n'
 
 /**
  * @constant {Object} ESCAPE_HTML_MAPPING
@@ -30,6 +31,13 @@ const ESCAPE_HTML_MAPPING = {
   "'": '&#39;'
 }
 
+/**
+ * @constant {object} MERMAID_CONFIG
+ * @description Mermaid configuration options from the JSDoc configuration settings
+ */
+const MERMAID_CONFIG = env.conf.mermaid || {};
+
+
 function escapeHtml(str) {
   return str.replace(/[&<>"']/g, c => ESCAPE_HTML_MAPPING[c])
 }
@@ -45,17 +53,35 @@ exports.handlers = {
         recoverable: true
       }).tags
 
+      let style = MERMAID_CONFIG.style ? ' style="' + MERMAID_CONFIG.style + '"' : ''
+
       const htmls = tags.map(tag => [
-        '<div class="mermaid">',
+        '<div class="mermaid"',
+        style,
+        '>',
         escapeHtml(tag.description),
         '</div>'
       ].join(''))
 
       if (htmls) {
         e.doclet.description = e.doclet.description || ''
 
-        if (!isAddedMermaid[e.doclet.memberof]) {
-          e.doclet.description += MERMAID_HTML_SCRIPT
+        if (!isAddedMermaid[e.doclet.memberof] && !MERMAID_CONFIG.disableScript) {
+          let version = MERMAID_CONFIG.version ? '@' + MERMAID_CONFIG.version : ''
+
+          // clone the Mermaid config so we can remove our unique options before rendering via JSON.stringify
+          let cloneMermaidConfig = {...MERMAID_CONFIG}
+          delete cloneMermaidConfig.version
+          delete cloneMermaidConfig.style
+
+          let MERMAID_VERSION = version;
+
+          const mermaidScript = tags.map(tag => [
+            MERMAID_HTML_SCRIPT.replace('${MERMAID_VERSION}', version),
+            MERMAID_INIT_SCRIPT.replace('${MERMAID_CONFIG}', JSON.stringify(cloneMermaidConfig)),
+          ].join(''))
+          e.doclet.description += mermaidScript
+
           isAddedMermaid[e.doclet.memberof] = true
         }
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsdoc-mermaid",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A tool to automagically create flowcharts and diagrams in your jsdocs.",
   "main": "index.js",
   "scripts": {

readme.md

@@ -11,7 +11,7 @@ yarn add -D jsdoc-mermaid # OR npm install -D jsdoc-mermaid
 
 And then add `jsdoc-mermaid` to your jsdoc configuration file. That's it!
 
-```javascript
+```json
 {
     "plugins": ["jsdoc-mermaid"]
 }
@@ -49,6 +49,44 @@ When you open that page in JSDoc, you should have a shiny new graph!
 
 ![jsdoc-mermaid example](https://user-images.githubusercontent.com/2096353/31104126-b9159786-a7a0-11e7-95ed-689a7f158803.png)
 
+## Customizing Mermaid
+
+You can optionally include a section in your JSDoc configuration file (such as ```conf.json```) to define Mermaid custom configurations.  Simply add a section called ```"mermaid"```:
+
+```json
+{
+  "mermaid": {
+    "theme": "forest"
+  }
+}
+```
+
+This package also supports some new properties to the mermaid configuration:
+
+* ```version```: Let's you specify which Mermaid version to use.  If not provided, defaults to latest Mermaid.
+* ```style```: Let's you add optional CSS styles to the surrounding ```<div>``` tag (which also has class ```mermaid``` if you want to use a proper stylesheet).
+* ```disableScript```: When true, disables the generation of the script for including Mermaid and initializing it.  This is sometimes needed when using a template that already has Mermaid scripting.  Continues to provide  ```<div class="mermaid">``` around the ```@mermaid``` sections.
+
+```json
+{
+  "mermaid": {
+    "theme": "nuetral",
+    "style": "display: flex",
+    "version": "8.3.0",
+    "flowchart": {
+      "curve": "cardinal",
+      "htmlLabels": false
+    }
+  }
+}
+```
+
+### Mermaid configuration documentation
+
+* [Mermaid API](https://mermaid-js.github.io/mermaid/#/mermaidAPI), however the properties are often incorrect
+* [Mermaid configuration defaults](https://mermaid-js.github.io/mermaid/#/mermaidAPI?id=mermaidapi-configuration-defaults) shows the defaults, and appears to be more accurate
+* [Source code for the API](https://github.com/mermaid-js/mermaid/blob/master/src/mermaidAPI.js) which is harder to parse but the most accurate
+
 
 ## Built With