aaranxu / adidoks

AdiDoks is a mordern documentation theme, which is a port of the Hugo theme Doks for Zola.
https://adidoks.org
MIT License
220 stars 80 forks source link

add support for mermaid.js diagrams #19

Open mscno opened 2 years ago

mscno commented 2 years ago

It would be a great feature to enable native support of mermaid.js diagram blocks. This would enable users to write diagrams as code and keep them inside the markdown files.

It is simple enough to include the mermaid.js dependency and include a raw div with mermaid syntax, but we may need some more tweaking to enable parsing of code blocks.

// Raw div block - these can be picked up by default by mermaid.js just by including the dependency.
<div class="mermaid">
graph LR
    A --- B
    B-->C[fa:fa-ban forbidden]
    B-->D(fa:fa-spinner);
</div>

// Code block - these are not picked up by mermaid.js, since they are rendered as <pre><code> blocks.
```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

By default the markdown renderer just renders a mermaid block as a standard code block.
```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

I dont know if mermaid rendering can be enabled without changing the core zola rendering engine, but it seems like it was achieved by Docsy (a hugo docuementation theme) without changing the core hugo markdown engine, and using jquery instead: https://github.com/google/docsy/blob/d4b214c8e5c7fabf9e83b58a9df2281be242d5b4/assets/js/mermaid.js

AlexMikhalev commented 2 years ago

:+1: very useful feature.

aaranxu commented 2 years ago

This is a good suggestion. I will add it soon.

AlexMikhalev commented 2 years ago

Good. Use case I have in mind diagram with clickable links:

graph LR;

QuickStart(Quick Start) --> CmdPalette(Command<BR>Palette);
QuickStart --> CreateNotes("Create notes");
QuickStart --> InternalLinks("Internal Links");

click CreateNotes "/Create notes";
click CmdPalette "/Command palette";
click InternalLinks "/Internal link";