Automate Markdown Render Verification and PDF Export From the CLI

AI agents can generate an impressive Markdown document in seconds. That does not mean the document is ready to publish.

A Mermaid diagram may contain valid-looking syntax that fails in the renderer. A document that reads well as source may behave differently when converted to PDF. The usual response is a manual loop: generate the file, paste it into a Markdown viewer, inspect it, return to the agent, make another revision, and repeat.

mdview.io can automate that loop from the CLI. Create a saved document once, update the same document on every iteration, verify it in the production PDF rendering environment, repair broken Mermaid diagrams, and export the final PDF only when the document passes.

[Diagram]

When This Workflow Is Useful

CLI verification is useful whenever Markdown is generated faster than a person can inspect every revision.

Common examples include:

A coding agent maintains an architecture document while changing a codebase.
CI generates release notes, migration reports, or deployment summaries.
An LLM produces Mermaid-heavy implementation plans.
A scheduled job publishes operational or compliance reports.
A team keeps one stable review URL for a document that changes frequently.
A release pipeline needs a PDF artifact and should fail if a diagram does not render.

The important distinction is that mdview.io becomes a verification target, not just a place to paste the finished result. Your generator writes Markdown; mdview.io checks what the rendered document will actually do.

Before You Start

Create an API token from the CLI Usage section of the mdview.io Dashboard. Store it in an environment variable instead of placing it directly in a script:

export MDVIEW_TOKEN="mdv1_..."

The examples also use curl and jq.

Step 1: Create the Document Once

Create a saved document and retain its ID:

MDVIEW_DOC_ID=$(
  curl -fsS -X POST https://mdview.io/api/documents \
    -H "Authorization: Bearer $MDVIEW_TOKEN" \
    -H "Content-Type: application/json" \
    --data '{"title":"Architecture","content":"# Architecture"}' \
  | jq -r '.id'
)

echo "$MDVIEW_DOC_ID"

Do this once. Subsequent revisions should update the same document instead of creating a new one. That preserves ownership, history, and any published review URL.

If teammates need a stable browser view, publish it once:

curl -fsS -X POST \
  "https://mdview.io/api/documents/$MDVIEW_DOC_ID/share" \
  -H "Authorization: Bearer $MDVIEW_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}' | jq

The returned shortId identifies the stable /s/... URL. Updating the saved document updates what reviewers see at that same address.

Step 2: Upload Each New Revision

Suppose an agent writes its latest output to docs/architecture.md. Upload that exact file with one command:

jq -Rs '{content: .}' docs/architecture.md \
  | curl -fsS -X PUT \
      "https://mdview.io/api/documents/$MDVIEW_DOC_ID" \
      -H "Authorization: Bearer $MDVIEW_TOKEN" \
      -H "Content-Type: application/json" \
      --data @- \
  | jq

The jq -Rs step safely converts the whole file into a JSON string, including newlines and quotes.

Step 3: Verify the Rendered Result

Run the full verification endpoint after an update:

curl -fsS \
  "https://mdview.io/api/documents/$MDVIEW_DOC_ID/verify" \
  -H "Authorization: Bearer $MDVIEW_TOKEN" \
  | tee verify.json \
  | jq

The verification runs in the same Chromium-based export environment used to create PDFs. A response looks like this:

{
  "renderable": false,
  "diagrams": { "total": 9, "failing": 1 },
  "tables": { "total": 3 },
  "failures": [
    {
      "index": 3,
      "fixable": true,
      "error": "Parse error on line 2",
      "snippet": "flowchart TD..."
    }
  ]
}

For a CI-friendly pass/fail result, let jq set the exit code:

curl -fsS \
  "https://mdview.io/api/documents/$MDVIEW_DOC_ID/verify" \
  -H "Authorization: Bearer $MDVIEW_TOKEN" \
  | jq -e '.renderable'

The command exits non-zero when the document contains a failing Mermaid diagram.

Step 4: Repair Broken Mermaid Diagrams

You can give the verification result back to the generating agent and ask it to revise the source. mdview.io can also run its render-validated Quick Fix pipeline over the failing diagrams:

curl -fsS -X POST \
  "https://mdview.io/api/documents/$MDVIEW_DOC_ID/fix/diagrams?apply=1" \
  -H "Authorization: Bearer $MDVIEW_TOKEN" \
  | jq

Without apply=1, the operation is a dry run and returns proposed repaired Markdown without changing the saved document.

Large repairs can reach the request deadline before every diagram has been processed. Repeat the request while the response contains "deadline_hit": true. Stop when renderable becomes true, or when deadline_hit is false and failures remain. The latter means at least one problem needs human or agent attention.

After applying a fix, fetch or otherwise reconcile the repaired source before allowing another generator update. Otherwise the next upload of the old local file will overwrite the server-side repair.

Step 5: Export the Verified PDF

Export only after verification succeeds:

curl -fsS \
  "https://mdview.io/api/documents/$MDVIEW_DOC_ID/export/pdf" \
  -H "Authorization: Bearer $MDVIEW_TOKEN" \
  -o architecture.pdf

The result is a vector PDF with selectable text. Free-plan PDF limits and branding still apply; Pro exports are clean and uncapped.

Only one Chromium export job runs at a time. If the API returns 429 export_busy, wait briefly and retry.

A Complete Verification Script

This minimal script updates a saved document, verifies it, and exports a PDF only when it passes:

#!/usr/bin/env bash
set -euo pipefail

: "${MDVIEW_TOKEN:?Set MDVIEW_TOKEN}"
: "${MDVIEW_DOC_ID:?Set MDVIEW_DOC_ID}"

MARKDOWN_FILE="${1:-docs/architecture.md}"
PDF_FILE="${2:-architecture.pdf}"
BASE="https://mdview.io/api/documents/$MDVIEW_DOC_ID"
AUTH="Authorization: Bearer $MDVIEW_TOKEN"

jq -Rs '{content: .}' "$MARKDOWN_FILE" \
  | curl -fsS -X PUT "$BASE" \
      -H "$AUTH" \
      -H "Content-Type: application/json" \
      --data @- > /dev/null

curl -fsS "$BASE/verify" -H "$AUTH" \
  | tee verify.json \
  | jq -e '.renderable' > /dev/null

curl -fsS "$BASE/export/pdf" -H "$AUTH" -o "$PDF_FILE"

echo "Verified and exported $PDF_FILE"

Run it like this:

./verify-markdown.sh docs/architecture.md build/architecture.pdf

Use the Cached Status for Polling

Full verification launches the export renderer. When a workflow only needs to ask whether the current content was already checked, use the cached status endpoint:

curl -fsS \
  "https://mdview.io/api/documents/$MDVIEW_DOC_ID/verify/status" \
  -H "Authorization: Bearer $MDVIEW_TOKEN" \
  | jq

"known": true means the status applies to the current document content. After an update, the endpoint returns "known": false until a full verification, repair, or PDF render refreshes the cache.

What “Renderable” Currently Means

The verdict is deliberately precise: renderable means every Mermaid diagram rendered in the production PDF environment. The response also reports table counts.

It is not yet a general visual-quality score. It does not promise that every page break is elegant, that a wide table is aesthetically ideal, or that headings never become orphans. Those checks still benefit from a human review of the exported PDF.

That boundary makes the result useful in automation. A pipeline gets a deterministic answer about silent diagram failures without pretending that all document design can be reduced to one boolean.

A Better Loop for AI-Generated Documentation

The traditional workflow treats rendering as the last manual step. The automated workflow moves it into the generation loop:

Generate or revise Markdown.
Update the same mdview.io document.
Verify it in the real export renderer.
Feed failures back to the agent or run Quick Fix.
Repeat until renderable is true.
Export the PDF and publish the stable review link.

That turns mdview.io into a verification surface for agents and CI—not merely a viewer opened after the work is supposedly finished.

Create an API token in your Dashboard, or see the complete endpoint reference and CI examples on the Agents page.