Merge pull request #181 from DannyBen/add/mermaid

Add optional support for mermaid charts
DannyBen · Jun 23, 2024 · 9d09f75 · 9d09f75
2 parents 3f48ac8 + 8636f96
commit 9d09f75
Show file tree

Hide file tree

Showing 20 changed files with 2,186 additions and 49 deletions.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -16,8 +16,17 @@ jobs:
     - name: Checkout code
       uses: actions/checkout@v4
 
+    - name: Install rush
+      run: curl -Ls http://get.dannyb.co/rush/setup | bash
+
+    - name: Connect rush repo
+      run: rush clone dannyben --shallow --default
+
+    - name: Install pandoc
+      run: rush get pandoc
+
     - name: Install OS dependencies
-      run: sudo apt-get -y install libyaml-dev pandoc
+      run: sudo apt-get -y install libyaml-dev
 
     - name: Setup Ruby
       uses: ruby/setup-ruby@v1
@@ -37,7 +46,6 @@ jobs:
     - name: Checkout code
       uses: actions/checkout@v4
 
-    # Rush needed for easy installation of check-jsonschema
     - name: Install rush
       run: curl -Ls http://get.dannyb.co/rush/setup | bash
 

diff --git a/README.md b/README.md
@@ -51,6 +51,7 @@ $ alias madness='docker run --rm -it -v $PWD:/docs -p 3000:3000 dannyben/madness
 - Can optionally show additional file types in the navigation menu (e.g. PDF
   files).
 - Optional support for `[[Short Link]]` syntax.
+- Optional support for Mermaid diagrams.
 - Optional basic authentication.
 - Support for extended markdown syntax, such as footnotes and syntax
   highlighting.
@@ -153,6 +154,10 @@ auto_toc: true
 # enable syntax highlighter for code snippets
 highlighter: true
 
+# enable mermaid diagramming and charting
+# put your diagram code inside <div class='mermaid'>...</div>
+mermaid: false
+
 # enable the copy to clipboard icon for code snippets
 copy_code: true
 
@@ -258,6 +263,11 @@ specifying internal links, where `[[Anything]]` will be converted to
 `[Anything](Anything)`, which will then be rendered as an internal link to a
 file or a directory in the same directory as the file itself.
 
+### Mermaid Diagrams and Charts
+
+When the `mermaid` option is enabled, you may display any mermaid diagram in
+your document by enclosing it in a `<div class='mermaid'>...</div>` block.
+
 ### Table of Contents Generation
 
 #### Site-wide

diff --git a/app/public/js/vendor/mermaid.min.js b/app/public/js/vendor/mermaid.min.js
diff --git a/app/views/layout.slim b/app/views/layout.slim
@@ -17,5 +17,10 @@ html
       script src="#{config.base_uri}/js/vendor/clipboard.min.js"
       script src="#{config.base_uri}/js/clipboard.js"
 
+    - if config.mermaid
+      script src="#{config.base_uri}/js/vendor/mermaid.min.js"
+      javascript:
+        mermaid.initialize({startOnLoad:true});
+
   body
     == yield
diff --git a/lib/madness/rendering/pandoc.rb b/lib/madness/rendering/pandoc.rb
@@ -6,7 +6,7 @@ class Pandoc
       include ServerHelper
 
       def render(text)
-        PandocRuby.new(text, [{ from: :markdown, to: :html }], *options).convert
+        PandocRuby.new(text, [{ from: :gfm, to: :html }], *options).convert
       end
 
     private

diff --git a/lib/madness/settings.rb b/lib/madness/settings.rb
@@ -64,6 +64,7 @@ def defaults
         auto_nav:          true,
         auto_toc:          true,
         highlighter:       true,
+        mermaid:           false,
         copy_code:         true,
         shortlinks:        false,
         source_link:       nil,

diff --git a/lib/madness/templates/madness.yml b/lib/madness/templates/madness.yml
@@ -42,6 +42,10 @@ auto_toc: true
 # enable syntax highlighter for code snippets
 highlighter: true
 
+# enable mermaid diagramming and charting
+# put your diagram code inside <div class='mermaid'>...</div>
+mermaid: false
+
 # enable the copy to clipboard icon for code snippets
 copy_code: true
 

diff --git a/schemas/madness.json b/schemas/madness.json
@@ -1,26 +1,26 @@
 {
     "$schema": "http://json-schema.org/draft-07/schema",
     "title": "settings",
-    "description": "Settings of the current site\nhttps://madness.dannyb.co/#configuration-file",
+    "description": "Settings for madness server\nhttps://madness.dannyb.co/#configuration-file",
     "type": "object",
     "properties": {
         "path": {
             "title": "path",
-            "description": "A path to the documentation root of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Path to the documentation root\nhttps://madness.dannyb.co/#configuration-file",
             "type": "string",
             "minLength": 1,
             "default": "."
         },
         "port": {
             "title": "port",
-            "description": "A server port of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Server port\nhttps://madness.dannyb.co/#configuration-file",
             "type": "integer",
             "minimum": 0,
             "default": "3000"
         },
         "bind": {
             "title": "bind",
-            "description": "A server listen address of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Server listening address\nhttps://madness.dannyb.co/#configuration-file",
             "type": "string",
             "pattern": "^\\d+\\.\\d+\\.\\d+\\.\\d+$",
             "default": "0.0.0.0"
@@ -37,7 +37,7 @@
         },
         "base_uri": {
             "title": "base uri",
-            "description": "A server root path of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Server root URI\nhttps://madness.dannyb.co/#configuration-file",
             "oneOf": [
                 {
                     "type": "string",
@@ -56,7 +56,7 @@
         },
         "sort_order": {
             "title": "sort order",
-            "description": "The navigation sort order\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Navigation sort order\nhttps://madness.dannyb.co/#configuration-file",
             "type": "string",
             "enum": [
                 "dirs_first",
@@ -66,49 +66,56 @@
         },
         "sidebar": {
             "title": "sidebar",
-            "description": "Whether to enable sidebar of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Whether to enable sidebar\nhttps://madness.dannyb.co/#configuration-file",
             "type": "boolean",
             "default": "true"
         },
         "auto_h1": {
             "title": "auto h1",
-            "description": "Whether to add H1 title to files that do not have one of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Whether to add H1 title to files that do not have one\nhttps://madness.dannyb.co/#configuration-file",
             "type": "boolean",
             "default": "true"
         },
         "auto_nav": {
             "title": "auto nav",
-            "description": "Whether to append navigation to directory READMEs of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Whether to append navigation to directory READMEs\nhttps://madness.dannyb.co/#configuration-file",
             "type": "boolean",
             "default": "true"
         },
         "auto_toc": {
             "title": "auto toc",
-            "description": "Whether to enable table of contents of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Whether to enable table of contents\nhttps://madness.dannyb.co/#configuration-file",
             "type": "boolean",
             "default": "true"
         },
         "highlighter": {
             "title": "highlighter",
-            "description": "Whether to enable syntax highlighter for code snippets of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Whether to enable syntax highlighter for code snippets\nhttps://madness.dannyb.co/#configuration-file",
             "type": "boolean",
             "default": "true"
         },
+        "mermaid": {
+            "title": "mermaid",
+            "description": "Whether to enable support for mermaid diagrams\nhttps://madness.dannyb.co/#configuration-file",
+            "type": "boolean",
+            "default": "true"
+        },
+
         "copy_code": {
             "title": "copy code",
-            "description": "Whether to enable the copy to clipboard icon for code snippets of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Whether to enable the copy to clipboard icon for code snippets\nhttps://madness.dannyb.co/#configuration-file",
             "type": "boolean",
             "default": "true"
         },
         "shortlinks": {
             "title": "shortlinks",
-            "description": "Whether to convert [[Links]] to [Links](Links) of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Whether to convert [[Links]] to [Links](Links)\nhttps://madness.dannyb.co/#configuration-file",
             "type": "boolean",
             "default": "false"
         },
         "toc": {
             "title": "toc",
-            "description": "Whether to generate a table of contents file with this name of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Whether to generate a table of contents file with this name\nhttps://madness.dannyb.co/#configuration-file",
             "oneOf": [
                 {
                     "type": "string",
@@ -124,7 +131,7 @@
         },
         "theme": {
             "title": "theme",
-            "description": "A theme directory of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Theme directory\nhttps://madness.dannyb.co/#configuration-file",
             "oneOf": [
                 {
                     "type": "string",
@@ -140,7 +147,7 @@
         },
         "source_link": {
             "title": "source link",
-            "description": "A link to the page source code\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Template for source code links\nhttps://madness.dannyb.co/#configuration-file",
             "oneOf": [
                 {
                     "type": "string",
@@ -156,7 +163,7 @@
         },
         "source_link_label": {
             "title": "source link label",
-            "description": "A label for the page source code link\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Label for the page source code link\nhttps://madness.dannyb.co/#configuration-file",
             "type": "string",
             "minLength": 1,
             "default": "Page Source"
@@ -173,13 +180,13 @@
         },
         "open": {
             "title": "open",
-            "description": "Whether to open the server URL in the browser of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Whether to open the server URL in the browser\nhttps://madness.dannyb.co/#configuration-file",
             "type": "boolean",
             "default": "false"
         },
         "auth": {
             "title": "auth",
-            "description": "Whether to provide user:password for basic authentication of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Whether to provide user:password for basic authentication\nhttps://madness.dannyb.co/#configuration-file",
             "oneOf": [
                 {
                     "type": "boolean",
@@ -196,13 +203,13 @@
         },
         "auth_zone": {
             "title": "auth zone",
-            "description": "An auth realm name of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "An auth realm name\nhttps://madness.dannyb.co/#configuration-file",
             "type": "string",
             "default": "Restricted Documentation"
         },
         "expose_extensions": {
             "title": "expose extensions",
-            "description": "Whether to show files with these extensions in the navigation and search of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Show files with these extensions in the navigation\nhttps://madness.dannyb.co/#configuration-file",
             "oneOf": [
                 {
                     "type": "string",
@@ -220,12 +227,12 @@
         },
         "exclude": {
             "title": "exclude",
-            "description": "Excluded directories of the current site\nhttps://madness.dannyb.co/#configuration-file",
+            "description": "Excluded directories\nhttps://madness.dannyb.co/#configuration-file",
             "type": "array",
             "minItems": 1,
             "uniqueItems": true,
             "items": {
-                "description": "An excluded directory of the current site\nhttps://madness.dannyb.co/#configuration-file",
+                "description": "An excluded directory\nhttps://madness.dannyb.co/#configuration-file",
                 "type": "string",
                 "default": "^[a-z_\\-0-9]+$"
             }

diff --git a/site/index.html b/site/index.html
@@ -37,6 +37,7 @@ <h2 id="table-of-contents">Table of Contents</h2>
 <li><a href="#images-and-static-files">Images and Static Files</a></li>
 <li><a href="#automatic-h1">Automatic H1</a></li>
 <li><a href="#shortlinks">Shortlinks</a></li>
+<li><a href="#mermaid-diagrams-and-charts">Mermaid Diagrams and Charts</a></li>
 <li><a href="#table-of-contents-generation">Table of Contents Generation</a></li>
 <li><a href="#hidden-directories">Hidden Directories</a></li>
 <li><a href="#controlling-sort-order">Controlling Sort Order</a></li>
@@ -82,6 +83,7 @@ <h2 id="feature-highlights">Feature Highlights</h2>
 <li>Can optionally show additional file types in the navigation menu (e.g. PDF
 files).</li>
 <li>Optional support for <code>[[Short Link]]</code> syntax.</li>
+<li>Optional support for Mermaid diagrams.</li>
 <li>Optional basic authentication.</li>
 <li>Support for extended markdown syntax, such as footnotes and syntax
 highlighting.</li>
@@ -171,6 +173,10 @@ <h2 id="configuration-file">Configuration File</h2>
 <span class="c1"># enable syntax highlighter for code snippets</span>
 <span class="na">highlighter</span><span class="pi">:</span> <span class="kc">true</span>
 
+<span class="c1"># enable mermaid diagramming and charting</span>
+<span class="c1"># put your diagram code inside &lt;div class='mermaid'&gt;...&lt;/div&gt;</span>
+<span class="na">mermaid</span><span class="pi">:</span> <span class="kc">false</span>
+
 <span class="c1"># enable the copy to clipboard icon for code snippets</span>
 <span class="na">copy_code</span><span class="pi">:</span> <span class="kc">true</span>
 
@@ -273,6 +279,11 @@ <h3 id="shortlinks">Shortlinks</h3>
 <code>[Anything](Anything)</code>, which will then be rendered as an internal link to a
 file or a directory in the same directory as the file itself.</p>
 
+<h3 id="mermaid-diagrams-and-charts">Mermaid Diagrams and Charts</h3>
+
+<p>When the <code>mermaid</code> option is enabled, you may display any mermaid diagram in
+your document by enclosing it in a <code>&lt;div class=&#39;mermaid&#39;&gt;...&lt;/div&gt;</code> block.</p>
+
 <h3 id="table-of-contents-generation">Table of Contents Generation</h3>
 
 <h4 id="site-wide">Site-wide</h4>

diff --git a/spec/approvals/cli/config/show b/spec/approvals/cli/config/show
@@ -9,6 +9,7 @@
             auto_nav:  true
             auto_toc:  true
          highlighter:  true
+             mermaid:  ~
            copy_code:  true
           shortlinks:  ~
          source_link:  ~

diff --git a/spec/approvals/cli/config/show-non-default b/spec/approvals/cli/config/show-non-default
@@ -9,6 +9,7 @@
             auto_nav:  true
             auto_toc:  true
          highlighter:  true
+             mermaid:  ~
            copy_code:  true
           shortlinks:  ~
          source_link:  ~

diff --git a/spec/approvals/cli/theme/theme-ls b/spec/approvals/cli/theme/theme-ls
@@ -15,6 +15,7 @@
 - tmp/theme-test/public/js/vendor
 - tmp/theme-test/public/js/vendor/clipboard.min.js
 - tmp/theme-test/public/js/vendor/jquery.min.js
+- tmp/theme-test/public/js/vendor/mermaid.min.js
 - tmp/theme-test/styles
 - tmp/theme-test/styles/_anchor.scss
 - tmp/theme-test/styles/_breadcrumbs.scss

diff --git a/spec/approvals/render/all-disabled b/spec/approvals/render/all-disabled
@@ -98,6 +98,19 @@ end
 <li>This is a <sup>superscript</sup></li>
 </ul>
 
+<h2 id="mermaid-diagrams">Mermaid Diagrams</h2>
+
+<p>Mermaid is supported (after enabling it in the config) by placing the diagram
+code inside a mermaid div:</p>
+
+<div class='mermaid'>
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+</div>
+
 <h2 id="unsafe-html">Unsafe HTML</h2>
 
 <p>This is calculated by Javascript: <span id='demo'></div></p>

diff --git a/spec/approvals/render/all-enabled b/spec/approvals/render/all-enabled
@@ -9,6 +9,7 @@
 <li><a href="#lists">Lists</a></li>
 <li><a href="#tables-and-keyboard">Tables and Keyboard</a></li>
 <li><a href="#text-decorations">Text Decorations</a></li>
+<li><a href="#mermaid-diagrams">Mermaid Diagrams</a></li>
 <li><a href="#unsafe-html">Unsafe HTML</a></li>
 </ul>
 
@@ -108,6 +109,19 @@ with <strong>markdown support</strong> in it</p>
 <li>This is a <sup>superscript</sup></li>
 </ul>
 
+<h2 id="mermaid-diagrams">Mermaid Diagrams</h2>
+
+<p>Mermaid is supported (after enabling it in the config) by placing the diagram
+code inside a mermaid div:</p>
+
+<div class='mermaid'>
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+</div>
+
 <h2 id="unsafe-html">Unsafe HTML</h2>
 
 <p>This is calculated by Javascript: <span id='demo'></div></p>