## Host-neutral runtime bindings These assignments select stable paths only; they do not install anything or grant consent: ```bash GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}" GSTACK_ROOT="$GSTACK_HOME" GSTACK_STATE_ROOT="$GSTACK_HOME" GSTACK_BIN="$GSTACK_HOME/bin" BUN_CMD="$GSTACK_BIN/bun" B="$GSTACK_BIN/browse" D="$GSTACK_BIN/gstack-design" P="$GSTACK_BIN/make-pdf" ``` ## Optional runtime binding This workflow requires the `pdf` capability. Read `references/RUNTIME.md` before attempting installation. Pure planning or document review can continue without it. If unavailable, follow the consent-first `pdf` capability handoff in `references/RUNTIME.md`. It expands to `pdf`, `diagram`, and `browser`; do not guess a checkout-relative setup command. # make-pdf: publication-quality PDFs from markdown Turn `.md` files into PDFs that look like Faber & Faber essays: 1in margins, left-aligned body, Helvetica throughout, curly quotes and em dashes, optional cover page and clickable TOC, diagonal DRAFT watermark when you need it. Copy-paste from the PDF produces clean words, never "S a i l i n g". On Linux, install `fonts-liberation` for correct rendering — Helvetica and Arial aren't present by default, and Liberation Sans is the standard metric-compatible fallback. CI and Docker builds install it automatically via Dockerfile.ci. Emoji need a color-emoji font. macOS (Apple Color Emoji) and Windows (Segoe UI Emoji) ship one; most Linux distros and containers ship none, so emoji render as empty boxes (▯). the explicitly approved `pdf` runtime capability attempts to install `fonts-noto-color-emoji` on Linux (apt/dnf/pacman/apk, best-effort) and the print CSS falls back through Apple / Segoe / Noto emoji families. Set `GSTACK_SKIP_FONTS=1` to skip the install (CI without sudo, managed or offline machines). ## Core patterns ### 80% case — memo/letter One command, no flags. Gets a clean PDF with running header + page numbers + CONFIDENTIAL footer by default. ```bash $P generate letter.md # writes /tmp/letter.pdf $P generate letter.md letter.pdf # explicit output path ``` ### Publication mode — cover + TOC + chapter breaks ```bash $P generate --cover --toc --author "Garry Tan" --title "On Horizons" \ essay.md essay.pdf ``` Each top-level H1 in the markdown starts a new page. Disable with `--no-chapter-breaks` for memos that happen to have multiple H1s. ### Draft-stage watermark ```bash $P generate --watermark DRAFT memo.md draft.pdf ``` Diagonal 10% opacity DRAFT across every page. When the draft is final, drop the flag and regenerate. ### Fast iteration via preview ```bash $P preview essay.md ``` Renders HTML with the same print CSS and opens it in your browser. Refresh as you edit the markdown. Skip the PDF round trip until you're ready. ### Brand-free (no CONFIDENTIAL footer) ```bash $P generate --no-confidential memo.md memo.pdf ``` ### Diagrams — mermaid and excalidraw fences render as pictures A column-0 ` ```mermaid ` or ` ```excalidraw ` fence in the markdown renders as a crisp vector diagram, fully offline (vendored bundle, no CDN). Indented fences (inside lists) stay plain code blocks by design. A broken fence produces a visible red diagnostic block with the parse error — never silent raw code. Fence info-string options: ``` ```mermaid title="Auth flow" ← caption + aria-label ```mermaid render=false ← keep it as a code block (today's behavior) ```mermaid page=landscape ← force this diagram onto a landscape page ```mermaid page=portrait ← veto auto-landscape for this diagram ``` A ` ```excalidraw ` fence contains a full .excalidraw scene file (what excalidraw.com saves). Authoring NEW diagrams from English is `$design --mode Generate --module diagram`'s job — it emits an editable triplet (source, .excalidraw, SVG/PNG) and pairs with this skill: embed the `.mmd` source in your markdown, not the PNG. ### Images — scaled right, never truncated Local images inline automatically (relative paths resolve against the markdown file). Every image caps at the content box — zero truncation, ever. Oversized photos downscale to print resolution (300dpi) so payloads stay small with no visible quality loss. Remote (http/https) images are **blocked with a visible placeholder** by default — offline posture; pass `--allow-network` to fetch them. An image that resolves outside the markdown's directory (even via symlink) still inlines, but warns loudly; `--strict` makes it fatal. Files over 64MB or non-regular files (fifos, devices) degrade to a placeholder instead of hanging the run. Per-image directives, written immediately after the image: ``` {width=full} ← stretch to content-box width {width=50%} ← percentage or 3in/8cm/200px {page=landscape} ← give it its own landscape page {page=portrait} ← veto auto-landscape ``` Wide, small-text diagram images auto-promote to their own landscape page (conservative: aspect ≥ 1.8, width over ~2.5x the content box, AND a diagram-ish alt word — diagram/architecture/flowchart/chart/graph). The promoted page is vertically centered. When the heuristic guesses wrong, `{page=portrait}` vetoes it; false negatives just need `{page=landscape}`. ### Other formats — single-file HTML and Word ```bash $P generate readme.md out.html --to html # ONE self-contained file: inline # SVG diagrams, data-URI images, # zero network refs, screen-readable $P generate readme.md out.docx --to docx # Word: content fidelity (headings, # tables, code, diagrams as PNG) — # layout is Word's, not ours ``` `--to` is the output format. `--format` is something else entirely (a `--page-size` alias) — don't confuse them. ### CI mode — fail loud on missing assets ```bash $P generate docs.md --strict # missing, remote, out-of-tree, oversized, # and non-regular-file images exit non-zero # instead of warn + placeholder ``` ## Common flags ``` Page layout: --margins 1in (default) | 72pt | 2.54cm | 25mm --page-size letter|a4|legal Structure: --cover Cover page (title, author, date, hairline rule) --toc Clickable TOC with page numbers --no-chapter-breaks Don't start a new page at every H1 Branding: --watermark Diagonal watermark ("DRAFT", "CONFIDENTIAL") --header-template Custom running header --footer-template Custom footer (mutex with --page-numbers) --no-confidential Suppress the CONFIDENTIAL right-footer Output: --to pdf|html|docx Output format (default: pdf). html = single self-contained file; docx = content fidelity. --strict Missing, remote, out-of-tree, oversized, or non-regular-file images fail the run (CI mode). --page-numbers "N of M" footer (default on) --tagged Accessible PDF (default on) --outline PDF bookmarks from headings (default on) --quiet Suppress progress on stderr --verbose Per-stage timings Network: --allow-network Fetch external images. Off by default: remote images render as a visible blocked placeholder (no tracking pixels fetch at print time). Metadata: --title "..." Document title (defaults to first H1) --author "..." Author for cover + PDF metadata --date "..." Date for cover (defaults to today) ``` ## When Claude should run it Watch for markdown-to-PDF intent. Any of these patterns → run `$P generate`: - "Can you make this markdown a PDF" - "Export it as a PDF" - "Turn this letter into a PDF" - "I need a PDF of the essay" - "Print this as a PDF for me" If the user has a `.md` file open and says "make it look nice", propose `$P generate --cover --toc` and ask before running. ## Debugging - Output looks empty / blank → check browse daemon is running: `$B status`. - Fragmented text on copy-paste → highlight.js output (Phase 4). Retry with `--no-syntax` once that flag exists. For now, remove fenced code blocks and regenerate. - Paged.js timeout → probably no headings in the markdown. Drop `--toc`. - "[remote image blocked]" placeholder in the output → add `--allow-network` (understand you're giving the markdown file permission to fetch from its image URLs). - Generated PDF too tall/wide → `--page-size a4` or `--margins 0.75in`. ## Output contract ``` stdout: /tmp/letter.pdf ← just the path, one line stderr: Rendering HTML... ← progress spinner (unless --quiet) Generating PDF... Done in 1.5s. 43 words · 22KB · /tmp/letter.pdf exit code: 0 success / 1 bad args / 2 render error / 3 Paged.js timeout / 4 browse unavailable ``` Capture the path: `PDF=$($P generate letter.md)` — then use `$PDF`. ## Upstream judgment port: PR #679 [Match the user language](https://github.com/garrytan/gstack/pull/679) ### User-language rule Write questions, progress updates, reports, and artifacts in the language used by the user. Source material, code identifiers, commands, and quotations may remain in their original language when translating them would reduce accuracy.