Displaying Mermaid diagrams on GitHub Pages#

04 January 2026

Mermaid charts show up fine in GitHub README files and other Markdown files when viewed inside their GitHub repos. The charts don’t show up when the same files are published to GitHub Pages sites.

Steps#

The following steps are relevant only if you use your own CSS files for your GitHub Pages site. If you’re using a theme, the steps are different (and not documented here).

In the _config.yml file of your repo, add the following code block:

kramdown:
  input: GFM
  syntax_highlighter_opts:
    disable: true

Create an assets/js/mermaid-fix.js file with the following content:

document.addEventListener("DOMContentLoaded", () => {
  document.querySelectorAll("pre > code.language-mermaid").forEach(block => {
    const parent = block.parentElement;
    const container = document.createElement("div");
    container.className = "mermaid";
    container.textContent = block.textContent;
    parent.replaceWith(container);
  });
});

In all of the template files that are used by your Markdown files, add the following code in the <head>:

  <script src="{{ '/assets/js/mermaid-fix.js' | relative_url }}"></script>

  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: true, theme: "default" });
  </script>

Check in the files. After the GitHub Pages build is over, you should be able to see a rendered version of your Mermaid diagram.

Displaying Mermaid diagrams on GitHub Pages

On this page

Displaying Mermaid diagrams on GitHub Pages#

Steps#