Work has been busy, but I found some time to update one of my open source tools, md-to-conf.
md-to-conf is a tool forked from RittmanMead that I continue to modify to push Markdown documentation into Confluence. It handles the boring parts of that workflow — converting fenced code blocks, uploading images as attachments, wiring up internal links — so the rest of the pipeline can stay out of it.
The 1.1.x releases focused on attachment handling and GitHub-flavored alert support. Version 1.2.0 ships something I’ve had on the backlog for a while: native Mermaid diagram rendering, with a fallback strategy that works out of the box in CI/CD pipelines that don’t have npm installed.
Here’s what changed.
What Was in 1.1.2
Before getting into the new stuff, a quick recap of where 1.1.2 left things:
– Attachment handling was overhauled to use Confluence’s REST API v2 endpoints consistently. The v1 attachment paths had been causing subtle issues, especially around upload confirmation and 404 handling.
– GitHub alert boxes landed in 1.1.0 — [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], and [!CAUTION] now convert to proper Confluence info/tip/warning/note macros. The 1.1.1 and 1.1.2 cycle stabilized those, fixed a ReDoS vulnerability in the alert regex, and improved test coverage significantly.
– Folder ancestor support was added, so pages can be organized under a folder hierarchy when published.
– A handful of SonarQube issues were resolved — mostly type annotation hygiene and regex security flags.
Solid maintenance work. The goal for that cycle was making the tool reliably boring to operate, which is the right goal.
What’s New in 1.2.0
Mermaid Diagram Rendering
The headline feature: pass --mermaid and any fenced Mermaid code block in your Markdown gets rendered to a PNG and uploaded as an attachment before the page is published.
md-to-conf architecture.md MY_SPACE --mermaidYour Markdown stays clean and human-readable:
```mermaid
graph TD
A[Developer] -->|git push| B[CI Pipeline]
B -->|md-to-conf| C[Confluence Page]
C --> D[Team reads it]
D -->|eventually| E[Documentation is current]
```And what lands in Confluence is an actual rendered diagram, not a gray code block that people have to squint at.
The Two-Strategy Rendering Pipeline
This is the design decision I spent the most time on. A lot of tools that promise Mermaid support require `mmdc` (the Mermaid CLI) to be on the PATH, which means coordinating an npm install in every environment that runs the tool. That’s fine for a developer workstation. It’s annoying for a CI agent, and it’s the first thing people hit when they try to use these features in automation.
md-to-conf 1.2.0 tries two strategies, in order:
Strategy 1: Local mmdc CLI
If mmdc is on the PATH, it renders the diagram locally. No network required. Fastest option, highest quality output.
npm install -g @mermaid-js/mermaid-cliStrategy 2: mermaid.ink public API
If mmdc isn’t found, the tool automatically falls back to mermaid.ink — a public rendering API that takes Base64-encoded diagram source and returns a PNG. It just needs outbound HTTPS access, which basically every pipeline already has.
No npm. No configuration. It works.
The fallback behavior is transparent — you don’t have to opt into it or configure anything. If mmdc is available, it’s used. If not, mermaid.ink picks it up silently. If both fail (offline environment, diagram syntax error), a warning is logged and the original code block is left intact. Nothing breaks.
For CI/CD pipelines, the practical implication is:
> --mermaid works out of the box with no additional tooling.
That’s the goal. You shouldn’t need to install anything extra just to get diagrams into your documentation.
Why This Matters
The reason I wanted this feature in the first place: architecture documentation that includes diagrams. The workflow without it was always one of:
1. Screenshot a diagram from some external tool, upload it manually, pray it stays current
2. Write the diagram in Mermaid, render it somewhere else, copy the image, upload it… manually
3. Just skip the diagram entirely (this one wins more often than it should)
Having --mermaid as a flag in the same command that handles the rest of the publish step closes that loop. The source of truth is the Markdown file, the rendered output is the Confluence page, and there’s nothing manual in between.
Upgrade Notes
The --mermaid flag is opt-in. Existing pipelines will continue to work without any changes. If you want diagram rendering, add the flag.
# Before
md-to-conf my-doc.md MY_SPACE
# After, with Mermaid support
md-to-conf my-doc.md MY_SPACE --mermaidIf you want the local CLI for better quality or offline environments:
npm install -g @mermaid-js/mermaid-cliWhat I Learned
1. Two strategies beat one. The mmdc + mermaid.ink combination covers the two real environments this tool runs in: developer machines (mmdc likely available) and CI agents (probably not). Building the fallback in from day one avoids the “works on my machine” problem that would otherwise become a support issue.
2. Opt-in is the right default for new features. `–mermaid` doesn’t change existing behavior. I’ve learned to be conservative with flags — it’s much easier to add behavior behind a flag than to explain to people why their pipeline broke after an upgrade.
3. Fail gracefully and loudly. If a diagram can’t render, the code block stays intact and a warning is logged. The page publish doesn’t fail. That’s the right tradeoff — a partially rendered page is better than a broken pipeline, and the warning gives people something to act on.
4. Build on solid foundations. The mermaid images are written to a temp directory, uploaded as attachments, and wired into the page HTML. The 1.1.x attachment handling work — getting the v2 API paths right, fixing 404 handling — meant this feature had a clean surface to build on. That kind of maintenance investment pays off when you add something new.
The full changelog is in the repository. If you’re running md-to-conf and have Mermaid diagrams sitting unused in your Markdown files, give 1.2.0 a try and let me know how it goes.