Embed a diagram in Jekyll: kramdown passes your iframe through, even on GitHub Pages

Drop an iframe or an img tag into a Jekyll post and kramdown emits it unchanged; raw HTML pass-through is the default, no flag to flip. That is the opposite of Hugo, where goldmark strips HTML until you opt in, and it means the interactive embed works on a stock Jekyll site: an iframe pointing at an embeddable diagram page gives readers pan and zoom in place.

One kramdown detail worth knowing when you mix HTML and markdown: block-level HTML elements do not process markdown inside them unless the element carries markdown="1". For a plain iframe or image embed this never comes up, but it explains the classic surprise of markdown syntax going literal inside a div.

<!-- In any post or page, works on a stock Jekyll config: -->
<iframe src="https://datadef.io/embed/my-platform-a1b2c3d4"
        title="Platform architecture" width="100%" height="560"
        style="border:none"></iframe>

<!-- Or the markdown image form: -->
![Platform architecture](https://datadef.io/api/embed/my-platform-a1b2c3d4)

GitHub Pages builds Jekyll sites in safe mode, which disables custom plugins outside its allowlisted set. That constraint is real for themes and generators, and irrelevant for embeds: safe mode does not sanitize the HTML in your markdown. Your iframe and your image URL survive a Pages build exactly as written.

The contrast worth naming: the README of the same repository is rendered by GitHub with a strict sanitizer that removes iframes, while the Pages site built from that repository renders them fine. Same host, different pipelines, covered from the README side in embed diagrams in a GitHub README.

Sites with many diagrams usually wrap the markup once: a file in _includes taking a src and caption parameter, invoked with the include tag. Includes run in safe mode, since they are templates rather than plugins, so this pattern works on GitHub Pages.

It also gives you one place to change presentation later, add lazy loading, a border, a link to the full diagram, without touching every post that embeds one.

<!-- _includes/diagram.html -->
<figure class="diagram">
  <img src="{{ include.src }}" alt="{{ include.alt }}" loading="lazy">
  <figcaption>{{ include.caption }}</figcaption>
</figure>

<!-- Usage in a post: -->
{% include diagram.html
   src="https://datadef.io/api/embed/my-platform-a1b2c3d4"
   alt="Platform architecture"
   caption="Current platform architecture, rendered live." %}

Project pages on GitHub Pages serve under a subpath, and site.baseurl exists to prefix site-relative links so they survive that. The filters that apply it, relative_url and absolute_url, act on paths you feed them; an absolute external URL written directly in markup is never rewritten. A live diagram URL therefore behaves identically on a user site, a project page under a subpath, and a custom domain.

This is one of the quiet advantages of the external image over a committed asset: committed images are exactly the links baseurl migrations break.

Jekyll builds freeze your prose at deploy time, but the external image is fetched at view time, so an edited diagram reaches published pages within minutes, five minute cache lifetime, no rebuild. What remains is editing the diagram when the system changes: the Datadef MCP server (registry name io.datadef/mcp) lets an agent with repository access do it from what it reads in the code, after a merge, in CI, or on request. Datadef does not watch repositories; the trigger is an agent call or CI command. The loop needs an agent API key, available on the paid plans. The workflow around it is in keep your README in sync with code.

The visibility limit is the same as everywhere: embed URLs exist only while the project is shared public, and 404 when it goes private. For public docs sites this is rarely a constraint, but confidential internals do not belong in the shared diagram.

• Embed diagrams in Markdown
• Embed diagrams in Hugo
• Embed diagrams in a GitHub README
• Keep your README in sync with code