Docs Automation Guide

Diagrams in a docs-as-code pipeline: keeping review, versions and CI

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

Docs as code is not really about markdown. It is about four properties: changes get reviewed, pages are versioned with the release they describe, checks run in CI, and the source of truth sits in the repository. Prose keeps all four. The question this page answers is how a diagram keeps them too, once you accept that the picture itself is not going to live in the repository as text.

Try it free
7 min readFor teams whose docs pipeline is solid everywhere except the picture

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

150/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Assume the trade-off is settled

The choice between a committed binary, a text DSL, and a hosted canvas is worked through in the limits of diagrams as code, including where the node count stops being kind to an auto-layout engine. That page argues the trade; this one starts after it, from the position most teams land on: text formats for the small and disposable, a maintained canvas for the diagram the whole team navigates by.

Taking that position feels like leaving the pipeline. It reads as though the picture has moved to a website, review no longer applies to it, and the docs for version 3 will show whatever the canvas looks like today. Each of those is addressable, and the rest of this page is how.

What actually goes in the page: one markdown line

A live embed is a single markdown image line pointing at a URL that renders the current state of the canvas. It behaves like a committed image in the docs page (any markdown renderer shows it, viewers need no account) and like generated content underneath (the canvas moves, the page follows). Every static site generator already handles it, because to the build it is an image with an absolute address.

That moves the review question from is this picture stale, which a human cannot answer from a diff, to is the source correct, which is a question the pipeline was already good at. The docs page carries no binary, no build-time renderer dependency, and no expiring third-party link.

When a frozen still is genuinely needed, a slide or an attachment, the canvas exports as PNG or JPEG. Freezing becomes a deliberate act with a date attached rather than the default state of every picture in the docs.

## Architecture

![Platform architecture](https://datadef.io/api/embed/your-project-slug)

The image above renders the current diagram. It updates when the canvas does.

Keeping the docs-as-code properties you actually wanted

Versioning by release is preserved. One repository connection can back several diagrams, so a diagram tracking a release tag sits alongside one tracking main, and the docs for v3 embed the v3 picture while the docs for main embed main.

Generated prose stays plain markdown you can commit, so the architecture doc lives in the repository like every other page and goes through the same review. The diagram section inside it is composed deterministically rather than written by a model, so the embed URL in a committed doc is real or explicitly absent.

And regeneration is scriptable. The MCP server exposes two repository tools, repo_status and repo_refresh, so a coding agent or a CI step can trigger a re-sync once an infrastructure change merges instead of waiting for the next daily pass.

Triggering the refresh from the pipeline

The daily pass is a floor rather than a ceiling. When an infrastructure change merges at ten in the morning, waiting until tomorrow for the docs site to agree is a choice, and it is an avoidable one. Both repository tools take a single project_id, and the endpoint speaks plain JSON-RPC over HTTPS, so the caller does not have to be an agent: a curl step in a workflow does the job.

Three properties make this cheap enough to run on every merge to main. A refresh whose tracked commit has not moved answers in a couple of seconds and changes nothing. A refresh whose commit did move but whose structure did not is stopped by the fingerprint check before any generation happens. What is left is the case you actually wanted, where the structure changed, the diagram and the architecture document are rebuilt, and the page embedding them is right before the next person opens it.

Two limits are worth knowing before wiring up the workflow below. Refreshes are capped at ten per ten minutes per account, which is generous for a merge hook and deliberately not generous for a loop across every repository you own. And repo_refresh regenerates from the repository, so it is the same operation as the daily sync rather than a gentler one: nodes moved by hand keep their positions, but content derived from the source is rebuilt.

# .github/workflows/architecture-docs.yml
name: refresh architecture docs
on:
  push:
    branches: [main]
    paths: ["infra/**", "charts/**", ".github/workflows/**"]

jobs:
  refresh:
    runs-on: ubuntu-latest
    env:
      DATADEF_KEY: ${{ secrets.DATADEF_KEY }}
      PROJECT_ID: ${{ vars.DATADEF_PROJECT_ID }}
    steps:
      - name: re-sync the diagram and the architecture doc
        run: |
          curl -sS https://datadef.io/mcp \
            -H "Authorization: Bearer $DATADEF_KEY" \
            -H "Content-Type: application/json" \
            -H "Accept: application/json, text/event-stream" \
            -d @- <<JSON
          {"jsonrpc":"2.0","id":1,"method":"tools/call",
           "params":{"name":"repo_refresh",
                     "arguments":{"project_id":"$PROJECT_ID"}}}
          JSON

FAQ

If the diagram is not in the repository, what does review cover?

The source it comes from. A diagram generated from the tracked branch changes when the infrastructure or service code changes, so the pull request that moves the architecture is the review, and the picture follows it. The prose architecture document generated alongside is plain markdown and goes through review like any other page.

What still lives in the repository under this arrangement?

Everything except the rendered picture: the prose pages, the generated architecture document, and the one markdown image line that points at the diagram. There is no binary asset, no build-time renderer dependency, and nothing for a docs build to install.

How does a live embed work in a static docs site?

It is a standard markdown image line pointing at a URL that renders the current canvas, so any renderer that shows images shows it, including static site generators. No plugin, no build-time renderer, and readers do not need an account to view it.

Can different documentation versions show different diagrams?

Yes. One repository connection can back several diagrams, for example one tracking a release tag and one tracking the main branch. Each has its own embed URL, so versioned docs pages can point at the picture that matches their version.

Can regeneration be triggered from CI instead of waiting a day?

Yes. Two MCP tools, repo_status and repo_refresh, each take a project_id, and the endpoint accepts plain JSON-RPC over HTTPS with a bearer key, so a curl step in a workflow is enough. Refreshes are capped at ten per ten minutes per account. The daily pass stays as the fallback and skips work entirely when the tracked commit has not moved.