Skip to content

feat: Add support for rendering mermaid diagrams - #62

Merged
larsks merged 1 commit into
CCI-MOC:mainfrom
larsks:feature/mermaid
Nov 20, 2026
Merged

larsks merged 1 commit into
CCI-MOC:mainfrom
larsks:feature/mermaid

Conversation

@larsks

@larsks larsks commented Nov 20, 2026

Copy link
Copy Markdown
Member

Github has support for rendering inline mermaid diagrams, so we should
support this on the published site as well. Like Github, this utilizes a
client-side renderer (diagrams are rendered when viewed, rather than
rendered to static files at build time).

@larsks

larsks commented Nov 20, 2026 •

Copy link
Copy Markdown
Member Author

An example of an ADR that requires this is in #61.

Comment thread _includes/layout.html
Comment on lines +54 to +57
<script src="/_assets/mermaid.min.js"></script>
<script>
mermaid.initialize({ startOnLoad: true });
</script>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mermaid.min.js is about 5.5 MB and is requested on every page, including the ones with no diagram. Optional: load it only when the page has one.

Suggested change
<script src="/_assets/mermaid.min.js"></script>
<script>
mermaid.initialize({ startOnLoad: true });
</script>
<script>
if (document.querySelector("pre.mermaid")) {
const script = document.createElement("script");
script.src = "/_assets/mermaid.min.js";
script.onload = () => {
mermaid.initialize({ startOnLoad: false });
mermaid.run();
};
document.head.appendChild(script);
}
</script>

@atyronesmith atyronesmith left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tested this branch with the ADR from #61 added: all three Mermaid diagrams render (headless Chrome).

One more optional thing, in a file this PR doesn't touch: the rendered diagram keeps the grey pre background from _assets/style.css. If you'd rather it sit on the page background:

pre.mermaid[data-processed] {
	background-color: transparent;
	padding: 0;
	text-align: center;
}

Github has support for rendering inline mermaid diagrams, so we should
support this on the published site as well. Like Github, this utilizes a
client-side renderer (diagrams are rendered when viewed, rather than
rendered to static files at build time).
@larsks

larsks commented Nov 20, 2026

Copy link
Copy Markdown
Member Author

One more optional thing...

That seems like a reasonable change; I've added it.

@larsks
larsks merged commit 780293b into CCI-MOC:main Nov 20, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants