Fixed so PrismJS and Mermaid can be used together (#318)

Co-authored-by: Sridhar Ratnakumar <srid@srid.ca>
srid · Aug 3, 2022 · 8bd7cf6 · 8bd7cf6
1 parent bbdee36
commit 8bd7cf6
Show file tree

Hide file tree

Showing 5 changed files with 111 additions and 46 deletions.
diff --git a/default/index.yaml b/default/index.yaml
@@ -87,9 +87,21 @@ js:
   # Syntax highlighting using prism.js
   prism: |
     <!-- Prism.js -->
-    <link href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.26.0/themes/prism-tomorrow.min.css" rel="stylesheet" />
-    <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.26.0/prism.min.js"></script>
-    <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.26.0/plugins/autoloader/prism-autoloader.min.js"></script>
+    <link href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.28.0/themes/prism-tomorrow.min.css" rel="stylesheet" />
+    <!-- Note: Having data-manual attribute so our custom code controls PrismJS, which allows support of Mermaid & Emanote hot-reloads -->
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.28.0/prism.min.js" data-manual></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.28.0/plugins/autoloader/prism-autoloader.min.js"></script>
+    <script>
+    /*
+      Custom code from Emanote to selectively skip class="language-mermaid"
+    */
+    (function() {
+      var elements = document.querySelectorAll('pre > code[class*="language"]:not(.language-mermaid)');
+      for (var element of elements) {
+        Prism.highlightElement(element, false);
+      }
+    })();
+    </script>
   # Syntax highlighting using highlight.js
   highlightjs: |
     <!-- highlight.js -->

diff --git a/docs/tips/js/math.md b/docs/tips/js/math.md
@@ -29,4 +29,4 @@ page:
 ## Demo
 
 When $a \ne 0$, there are two solutions to $ax^2 + bx + c = 0$ and they are
-$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$
+$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$
diff --git a/docs/tips/js/mermaid.md b/docs/tips/js/mermaid.md
@@ -1,52 +1,72 @@
 ---
 page:
   headHtml: |
-    <snippet var="js.highlightjs" />
+    <snippet var="js.prism" />
     <snippet var="js.mermaid" />
 ---
 
 # Mermaid Diagrams
 
 [Mermaid](https://mermaid-js.github.io/mermaid/#/) lets you create diagrams and visualizations using text and code. You can define these diagrams in your Markdown code blocks. 
 
-1. Add the following to your `page.headHtml`, either in frontmatter or `index.yaml` (see [[yaml-config]])
-    ```yaml
-    page:
-      headHtml: |
-        <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
-        <script>
-          mermaid.initialize({startOnLoad:false});
-          mermaid.init(undefined,document.querySelectorAll(".mermaid"));
-        </script>
-    ```
-1. Add a code block with `mermaid` language
-    ~~~markdown
-    ```mermaid
-    %%{init: {'theme': 'forest', "flowchart" : { "curve" : "basis" } } }%%
-    graph TD;
-        A-->B;
-        A-->C;
-        B-->D;
-        C-->D;
-    ```
-    ~~~
-
-The result will be:
-
-```mermaid {.nohighlight}
+To enable this, add the following to your `page.headHtml`, either in frontmatter or `index.yaml` (see [[yaml-config]]):
+
+```yaml
+page:
+  headHtml: |
+    <snippet var="js.mermaid" />
+```
+
+The above alias will add Mermaid `<style>` and `<script>` tags based on Emanote's defaults.[^js.mermaid-source]
+
+[^js.mermaid-source]: Source code for the `<snippet var="js.mermaid" />` alias can be found in the <https://github.com/EmaApps/emanote/blob/master/default/index.yaml> file, under the `js:` YAML map
+
+## Example using Mermaid
+
+### Graph diagram
+
+~~~markdown
+```mermaid
 %%{init: {'theme': 'forest', "flowchart" : { "curve" : "basis" } } }%%
 graph TD;
     A-->B;
     A-->C;
     B-->D;
     C-->D;
 ```
+~~~
 
-Note that mermaid.js will have trouble operating with PrismJS [[syntax-highlighting]], but it works well with highlight.js (which this note uses).
+Results in:
 
-## More examples
+```mermaid
+%%{init: {'theme': 'forest', "flowchart" : { "curve" : "basis" } } }%%
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+```
 
-```mermaid {.nohighlight}
+### State diagram
+
+~~~markdown
+```mermaid
+stateDiagram
+    direction LR
+    [*] --> A
+    A --> B
+    B --> C
+    state B {
+      direction LR
+      a --> b
+    }
+    B --> D
+```
+~~~
+
+Results in:
+
+```mermaid
 stateDiagram
     direction LR
     [*] --> A
@@ -59,7 +79,10 @@ stateDiagram
     B --> D
 ```
 
-```mermaid {.nohighlight}
+### GANTT diagram
+
+~~~markdown
+```mermaid
 gantt
     dateFormat  YYYY-MM-DD
     title       Adding GANTT diagram functionality to mermaid
@@ -89,4 +112,39 @@ gantt
     Describe gantt syntax               :after doc1, 3d
     Add gantt diagram to demo page      :20h
     Add another diagram to demo page    :48h
-```
+```
+~~~
+
+Results in:
+
+```mermaid
+gantt
+    dateFormat  YYYY-MM-DD
+    title       Adding GANTT diagram functionality to mermaid
+    excludes    weekends
+    %% (`excludes` accepts specific dates in YYYY-MM-DD format, days of the week ("sunday") or "weekends", but not the word "weekdays".)
+
+    section A section
+    Completed task            :done,    des1, 2014-01-06,2014-01-08
+    Active task               :active,  des2, 2014-01-09, 3d
+    Future task               :         des3, after des2, 5d
+    Future task2              :         des4, after des3, 5d
+
+    section Critical tasks
+    Completed task in the critical line :crit, done, 2014-01-06,24h
+    Implement parser and jison          :crit, done, after des1, 2d
+    Create tests for parser             :crit, active, 3d
+    Future task in critical line        :crit, 5d
+    Create tests for renderer           :2d
+    Add to mermaid                      :1d
+
+    section Documentation
+    Describe gantt syntax               :active, a1, after des1, 3d
+    Add gantt diagram to demo page      :after a1  , 20h
+    Add another diagram to demo page    :doc1, after a1  , 48h
+
+    section Last section
+    Describe gantt syntax               :after doc1, 3d
+    Add gantt diagram to demo page      :20h
+    Add another diagram to demo page    :48h
+```
diff --git a/docs/tips/js/syntax-highlighting.md b/docs/tips/js/syntax-highlighting.md
@@ -5,19 +5,14 @@ In order to enable syntax highlighting, you must use a client-side JavaScript hi
 ```yaml
 page:
   headHtml: |
-    <link href="https://cdn.jsdelivr.net/npm/prismjs@1.23.0/themes/prism-tomorrow.css" rel="stylesheet" />
-    <script src="https://cdn.jsdelivr.net/combine/npm/prismjs@1.23.0/prism.min.js,npm/prismjs@1.23.0/plugins/autoloader/prism-autoloader.min.js"></script>
+    <snippet var="js.prism" />
 ```
 
-Or, using the alias from the default layer's `index.yaml`:
+The above alias will add PrismJS `<style>` and `<script>` tags, as well as additional script for supporting syntax highlighting updates after hot reload when running a live server via `emanote run`.[^js.prism-source]
 
-```yaml
-page:
-  headHtml: |
-    <snippet var="js.prism" />
-```
+[^js.prism-source]: Source code for the `<snippet var="js.prism" />` alias can be found in the <https://github.com/EmaApps/emanote/blob/master/default/index.yaml> file, under the `js:` YAML map
 
-An alias for highlight.js also exists, especially as highlight.js works better with [[mermaid]] than PrismJS:
+An alias for [highlight.js](https://highlightjs.org/) also exists, which can be useful especially if PrismJS and Mermaid keep on being troublesome together. The highlight.js package works better with Mermaid out of the box compared to PrismJS.
 
 ```yaml
 page:
@@ -27,7 +22,7 @@ page:
 
 Bear in mind that when using highlight.js you must manually add language support. Prism.js in contrast provides an autoload feature.
 
-## Example using PrismJS:
+## Example using PrismJS
 
 ### Python
 

diff --git a/emanote.cabal b/emanote.cabal
@@ -1,6 +1,6 @@
 cabal-version:      2.4
 name:               emanote
-version:            0.6.20.0
+version:            0.6.21.0
 license:            AGPL-3.0-only
 copyright:          2021 Sridhar Ratnakumar
 maintainer:         srid@srid.ca