Docs: build-time mermaid + tmux-layout diagram rendering

.github/workflows/docs.yml

@@ -56,6 +56,38 @@ jobs:
         if: env.PUBLISH == 'true'
         uses: extractions/setup-just@v4
 
+      - name: Set up Node.js
+        if: env.PUBLISH == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Set up pnpm
+        if: env.PUBLISH == 'true'
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+          run_install: false
+
+      - name: Cache Puppeteer browser
+        if: env.PUBLISH == 'true'
+        uses: actions/cache@v5
+        with:
+          path: ~/.cache/puppeteer
+          key: puppeteer-${{ runner.os }}-${{ hashFiles('docs/pnpm-lock.yaml') }}
+          restore-keys: |
+            puppeteer-${{ runner.os }}-
+
+      # Diagrams (docs/_ext/mermaid_inline.py) are rendered at build time by
+      # mmdc, which drives a headless Chrome. Without it the build still
+      # succeeds but degrades diagrams to a text fallback, so provision both.
+      - name: Install diagram toolchain (mermaid-cli + Chrome)
+        if: env.PUBLISH == 'true'
+        run: |
+          pnpm -C docs install --frozen-lockfile
+          pnpm -C docs rebuild puppeteer
+          pnpm -C docs exec mmdc --version
+
       - name: Print python versions
         if: env.PUBLISH == 'true'
         run: |

.gitignore

@@ -59,6 +59,10 @@ coverage.xml
 # Sphinx documentation
 docs/_build/
 
+# Mermaid diagram tooling (docs/_ext/mermaid_inline.py)
+docs/node_modules/
+docs/_mermaid_cache/
+
 # PyBuilder
 target/
 

CHANGES

@@ -44,6 +44,16 @@ $ tmuxp@next load yoursession
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### Documentation
+
+#### Themed diagrams across the docs (#1071)
+
+The docs now render their diagrams as theme-aware inline graphics that follow the
+site's light/dark palette and code styling, replacing the old static ASCII art.
+{ref}`workspace-builders` gains a load → build → attach flow diagram and opens
+with a concept-first overview, and {ref}`examples` shows each pane example as a
+faithful tmux window layout.
+
 ## tmuxp 1.73.0 (2026-06-28)
 
 tmuxp 1.73.0 makes the workspace build step pluggable and tunable. A workspace can now build through a third-party builder selected by registered entry-point name or Python import path, and a new `workspace_builder_options` catalog controls the pane-readiness wait per workspace. The built-in builder stays the default, so existing workspaces keep working — though the new `pane_readiness: auto` default skips the prompt wait on non-zsh shells. See {ref}`custom-workspace-builders` for the guide.

docs/AGENTS.md

@@ -0,0 +1,80 @@
+# Documentation voice
+
+This file covers the *voice* of prose under `docs/` — how to frame a
+feature page so a reader meets the idea before its configuration. It
+complements the repository-root `AGENTS.md`, which already governs code
+blocks, shell-command formatting, changelog conventions, and MyST
+roles. When the two overlap, the root file wins; this one only answers
+the question it leaves open: how should the prose sound?
+
+## Who you are writing for
+
+The default reader runs tmuxp and writes workspace files in YAML or
+JSON. They are fluent in tmux itself — servers, sessions, windows,
+panes, layouts, the shell and its prompt — but you cannot assume they
+read Python, know tmuxp's internals, or have heard of its builder
+architecture, entry points, or `sys.path`.
+
+A second, smaller reader writes Python: custom builders, plugins, code
+against libtmux. Serve them too, but mark their material as opt-in
+("for the braver cases", "advanced") so the default reader knows they
+can stop. Never make the common case pay a comprehension tax for the
+advanced one.
+
+## Voice
+
+- **Second person, present tense, active.** "You name the builder", not
+  "The builder is selected". Address the reader who is doing the thing.
+- **Concept before configuration.** Open by saying what the thing *is*
+  and what it does for the reader. The YAML surface — the keys, the
+  flags — is the last detail they need, not the first. A page that
+  opens with "set these keys" has buried the idea under its mechanics.
+- **Say when they can stop.** Lead with the default and the
+  reassurance: most readers never touch this, it works out of the box,
+  everything here is optional. Let a skimmer leave after one sentence.
+- **Progressive disclosure.** Order by how many readers need it:
+  default → the one option a few will tune → swapping the whole thing
+  → writing your own. Each step is for a smaller audience than the last.
+- **Name the trade-off.** If an option costs something — load time, a
+  slower attach — say so, and say what it buys ("a little slower, but
+  the workspace is fully prepped before you attach"). State it; don't
+  sell it.
+- **Frame by concept, not by mechanism.** Don't call a feature "the
+  keys" or "the flags" in prose; that names the implementation surface,
+  which is the reader's last concern. Name the concept. The mechanics
+  vocabulary — a `Key` / `Type` / `Default` table — is correct in a
+  reference table, and only there.
+
+## What stays precise
+
+Warm the framing, never the facts. Resolution-order lists, value
+tables, exact error strings, and class or function cross-references
+carry meaning in their exact form — leave them alone. The friendly
+voice belongs in the sentences *around* a precise block, introducing
+it, not inside it paraphrasing it into vagueness.
+
+## Cross-references
+
+Point the advanced reader at the deep-dive rather than inlining it, and
+put the link where their interest peaks — on the phrase that made them
+curious ("write your own") — not as a standalone footnote the eye
+skips. Use the MyST roles listed in the root `AGENTS.md`.
+
+## A page that does this
+
+`docs/configuration/workspace-builders.md` is the worked example:
+a concept-first intro, an out-of-the-box reassurance, sections ordered
+by shrinking audience, an honest trade-off on the prompt wait, and
+precise reference tables left precise. Read it before reshaping another
+page.
+
+## Before you commit
+
+- Does the page open with what the feature *is*, or with how to
+  configure it?
+- Can a reader who needs only the default stop after the first
+  paragraph?
+- Is anything framed as "the keys/flags" that should be named by
+  concept instead?
+- Are the advanced and Python-only parts clearly marked opt-in?
+- Did you leave every table, error string, and cross-reference exact?

docs/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md