Software Coding in WordPress Blog Posts Deserves Better: Syntax Highlighting, Live Links to GitHub, and Mermaid Diagrams

Good code in a WordPress post needs syntax highlighting for readability, live links or embeds that pull snippets from GitHub so the repository stays the source of truth, and Mermaid diagrams written as text instead of images. WordPress supports these through plugins and blocks, though few tools combine all three well today.

Most technical blogs treat code as an afterthought, pasting a block of monospaced text into a post, perhaps adding a screenshot of an IDE, and leaving the reader to guess which version of the repository it came from, whether it still compiles, and how it fits into the wider system. This post sets out what good code markup looks like in a blog post, why the source of truth for any snippet should be the repository rather than the post, why architecture should be drawn as text rather than as images, and then answers the practical question that prompted it: does anything in the WordPress ecosystem actually support all three of these properly today?

1. What good code markup actually means

Good code markup starts with the assumption that a reader will copy what you show them and run it, so every block should declare its language explicitly, render with real syntax highlighting rather than a theme’s default grey box, preserve indentation exactly, offer a copy button that copies the code and nothing else, and avoid line numbers being swept up into the clipboard. Screenshots of code fail every one of these tests, because they cannot be copied, searched, read by a screen reader, or indexed, and they silently go stale the moment the underlying file changes.

The second requirement is that highlighting should, where possible, happen on the server when the post is saved or rendered rather than in the reader’s browser, because a page that ships a large JavaScript highlighter to colour twenty lines of Python is paying a performance cost on every view, and because server rendered markup also survives RSS readers, email newsletters and AI summarisers that never execute your scripts. The third requirement is restraint: a snippet should show the smallest piece of code that makes the point, with line highlighting used to draw the eye to the two or three lines that matter, and with a link that lets the curious reader see the full file in context.

def backoff(attempt: int, base: float = 0.1, cap: float = 10.0) -> float:
    # Full jitter: spread retries so clients do not synchronise
    return random.uniform(0, min(cap, base * (2 ** attempt)))

That last point is where most posts fall down, because the link is usually either missing or points at a branch that has moved on since the post was written.

2. Linking code in a post back to the GitHub repository

The repository should be the source of truth for any code that appears in a post, and the post should say exactly which version it is showing. GitHub makes this straightforward: selecting a range of lines in a file gives a URL ending in a fragment such as #L15-L29, and pressing y on a file page rewrites the URL from a branch name to the full commit SHA, so the link is a permanent reference to those exact lines at that exact moment. A permalink to a line range, posted in an issue or pull request, is rendered by GitHub itself as an embedded code snippet, which is a good model for what a blog should do.

There are three reasonable ways to bring that into a post, and each makes a different trade. The first is to paste the snippet into a highlighted code block and add a caption linking to the pinned permalink, which is fast, renders on the server, works in every feed reader, and is honest about its age, but which will never update if the code changes. The second is to embed the file live from GitHub at view time using a script, which is always current if you point it at a branch, but which drifts silently when lines are added above your range, so the embed starts showing the wrong code with no warning. The third, and the one I would argue is correct for anything that matters, is to fetch the snippet at publish time from a pinned commit, render and cache it on the server, and show a small footer that names the repository, the file path and the short SHA, with a link to the same lines on GitHub and an optional note when the default branch has moved on.

The line drift problem in the second approach is worth dwelling on, because it is the reason live embeds are less useful than they first appear. The more robust fix is to anchor snippets to named regions in the source rather than to line numbers, using comment markers such as // region: retry-policy and // endregion, so that the post asks for a named block of code and keeps working as the file around it changes. Documentation tools have done this for years, and the same idea has been raised against at least one of the popular GitHub embed services, but it is still rare in blogging tools.

3. Diagrams as code with Mermaid

The same argument that applies to code applies to architecture diagrams. A diagram exported as a PNG from a drawing tool cannot be diffed, reviewed in a pull request, searched, or updated without finding the original file, and in practice it is redrawn from scratch or left wrong. Mermaid describes flowcharts, sequence diagrams, state machines, entity relationships and Gantt charts as plain text that sits in a fenced code block, renders natively on GitHub, and can live in the same repository as the code it describes, which means the diagram in the post and the diagram in the README can be the same file.

sequenceDiagram
    participant Author
    participant Repo as GitHub repo
    participant Blog as WordPress
    participant Reader
    Author->>Repo: commit code and diagram source
    Author->>Blog: publish post referencing file, region and SHA
    Blog->>Repo: fetch snippet at publish time
    Blog-->>Blog: highlight and cache on the server
    Reader->>Blog: view post
    Blog-->>Reader: highlighted code, rendered diagram, link to exact lines

The portable pattern, which the F# documentation tooling describes well, is to keep the diagram as an ordinary fenced block tagged mermaid so that GitHub and any Markdown viewer render it, and then let the blog promote that block into a rendered diagram when the page loads. Done properly, the blog should also load the Mermaid library only on pages that actually contain a diagram, give each diagram a text caption for readers who cannot see it, and respect the reader’s dark mode preference rather than drawing a bright white rectangle in the middle of a dark page.

4. Does anyone support this in WordPress?

The honest answer is that every individual piece exists, but I could not find a single, actively maintained plugin that handles all three together in the block editor, and several of the pieces that do exist are showing their age.

For syntax highlighting the ecosystem is healthy. Code Block Pro uses the same rendering engine as VS Code, supports line highlighting and a copy button, and is tested against WordPress 7.0, although its themes are set per block rather than site wide. Syntax-highlighting Code Block takes a different approach, extending the core Code block with server side highlighting and loading no external scripts, which suits the performance argument above. Enlighter, Prismatic and Highlighting Code Block are all credible alternatives depending on whether you favour the classic or block editor.

Linking to GitHub is where support thins out sharply. GetGit offers a shortcode that pulls a file from a public repository with start and end lines and basic highlighting, but its directory listing warns that it has not been tested with the last three major WordPress releases. WP Github Gist supports line ranges too, but relies on the external gist-it service to fetch files, so it is only as reliable as that service. Outside WordPress, emgithub lets you embed a file or a sliced line range from a permalink via a script or iframe, fetching and highlighting in the reader’s browser, and its own documentation suggests self hosting a fork in case the public service is compromised or changes, which tells you something about the trust model of loading third party script into your posts. None of these fetch at publish time, cache on the server, or support named regions.

Mermaid support is similarly fragmented. WP Mermaid is the best known option, and sensibly loads the library only on posts that use it, but it also carries the untested warning and its changelog shows it bundling Mermaid 9.4.3, while current Mermaid is on version 11. Newer entrants such as CanaryBlue Diagrams for Mermaid, which offers live preview in the editor without calling an external rendering service, and PlusMagi Blocks, which adds syntax error detection, are promising but very young. WP Githuber MD comes closest to an all in one answer, combining a Markdown editor with Prism highlighting and Mermaid, but it replaces the editing model entirely, stores Markdown in a separate column, recommends that you only adopt it on a new blog, and asks you to disable other Markdown plugins, which is a heavy price for an established site.

5. What the complete solution would look like

Putting the pieces together, the plugin that does not yet exist would provide a single block where an author pastes a GitHub permalink, or a repository, file path and named region, and the plugin fetches the code at publish time from a pinned commit, highlights it on the server with VS Code quality grammars, caches the result, and renders a footer linking back to the exact lines, with an optional warning in the editor when the default branch has diverged from the pinned commit. The same plugin would render fenced Mermaid blocks with a current version of the library, loaded only where needed, themed for light and dark mode, and with captions for accessibility, and it would accept Markdown pasted from a README without forcing the whole site onto a Markdown editor.

That combination matters because it changes the relationship between a blog and the code it describes. Instead of a post being a frozen copy that decays from the day it is published, it becomes a view onto a specific, verifiable version of a real repository, with diagrams that are versioned alongside the code they explain, and that is a standard technical writing on WordPress should be held to.

References

1. Code Block Pro: https://wordpress.org/plugins/code-block-pro/
2. Syntax-highlighting Code Block and other highlighters, Speckyboy round up: https://speckyboy.com/free-wordpress-plugin-display-edit-code/
3. GetGit: https://wordpress.org/plugins/getgit/
4. WP Github Gist: https://github.com/sudar/wp-github-gist
5. emgithub: https://github.com/yusanshi/emgithub
6. emgithub issue on marker based embedding: https://github.com/yusanshi/emgithub/issues/27
7. WP Mermaid: https://wordpress.org/plugins/wp-mermaid/
8. CanaryBlue Diagrams for Mermaid: https://wordpress.org/plugins/canaryblue-diagrams-for-mermaid/
9. WP Githuber MD: https://github.com/terrylinooo/githuber-md
10. FSharp.Formatting Mermaid pattern: https://fsprojects.github.io/FSharp.Formatting/mermaid.html