gstack/docs/howto-diagrams-and-formats.md

# How to put diagrams in your documents (and export beyond PDF)

This guide covers the diagram + multi-format engine that ships with
`/make-pdf` and `/diagram` (v1.58.0.0+). Everything here runs fully offline:
the mermaid and excalidraw runtimes are vendored in `lib/diagram-render/` and
loaded into a browser by `bin/gstack-render.ts`, which serves the bundle from
your machine on loopback for the length of one render. No CDN, no network at
render time. The browser is your Aside browser when it is open (macOS 15+);
when it is not — Linux, Windows, or the app closed — the same bundle renders in
gstack's own bundled browser, so it renders offline on every platform (PNGs
come out at 1x on the fallback, 2x through Aside).

## Render a mermaid diagram inside a PDF

Put a fence in your markdown. That's it.

````markdown
```mermaid title="Render pipeline"
graph LR
  A[markdown] --> B[prepass]
  B --> C[browser]
  C --> D[PDF]
```
````

```bash
make-pdf generate doc.md out.pdf
```

The fence renders as a **vector** diagram (crisp at any zoom, selectable
text), with the `title` as caption and accessibility label. The raw mermaid
source is preserved base64-encoded in a `data-gstack-source` attribute on the
figure for debugging and round-trips (an HTML comment would corrupt mermaid's
`-->` arrows). One catch: the fence must start at **column 0** — indented
fences (inside lists, for example) stay plain code blocks by design.

**Fence options** (space-separated in the info string):

| Option | Effect |
|---|---|
| `title="..."` | caption below the diagram + `aria-label` |
| `render=false` | keep the fence as a plain code block |
| `page=landscape` | force this diagram onto its own landscape page |
| `page=portrait` | veto auto-landscape for this diagram |

A fence that fails to parse renders as a loud red diagnostic block with the
parse error and source excerpt — your document still builds, and the error
is impossible to miss.

` ```excalidraw ` fences work the same way; the body is a full `.excalidraw`
scene file (what excalidraw.com saves with File → Save).

## Control image size and orientation

Local images are inlined automatically (relative paths resolve against the
markdown file) and **never truncate** — every image caps at the content box.
Oversized photos downscale to print resolution (300dpi at the content width),
so a phone photo doesn't bloat the document.

Image safety defaults: remote (http/https) images are **blocked with a
visible placeholder** unless you pass `--allow-network`. An image path that
resolves outside the markdown's directory (even through a symlink) still
inlines but warns loudly. Files over 64MB and non-regular files (fifos,
devices) degrade to a placeholder instead of hanging the render.

Per-image directives go immediately after the image:

```markdown
![quarterly chart](chart.png){width=full}
![logo](logo.png){width=2in}
![wide architecture](arch.png){page=landscape}
![wide screenshot](shot.png){page=portrait}
```

`width=` accepts `full`, a percentage (`50%`), or a dimension (`3in`, `8cm`,
`200px`). `page=` forces or vetoes a dedicated landscape page.

**Auto-landscape:** a wide, small-text, diagram-like image gets its own
vertically-centered landscape page automatically — inside an otherwise
portrait document. The heuristic is deliberately conservative (aspect ratio
≥ 1.8, intrinsic width over ~2.5x the content box, and a diagram-ish alt
word: diagram / architecture / flowchart / chart / graph). If it doesn't
fire when you want it, add `{page=landscape}`; if it fires when you don't,
add `{page=portrait}`.

## Export single-file HTML or Word

```bash
make-pdf generate doc.md out.html --to html
make-pdf generate doc.md out.docx --to docx
```

- **`--to html`** writes ONE self-contained file: diagrams as inline SVG,
  images as data URIs, zero network references (under the default offline
  posture — `--allow-network` deliberately keeps remote image tags live),
  plus a screen-reading layer (centered measure, padding). Email it, attach
  it, open it anywhere.
- **`--to docx`** is a content-fidelity export: headings, tables, code
  blocks, lists, and diagrams (embedded as 300dpi PNGs with alt text) carry
  over. Page-perfect layout does not — that's Word's job once it's open.

Heads-up: `--to` is the output format. `--format` is an old alias for
`--page-size` — different thing.

## Generate a diagram from English

```
/diagram make a flowchart of our deploy pipeline: build, test, canary, promote
```

The skill authors mermaid and emits a **triplet**:

| File | Use it for |
|---|---|
| `<slug>.mmd` | the source of truth — edit and re-render |
| `<slug>.excalidraw` | open at excalidraw.com (File → Open), move boxes, hand back |
| `<slug>.svg` / `<slug>.png` | docs, issues, READMEs, chat |

Flowcharts convert to fully editable excalidraw scenes. Other mermaid types
(sequence, state, gantt) render to SVG/PNG fine but skip the `.excalidraw`
artifact — an upstream converter limitation the skill will tell you about.

For documents, embed the `.mmd` source in your markdown instead of the PNG —
`/make-pdf` renders it as vector and the diagram stays editable forever.

## CI: fail loud instead of shipping placeholders

```bash
make-pdf generate docs.md --strict
```

Missing local images, blocked remote images, out-of-tree image reads (a path
or symlink resolving outside the markdown's directory), oversized files
(>64MB), and non-regular files all exit non-zero instead of degrading to a
warning or placeholder — for docs pipelines where a broken image should
break the build.

## Troubleshooting

- **"diagram-render bundle not found"** → run `bun run build:diagram-render`
  in the gstack repo, or re-run `./setup`.
- **Diagram renders but looks squished inline** → it's wide; give it room
  with `page=landscape` on the fence.
- **A two-row "racetrack" loop instead of one long line:** mermaid subgraph
  trick — top-level `flowchart TB`, two subgraphs with `direction LR` and
  `direction RL`, connect the *subgraphs* (node-level edges across subgraph
  boundaries silently disable `direction`).
- **"[remote image blocked]" placeholder** → remote images are never fetched
  by default (offline posture); the tag is replaced with a visible
  placeholder so the browser can't fetch it at print time either. Pass
  `--allow-network` to opt in.