[Feature] Add Mermaid diagram & image rendering support

[weijinglin]

Problem Type (问题类型)

others (please edit later)

Your Question (问题描述)

Feature Description (功能描述)

🎯 Problem Description

Current Situation:

• The project uses Mermaid syntax in documentation files (e.g., content/en/docs/quickstart/hugegraph-ai/quick_start.md) but these diagrams are not being rendered properly. The Mermaid code blocks are displayed as raw text instead of rendered diagrams.

• The images in the page quick_start can't be randering properly.

Specific Issues:

• 3 mermaid flowcharts in quick_start.md cannot be rendered properly

• Project architecture diagram in main doc also cannot be displayed

• Users can only see raw mermaid code, unable to understand project workflows and architecture

• Users can not see actually image which should be randered in documentation

[dosubot]

Hi @weijinglin! I'm Dosu and I’m helping the incubator-hugegraph-doc team.

To enable Mermaid diagram rendering in the HugeGraph documentation, add the following to your config.toml:

[params.mermaid]
enable = true

[markup]
  [markup.highlight]
    guessSyntax = false

This activates the built-in Docsy/Hugo support for Mermaid diagrams, so code blocks with mermaid will render as diagrams instead of raw text. The site already includes the necessary scripts and logic to load and initialize Mermaid.js when this config is present source.

For image issues: make sure all images referenced in documentation are stored locally (for example, in the static/ directory) rather than using remote URLs, which can break or be blocked source. Hosting all third-party resources (like Mermaid.js, images, fonts) locally also helps avoid CSP and privacy policy issues source.

After updating the configuration and image locations, rebuild the site and the diagrams/images should render as expected.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[imbajin]

@dosu

refer

• Mermaid graph with no parameters defined in hugo config results in 'Uncaught TypeError' docsy/docsy#1882 (comment)
• Auto activation of mermaid diagrams (via use of hugo render hook) docsy/docsy#990

[dosubot]

The Docsy bug described in docsy/docsy#1882 (where Mermaid rendering fails if [params.mermaid] is missing) does not affect HugeGraph docs as implemented. The theme logic in this repo only loads Mermaid scripts if .Site.Params.mermaid.enable is set, so the specific var params = null TypeError cannot occur here. Your Mermaid diagrams are not rendering because the required config is missing, not due to the upstream bug.

To fix Mermaid rendering, add this to your config.toml:

[params.mermaid]
enable = true

[markup]
  [markup.highlight]
    guessSyntax = false

This will enable Mermaid support and ensure diagrams render as expected. For future troubleshooting, consider tracking the Docsy theme version or commit in your repo for clarity on upstream changes and bug status.
Reference: scripts.html logic

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[Swadeep006]

hi @imbajin, is this issue still active? if not please assign it to me!

[imbajin]

hi @imbajin, is this issue still active? if not please assign it to me!

@Swadeep006 Hi, we have a temporary solution for the problem & it did work (refer: https://github.com/apache/incubator-hugegraph-doc/blob/master/themes/docsy/layouts/partials/hooks/head-end.html)

However it breaks the ASF's website rule: (⚠️ WARN)
https://whimsy.apache.org/pods.cgi/project/hugegraph

Found 1 external resources: {"ERROR Refused to load the script 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js' because it violates the following Content Security Policy directive: \"script-src 'self' data: blob: 'unsafe-inline' 'unsafe-eval' https://www.apachecon.com/ https://www.communityovercode.org/ https://*.apache.org/ https://apache.org/ https://*.scarf.sh/\". Note that 'script-src-elem' was not explicitly set, so 'script-src' is used as a fallback."=>1}

If u have any better solution for it, just let us know (assign to u now)

[Swadeep006]

Thank you for assigning this issue to me, I'll do my level best to clear this issue as soon as possible.

…

On Wed, 10 Dec, 2025, 1:25 pm imbajin, ***@***.***> wrote: Assigned #408 <#408> to @Swadeep006 <https://github.com/Swadeep006>. — Reply to this email directly, view it on GitHub <#408 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/A3FFMZF3LUL3VDNEOWZJA5D4A7GXXAVCNFSM6AAAAAB7TQVFLOVHI2DSMVQWIX3LMV45UABCJFZXG5LFIV3GK3TUJZXXI2LGNFRWC5DJN5XDWMRRGQ3TEMBZGMZDSMI> . You are receiving this because you were assigned.Message ID: ***@***.*** com>

[Swadeep006]

Hi @imbajin , thanks for pointing out the temporary solution and the CSP warning.
To avoid violating ASF website rules, I’ll work on a better approach!
Plan:

Remove the external CDN reference to Mermaid.
Self-host mermaid.min.js inside the HugeGraph docs repo (e.g., under static/js/).
Update head-end.html to load the script locally via 'self', which is allowed by the CSP.
Test that Mermaid diagrams render correctly without triggering any external resource warnings.

This should resolve the CSP violation and still enable Mermaid rendering.
I’ll proceed with this approach and update once I have a working solution.