From 6db43a77a1395dc539b7b98ddf3cf83b8e6c3868 Mon Sep 17 00:00:00 2001
From: Mark Bacon <mark@bacon.me.uk>
Date: Wed, 21 Oct 2026 14:31:54 +0100
Subject: [PATCH 1/6] Support Option 1 (HTML twin --watch server) and Option 3
 (Instant previews) for Word, slides, and posters

---
 .gitignore                           |   1 +
 editors/vscode/README.md             |  39 +++++++---
 editors/vscode/extension.js          |  95 ++++++++++++++++++-----
 editors/vscode/package-lock.json     | 110 +++++++++++++++++++++++++++
 editors/vscode/package.json          |  26 ++++++-
 editors/vscode/test/test.js          |  21 ++++-
 src/py_doc/_cli.py                   |  83 ++++++++++++++++++++
 src/py_doc/cli.py                    |   3 +-
 src/py_doc/convert.py                |  18 +++++
 src/py_doc/pandoc/resources/html.css |   9 +++
 src/py_doc/poster_watch.py           |   9 ++-
 src/py_doc/slides_cli.py             |   3 +-
 tests/test_cli.py                    |  26 +++++++
 tests/test_convert.py                |  22 ++++++
 tests/test_slides_cli.py             |  27 +++++++
 15 files changed, 454 insertions(+), 38 deletions(-)
 create mode 100644 editors/vscode/package-lock.json

diff --git a/.gitignore b/.gitignore
index d3b7ab9..98a667d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,4 @@ build/
 .py-doc/
 .structurizr/
 .venv/
+node_modules/
diff --git a/editors/vscode/README.md b/editors/vscode/README.md
index 3ac429e..498b905 100644
--- a/editors/vscode/README.md
+++ b/editors/vscode/README.md
@@ -6,17 +6,36 @@ It formats custom `py-doc` Word (`.docx`) markers, callouts, numbered captions,
 
 ---
 
-## Two Preview Modes: Instant vs. Watch Server
+## Two Preview Modes: Instant vs. HTML Twin Live Watch
 
-### 1. Instant Editor Preview (`Ctrl+K V` or `Ctrl+Shift+V`)
-* **Zero dependencies, instant typing-latency**: Formats text, callouts, numbered captions, slide cards, poster stat strips, card grids, and Mermaid diagrams directly in the editor as you type.
-* **No Docker required**: Works offline without compiling files.
+This extension provides two complementary ways to preview your documents:
 
-### 2. Live Poster Watch Server (`py-doc poster --watch`)
-* **100% Pixel-Perfect Production Render**: Click the **👁️ (Live Poster Watch)** button in the editor navigation bar (or run `py-doc poster <file> --watch --port 8765 --no-open` in the terminal).
-* **Side-by-Side in VS Code**: Automatically docks a side-by-side browser tab inside VS Code using `Simple Browser`.
-* **Auto-Reloads on Save (`Ctrl+S`)**: Rebuilds the poster in the background and reloads the tab in ~0.7 seconds.
-* **Compiles Every Diagram**: Renders PlantUML, Graphviz, Ditaa, Wavedrom, Vega, Pikchr, and Bytefield diagrams into true vector SVGs via `py-doc`'s container.
+| Capability | Option 3: Instant In-Editor Preview | Option 1: Live Watch Server (HTML Twin) |
+|:---|:---|:---|
+| **Trigger** | `Ctrl+K V` or `Ctrl+Shift+V` (or standard Preview icon) | `👁️` eye icon in editor title bar, or `py-doc ... --watch` |
+| **Speed** | Instant (<1ms), updates on every keystroke | ~1 second on save (`Ctrl+S`) |
+| **Docker / Tooling** | **Zero dependencies**, 100% offline pure JavaScript | Uses `py-doc`'s tool container via Pandoc |
+| **Formats Supported** | Technical Documents, Slide Decks, Posters | Technical Documents (`docx`), Slide Decks (`slides`), Posters (`poster`) |
+| **Diagrams** | Live client SVG preview for Mermaid, PlantUML syntax cards | Full 100% compilation of all 12 diagram engines (Mermaid, PlantUML, Graphviz, Ditaa, Wavedrom, Vega, Pikchr, Bytefield, etc.) |
+| **Where it Displays** | Native VS Code Markdown preview pane | Side-by-side inside VS Code via `Simple Browser` or external browser |
+| **File Lock Tolerance** | Never touches output files | Tolerates open Word/PowerPoint locks; always serves HTML twin reliably |
+
+---
+
+### How Option 1 (Live Watch Server) Works Across All Formats
+
+When you run `py-doc` with `--watch` (or click `👁️` in VS Code):
+1. **Technical Documents (`py-doc docx file.md --watch`)**:
+   - Rebuilds `file.docx` on save (gracefully warning if Word has it open).
+   - Compiles an **HTML twin** (`file.html`) with Pandoc, MathML, admonitions, and all diagrams.
+   - Serves the twin at `http://127.0.0.1:8765` with auto-reload polling.
+2. **Slide Decks (`py-doc slides deck.md --watch`)**:
+   - Rebuilds `deck.pptx` on save.
+   - Compiles an HTML presentation twin with styled slides, columns, and formatted speaker notes (`::: notes` / `<!-- notes: ... -->`).
+   - Serves the twin with auto-reload polling.
+3. **Posters (`py-doc poster poster.md --watch`)**:
+   - Rebuilds the self-contained poster HTML file on save with true vector graphics and barcodes.
+   - Serves the poster with auto-reload polling.
 
 ---
 
@@ -110,4 +129,4 @@ In projects initialized with `py-doc init`, or at the root of `py-doc`:
 npm test
 ```
 
-Runs all 8 test suites validating documents, slides, posters, image dimensions, and diagram features.
+Runs all 9 test suites validating documents, slides, posters, image dimensions, diagram features, and format auto-detection.
diff --git a/editors/vscode/extension.js b/editors/vscode/extension.js
index 56b77ca..b523fd1 100644
--- a/editors/vscode/extension.js
+++ b/editors/vscode/extension.js
@@ -742,35 +742,93 @@ try { vscode = require('vscode'); } catch (e) { vscode = null; }
 
 let watchTerminal = null;
 
+function detectDocumentFormat(document) {
+  const text = typeof document.getText === 'function' ? document.getText() : String(document);
+  const frontMatterMatch = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  const frontMatter = frontMatterMatch ? frontMatterMatch[1] : '';
+  const parsed = parseSimpleYaml(frontMatter);
+  const fileName = ((document && document.fileName) || (document && document.name) || '').toLowerCase();
+
+  // 1. Poster detection
+  if (parsed.theme || parsed.size || parsed.columns || parsed.posters || fileName.includes('poster')) {
+    return 'poster';
+  }
+
+  // 2. Slides detection
+  if (parsed.format === 'slides' || parsed.aspect_ratio || parsed.split_level || fileName.includes('slide') || fileName.includes('talk') || fileName.includes('deck')) {
+    return 'slides';
+  }
+
+  // 3. Default to Word document
+  return 'docx';
+}
+
+function launchWatchTerminal(subcommand, filePath, port) {
+  if (!vscode) return;
+
+  if (!watchTerminal || watchTerminal.exitStatus !== undefined) {
+    watchTerminal = vscode.window.createTerminal({
+      name: `py-doc ${subcommand} watch`,
+      iconPath: new vscode.ThemeIcon('eye')
+    });
+  }
+
+  watchTerminal.show(true);
+  watchTerminal.sendText(`py-doc ${subcommand} "${filePath}" --watch --port ${port} --no-open`);
+
+  setTimeout(() => {
+    vscode.commands.executeCommand('simpleBrowser.show', `http://127.0.0.1:${port}`);
+  }, 1500);
+}
+
 function activate(context) {
   if (!vscode) return;
 
-  const disposable = vscode.commands.registerCommand('pydoc.openPosterWatch', async () => {
+  const getActiveFile = () => {
     const editor = vscode.window.activeTextEditor;
     if (!editor) {
-      vscode.window.showErrorMessage('No active Markdown file to watch.');
-      return;
+      vscode.window.showErrorMessage('No active Markdown file to preview.');
+      return null;
     }
+    return editor;
+  };
 
-    const filePath = editor.document.uri.fsPath;
-    const port = 8765;
+  const port = 8765;
 
-    if (!watchTerminal || watchTerminal.exitStatus !== undefined) {
-      watchTerminal = vscode.window.createTerminal({
-        name: 'py-doc poster watch',
-        iconPath: new vscode.ThemeIcon('eye')
-      });
-    }
+  const liveWatchCmd = vscode.commands.registerCommand('pydoc.openLiveWatch', async () => {
+    const editor = getActiveFile();
+    if (!editor) return;
+    const format = detectDocumentFormat(editor.document);
+    launchWatchTerminal(format, editor.document.uri.fsPath, port);
+  });
+
+  const docxWatchCmd = vscode.commands.registerCommand('pydoc.openDocxWatch', async () => {
+    const editor = getActiveFile();
+    if (!editor) return;
+    launchWatchTerminal('docx', editor.document.uri.fsPath, port);
+  });
 
-    watchTerminal.show(true);
-    watchTerminal.sendText(`py-doc poster "${filePath}" --watch --port ${port} --no-open`);
+  const slidesWatchCmd = vscode.commands.registerCommand('pydoc.openSlidesWatch', async () => {
+    const editor = getActiveFile();
+    if (!editor) return;
+    launchWatchTerminal('slides', editor.document.uri.fsPath, port);
+  });
 
-    setTimeout(() => {
-      vscode.commands.executeCommand('simpleBrowser.show', `http://127.0.0.1:${port}`);
-    }, 1500);
+  const posterWatchCmd = vscode.commands.registerCommand('pydoc.openPosterWatch', async () => {
+    const editor = getActiveFile();
+    if (!editor) return;
+    launchWatchTerminal('poster', editor.document.uri.fsPath, port);
+  });
+
+  const stopWatchCmd = vscode.commands.registerCommand('pydoc.stopLiveWatch', async () => {
+    if (watchTerminal) {
+      watchTerminal.dispose();
+      watchTerminal = null;
+      vscode.window.showInformationMessage('py-doc live watch server stopped.');
+    }
   });
 
-  context.subscriptions.push(disposable);
+  context.subscriptions.push(liveWatchCmd, docxWatchCmd, slidesWatchCmd, posterWatchCmd, stopWatchCmd);
 }
 
 function deactivate() {
@@ -788,5 +846,6 @@ module.exports = {
   deactivate,
   extendMarkdownIt,
   pyDocPlugin,
-  parseSimpleYaml
+  parseSimpleYaml,
+  detectDocumentFormat
 };
diff --git a/editors/vscode/package-lock.json b/editors/vscode/package-lock.json
new file mode 100644
index 0000000..9dd18d0
--- /dev/null
+++ b/editors/vscode/package-lock.json
@@ -0,0 +1,110 @@
+{
+  "name": "vscode-py-doc-preview",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "vscode-py-doc-preview",
+      "version": "1.0.0",
+      "devDependencies": {
+        "markdown-it": "^14.1.0"
+      },
+      "engines": {
+        "vscode": "^1.75.0"
+      }
+    },
+    "node_modules/argparse": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
+      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+      "dev": true,
+      "license": "Python-2.0"
+    },
+    "node_modules/entities": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
+      "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
+    "node_modules/linkify-it": {
+      "version": "5.0.2",
+      "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.2.tgz",
+      "integrity": "sha512-ONTm2jCMAVZjgQa/Fy1kScXsuOoF5NPTsoFBdE1KVIZ2vAh/r9+Bqo+0jINCBYnavTPQZz38QzFTme79ENoN3Q==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/puzrin"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/markdown-it"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "uc.micro": "^2.0.0"
+      }
+    },
+    "node_modules/markdown-it": {
+      "version": "14.3.3",
+      "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.3.3.tgz",
+      "integrity": "sha512-L//tDAkjTjJCU6pBUSBTgs3Kg4InVaZuUZog/b6V12UKhcDQ7S78877ibbCanRExwPuYP1CZD7Gd2dxSy1GXRg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/puzrin"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/markdown-it"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1",
+        "entities": "^4.5.0",
+        "linkify-it": "^5.0.2",
+        "mdurl": "^2.0.0",
+        "punycode.js": "^2.3.1",
+        "uc.micro": "^2.1.0"
+      },
+      "bin": {
+        "markdown-it": "bin/markdown-it.mjs"
+      }
+    },
+    "node_modules/mdurl": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.1.0.tgz",
+      "integrity": "sha512-1+HBaOx0zi/dQWht8rNv9MYf9qqpqL/kxI0hXImU6Y547zM6Sni8BQibt7ifgMcYtQg41ao3Ivd6cnSM86inpg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/punycode.js": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz",
+      "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/uc.micro": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz",
+      "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==",
+      "dev": true,
+      "license": "MIT"
+    }
+  }
+}
diff --git a/editors/vscode/package.json b/editors/vscode/package.json
index 745d607..6b3e2ab 100644
--- a/editors/vscode/package.json
+++ b/editors/vscode/package.json
@@ -28,16 +28,36 @@
   "contributes": {
     "commands": [
       {
-        "command": "pydoc.openPosterWatch",
-        "title": "py-doc: Open Live Poster Preview (via Watch Server)",
+        "command": "pydoc.openLiveWatch",
+        "title": "py-doc: Open Live Preview (HTML Twin Watch Server)",
         "category": "py-doc",
         "icon": "$(eye)"
+      },
+      {
+        "command": "pydoc.openDocxWatch",
+        "title": "py-doc: Open Live Word Document Preview (docx --watch)",
+        "category": "py-doc"
+      },
+      {
+        "command": "pydoc.openSlidesWatch",
+        "title": "py-doc: Open Live Presentation Preview (slides --watch)",
+        "category": "py-doc"
+      },
+      {
+        "command": "pydoc.openPosterWatch",
+        "title": "py-doc: Open Live Poster Preview (poster --watch)",
+        "category": "py-doc"
+      },
+      {
+        "command": "pydoc.stopLiveWatch",
+        "title": "py-doc: Stop Live Preview Server",
+        "category": "py-doc"
       }
     ],
     "menus": {
       "editor/title": [
         {
-          "command": "pydoc.openPosterWatch",
+          "command": "pydoc.openLiveWatch",
           "when": "resourceExtname == .md",
           "group": "navigation"
         }
diff --git a/editors/vscode/test/test.js b/editors/vscode/test/test.js
index aa5a0fe..b68cf0b 100644
--- a/editors/vscode/test/test.js
+++ b/editors/vscode/test/test.js
@@ -210,4 +210,23 @@ digraph G {
   console.log('✓ Image width attributes and diagram fence blocks rendered correctly');
 }
 
-console.log('\nAll 8 test suites passed successfully! 🎉');
+// Test 9: Document format detection
+{
+  const { detectDocumentFormat } = require('../extension');
+
+  // Poster detection
+  assert(detectDocumentFormat('---\ntitle: Poster\ntheme: dark\nsize: a0\n---\n# Poster') === 'poster', 'theme in front-matter means poster');
+  assert(detectDocumentFormat({ getText: () => '# Just doc', fileName: 'c:/docs/sn100-poster.md' }) === 'poster', 'poster in filename means poster');
+
+  // Slides detection
+  assert(detectDocumentFormat('---\ntitle: Deck\nformat: slides\n---\n# Slide 1') === 'slides', 'format: slides means slides');
+  assert(detectDocumentFormat({ getText: () => '# Presentation', fileName: 'c:/decks/talk.md' }) === 'slides', 'talk/deck in filename means slides');
+
+  // Docx default
+  assert(detectDocumentFormat('---\ntitle: Tech Spec\nauthor: Jane\n---\n# Chapter 1') === 'docx', 'standard technical doc defaults to docx');
+  assert(detectDocumentFormat({ getText: () => '# Guide', fileName: 'c:/docs/guide.md' }) === 'docx', 'guide.md defaults to docx');
+
+  console.log('✓ Document format detection for live watch server (docx, slides, poster) works correctly');
+}
+
+console.log('\nAll 9 test suites passed successfully! 🎉');
diff --git a/src/py_doc/_cli.py b/src/py_doc/_cli.py
index 15e41c1..7dbcf2f 100644
--- a/src/py_doc/_cli.py
+++ b/src/py_doc/_cli.py
@@ -50,6 +50,22 @@ def add_common_options(parser: argparse.ArgumentParser, kind: str, suffix: str)
         action="store_true",
         help="Use a default blank document with a warning if the template file is not found (default: fail)",
     )
+    parser.add_argument(
+        "--watch",
+        action="store_true",
+        help="Build again on every save, and reload an HTML preview twin in the browser (Ctrl+C stops)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=0,
+        help="With --watch, the local port to serve the preview on (default: a free one)",
+    )
+    parser.add_argument(
+        "--no-open",
+        action="store_true",
+        help="With --watch, do not open the browser",
+    )
     noise = parser.add_mutually_exclusive_group()
     noise.add_argument("-q", "--quiet", action="store_true", help="Only show warnings and errors")
     noise.add_argument("-v", "--verbose", action="store_true", help="Show debug detail")
@@ -124,6 +140,71 @@ def convert_all(converter: Converter, args: argparse.Namespace, suffix: str, lab
     return status
 
 
+def watch_converter(converter: Converter, args: argparse.Namespace, suffix: str, label: str) -> int:
+    """Watch source files, rebuild the document and an HTML twin preview on every save, and reload in browser."""
+    input_path = Path(args.input).resolve()
+    try:
+        converter.validate_template()
+        if input_path.is_file():
+            if not is_markdown(input_path):
+                logger.warning(f"'{input_path.name}' does not end in .md or .markdown")
+            pairs = [(input_path, output_for_file(input_path, args.output, suffix).resolve())]
+        elif input_path.is_dir():
+            pairs = plan_directory(input_path, args.output, suffix)
+        else:
+            error(f"Path not found: {input_path}")
+            return 1
+    except (FileNotFoundError, ConversionError) as exc:
+        error(str(exc))
+        return exit_status(exc)
+
+    if not pairs:
+        logger.warning(f"No Markdown files found in '{input_path}'")
+        return 0
+
+    def build_all() -> tuple[dict[str, Path], set[Path]]:
+        pages: dict[str, Path] = {}
+        sources: set[Path] = {p[0].resolve() for p in pairs}
+        template_path = getattr(converter, "template_path", None)
+        if template_path:
+            sources.add(template_path.resolve())
+
+        for src, dst in pairs:
+            # 1. Attempt primary document (.docx or .pptx)
+            try:
+                converter.convert_file(src, dst)
+                print(f"wrote {dst}")
+            except PermissionError:
+                logger.warning(f"{dst.name} is open in Word/PowerPoint; skipped writing {dst.suffix}")
+            except ConversionError as exc:
+                if "locked" in str(exc).lower():
+                    logger.warning(f"{dst.name} is open in Word/PowerPoint; skipped writing {dst.suffix}")
+                else:
+                    raise
+
+            # 2. Render HTML preview twin
+            twin_path = dst.with_suffix(".html")
+            if hasattr(converter, "convert_twin"):
+                converter.convert_twin(src, twin_path)
+            else:
+                twin_path = converter.convert_file(src, twin_path)
+            print(f"wrote {twin_path} (HTML preview twin)")
+            pages[src.stem] = twin_path.resolve()
+
+        return pages, sources
+
+    from .poster_watch import watch
+
+    errors = (ConversionError, FileNotFoundError, OSError)
+    return watch(
+        build_all,
+        errors,
+        port=getattr(args, "port", 0),
+        open_browser=not getattr(args, "no_open", False),
+        title=f"{label} Preview",
+    )
+
+
 def deprecation_notice(old: str, new: str) -> str:
     return (
         f"{old} is now part of py-doc. `{new}` does the same, and `py-doc build` builds every document "
@@ -143,4 +224,6 @@ def run(
     configure_logging(quiet=args.quiet, verbose=args.verbose)
     if notice:
         logger.info(notice)
+    if getattr(args, "watch", False):
+        return watch_converter(make_converter(args), args, suffix, label)
     return convert_all(make_converter(args), args, suffix, label)
diff --git a/src/py_doc/cli.py b/src/py_doc/cli.py
index db89b69..6c3a607 100644
--- a/src/py_doc/cli.py
+++ b/src/py_doc/cli.py
@@ -17,7 +17,8 @@
 EXAMPLES = """examples:
   py-doc docx guide.md                        guide.docx next to it (or -o FILE)
   py-doc docx guide.md -t Template.docx       with a Word template
-  py-doc docx docs -o build                   every Markdown file in docs, into build/"""
+  py-doc docx docs -o build                   every Markdown file in docs, into build/
+  py-doc docx guide.md --watch                live HTML twin preview in the browser on every save"""
 
 
 def build_parser(prog: str = "py-doc docx") -> argparse.ArgumentParser:
diff --git a/src/py_doc/convert.py b/src/py_doc/convert.py
index bc998fd..43dc47d 100644
--- a/src/py_doc/convert.py
+++ b/src/py_doc/convert.py
@@ -72,6 +72,24 @@ def convert_file(self, md_path: Path, output_path: Path) -> Path:
             self.options, self.runtime, keep_going=False,
         )  # fmt: skip
 
+    def convert_twin(self, md_path: Path, output_path: Path) -> Path:
+        """Render an HTML preview twin of the document or presentation."""
+        md_path = Path(md_path).resolve()
+        if not md_path.is_file():
+            raise FileNotFoundError(f"Markdown file not found: {md_path}")
+        joined = join_sources([Source(md_path)], {}, {}, md_path.name)
+        if self.fmt == "pptx":
+            from .pandoc.pptx_finish import notes_to_divs
+
+            joined = replace(joined, parts=[(src, notes_to_divs(md)) for src, md in joined.parts])
+        metadata = joined.metadata
+        if not metadata.title:
+            metadata = replace(metadata, title=joined.first_heading or md_path.stem)
+        return render_output(
+            "html", joined, metadata, Path(output_path), md_path.name, [md_path.parent], None,
+            self.options, self.runtime, keep_going=False,
+        )  # fmt: skip
+
 
 class DocxConverter(_Converter):
     """Markdown to a Word document. The template, when given, is the reference document."""
diff --git a/src/py_doc/pandoc/resources/html.css b/src/py_doc/pandoc/resources/html.css
index 567b4b7..6831a51 100644
--- a/src/py_doc/pandoc/resources/html.css
+++ b/src/py_doc/pandoc/resources/html.css
@@ -12,4 +12,13 @@ div.tip { background: #e8f5e9; border-color: #2e7d32; }
 div.important { background: #f1ecf9; border-color: #6a3fb5; }
 div.warning { background: #fff4e0; border-color: #e08a00; }
 div.caution { background: #fce8e8; border-color: #c62828; }
+figure { margin: 1.5em 0; text-align: center; }
+figcaption { font-size: 0.9em; color: #4b5563; margin-top: 0.5em; font-style: italic; }
+caption { font-size: 0.9em; font-weight: 600; color: #003c64; padding-bottom: 0.5em; text-align: left; }
+div.notes { background: #f1f5f9; border-left: 4px solid #64748b; border-radius: 4px; padding: 0.5em 1em; margin: 1.2em 0; font-size: 0.9em; color: #334155; }
+div.notes > p:first-child::before { content: "📝 Speaker Note: "; font-weight: 600; color: #1e293b; }
+div.columns { display: flex; gap: 1.5em; margin: 1em 0; }
+div.column { flex: 1; min-width: 0; }
+hr.pagebreak, hr.pydoc-pagebreak { border: none; border-top: 2px dashed #cbd5e1; margin: 2em 0; position: relative; }
+hr.pagebreak::after, hr.pydoc-pagebreak::after { content: "Page Break"; position: absolute; right: 0; top: -0.8em; background: #fff; padding: 0 0.5em; font-size: 0.75em; color: #94a3b8; text-transform: uppercase; letter-spacing: 0.05em; }
 @media print { h1, h2, h3 { break-after: avoid; } pre, table, img { break-inside: avoid; } }
diff --git a/src/py_doc/poster_watch.py b/src/py_doc/poster_watch.py
index 2e143a1..7124fea 100644
--- a/src/py_doc/poster_watch.py
+++ b/src/py_doc/poster_watch.py
@@ -46,11 +46,12 @@
 class State:
     """The pages being served, the build they are from, and the error of the last build, if it failed."""
 
-    def __init__(self) -> None:
+    def __init__(self, title: str = "Posters") -> None:
         self.lock = threading.Lock()
         self.pages: dict[str, Path] = {}
         self.version = 0
         self.error: str | None = None
+        self.title = title
 
 
 def watched_files(folders: set[Path], files: set[Path], outputs: set[Path]) -> dict[Path, int]:
@@ -94,7 +95,7 @@ def do_GET(self):  # noqa: N802 (the name http.server calls)
                 return self._send(200, "text/html; charset=utf-8", page.replace("</body>", script + "</body>", 1))
             if not name:
                 links = "".join(f'<li><a href="/{html.escape(n)}.html">{html.escape(n)}</a></li>' for n in pages)
-                return self._send(200, "text/html; charset=utf-8", f"<!doctype html><title>Posters</title><ul>{links}</ul>")
+                return self._send(200, "text/html; charset=utf-8", f"<!doctype html><title>{state.title}</title><ul>{links}</ul>")
             self._send(404, "text/plain", f"No poster {name}")
 
         def _send(self, code: int, kind: str, body: str) -> None:
@@ -115,9 +116,9 @@ def log_message(self, *args) -> None:
 
 
 def watch(build: Build, errors: tuple[type[Exception], ...], port: int = 0, open_browser: bool = True,
-          stop: threading.Event | None = None, interval: float = INTERVAL) -> int:
+          stop: threading.Event | None = None, interval: float = INTERVAL, title: str = "py-doc preview") -> int:
     """Build, serve, and build again on every change, until Ctrl+C or ``stop``. Returns the exit status."""
-    state, stop = State(), stop or threading.Event()
+    state, stop = State(title=title), stop or threading.Event()
 
     def rebuild() -> set[Path]:
         started = time.monotonic()
diff --git a/src/py_doc/slides_cli.py b/src/py_doc/slides_cli.py
index efd9161..112a9b1 100644
--- a/src/py_doc/slides_cli.py
+++ b/src/py_doc/slides_cli.py
@@ -14,7 +14,8 @@
 EXAMPLES = """examples:
   py-doc slides talk.md                       talk.pptx next to it (or -o FILE)
   py-doc slides talk.md -t Template.pptx      with a PowerPoint template
-  py-doc slides talk.md --split-level 1       a new slide only at each # heading"""
+  py-doc slides talk.md --split-level 1       a new slide only at each # heading
+  py-doc slides talk.md --watch               live HTML twin preview in the browser on every save"""
 
 
 def build_parser(prog: str = "py-doc slides") -> argparse.ArgumentParser:
diff --git a/tests/test_cli.py b/tests/test_cli.py
index ec8080c..dcf386a 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -297,3 +297,29 @@ def test_compat_module_entry_point_runs(self, tmp_path):
         )
         assert result.returncode == 0
         assert "py-doc2docx" in result.stdout
+
+    def test_docx_watch_mode(self, tmp_path, monkeypatch):
+        from py_doc.cli import run_docx
+        from py_doc import poster_watch
+
+        src = tmp_path / "spec.md"
+        src.write_text("# Spec\n\nText\n", encoding="utf-8")
+
+        called = []
+
+        def fake_watch(build, errors, port=0, open_browser=True, stop=None, interval=0.5, title=""):
+            pages, sources = build()
+            called.append((pages, sources, port, open_browser, title))
+            return 0
+
+        monkeypatch.setattr(poster_watch, "watch", fake_watch)
+        code = run_docx([str(src), "--watch", "--port", "9876", "--no-open"])
+        assert code == 0
+        assert len(called) == 1
+        pages, sources, port, open_browser, title = called[0]
+        assert "spec" in pages
+        assert pages["spec"].is_file()
+        assert (tmp_path / "spec.docx").is_file()
+        assert port == 9876
+        assert open_browser is False
+        assert "Word Preview" in title
diff --git a/tests/test_convert.py b/tests/test_convert.py
index 91a81b6..d6174bd 100644
--- a/tests/test_convert.py
+++ b/tests/test_convert.py
@@ -90,3 +90,25 @@ def test_a_template_without_the_layouts_pandoc_needs_is_explained(tmp_path, pand
     (tmp_path / "a.md").write_text("# A\n\n## B\n\n- x\n", encoding="utf-8")
     with pytest.raises(ConversionError, match="no slides"):
         SlidesConverter(template_path=template).convert_file(tmp_path / "a.md", tmp_path / "a.pptx")
+
+
+def test_docx_convert_twin_produces_html(tmp_path, pandoc_runtime):
+    md = tmp_path / "spec.md"
+    md.write_text("# Specification\n\n> [!NOTE]\n> A note box.\n\nParagraph text.\n", encoding="utf-8")
+    out = DocxConverter().convert_twin(md, tmp_path / "spec.html")
+    assert out.is_file()
+    html_text = out.read_text(encoding="utf-8")
+    assert "Specification" in html_text
+    assert "admonition note" in html_text or "note" in html_text
+    assert "A note box." in html_text
+
+
+def test_slides_convert_twin_produces_html_with_notes(tmp_path, pandoc_runtime):
+    md = tmp_path / "talk.md"
+    md.write_text("# Title\n\n## First Slide\n\n- point\n\n<!-- notes: Remember to emphasize this -->\n", encoding="utf-8")
+    out = SlidesConverter().convert_twin(md, tmp_path / "talk.html")
+    assert out.is_file()
+    html_text = out.read_text(encoding="utf-8")
+    assert "First Slide" in html_text
+    assert "Remember to emphasize this" in html_text
+
diff --git a/tests/test_slides_cli.py b/tests/test_slides_cli.py
index 6bb1626..1a7a79f 100644
--- a/tests/test_slides_cli.py
+++ b/tests/test_slides_cli.py
@@ -101,3 +101,30 @@ def test_module_entry_point_prints_help():
     )
     assert result.returncode == 0
     assert "PowerPoint" in result.stdout
+
+
+def test_slides_watch_mode(tmp_path, monkeypatch):
+    from py_doc.slides_cli import run_slides
+    from py_doc import poster_watch
+
+    src = tmp_path / "deck.md"
+    src.write_text("# Deck\n\n## S1\n\n- a\n", encoding="utf-8")
+
+    called = []
+
+    def fake_watch(build, errors, port=0, open_browser=True, stop=None, interval=0.5, title=""):
+        pages, sources = build()
+        called.append((pages, sources, port, open_browser, title))
+        return 0
+
+    monkeypatch.setattr(poster_watch, "watch", fake_watch)
+    code = run_slides([str(src), "--watch", "--port", "9875", "--no-open"])
+    assert code == 0
+    assert len(called) == 1
+    pages, sources, port, open_browser, title = called[0]
+    assert "deck" in pages
+    assert pages["deck"].is_file()
+    assert (tmp_path / "deck.pptx").is_file()
+    assert port == 9875
+    assert open_browser is False
+    assert "PowerPoint Preview" in title

From 7070caf4487d0f6f549ee92d7ec6deb37d6bd3e2 Mon Sep 17 00:00:00 2001
From: Mark Bacon <mark@bacon.me.uk>
Date: Wed, 21 Oct 2026 15:03:54 +0100
Subject: [PATCH 2/6] Fix live preview review findings, and document it

VS Code extension:
- One format detection (front matter and deck-only blocks) for the instant
  preview and the eye button; real posters (paper, byline, orientation) are
  no longer sent to `py-doc docx`, and file names no longer decide
- The front matter header keeps its mode when callouts or captions render
  nested Markdown
- List and mapping values in front matter are shown instead of crashing
- Heading accents only on posters, splitting inline tokens so code, bold
  and links keep their formatting
- A new live preview stops the running one first, waits for the server
  before opening Simple Browser, and the port is a setting
- Slide grouping honours split_level; colours and weights are sanitised;
  command titles no longer repeat "py-doc"

docx/slides --watch:
- HTML twins go to .py-doc/preview, keyed by relative path, so no user
  file is overwritten and same-named files stay apart
- OutputLocked replaces matching "locked" in the message
- convert_file and convert_twin share one render helper
- Twin-only preview.css (page breaks, notes, columns); html.css is
  unchanged for normal HTML builds; page breaks carry a class
- --port/--no-open without --watch warn; served paths are URL-decoded

Docs: README, guide (single files, writing), architecture (live previews,
AD-08), workspace.dsl (VS Code extension, Live preview component and
dynamic view), requirements FR-161/162 with traceability. CI runs the
extension tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                  |  14 +-
 README.md                                 |  18 +-
 docs/architecture/00_introduction.md      |   2 +-
 docs/architecture/02_pipeline.md          |   9 +
 docs/architecture/05_decisions.md         |   7 +
 docs/architecture/workspace.dsl           |  24 +-
 docs/guide/02_projects.md                 |  14 +
 docs/guide/03_writing.md                  |   4 +-
 docs/requirements/01_functional.md        |   2 +
 docs/requirements/04_traceability.md      |   2 +
 editors/vscode/README.md                  |  29 +-
 editors/vscode/extension.js               | 324 ++++++++++++----------
 editors/vscode/package.json               |  20 +-
 editors/vscode/test/test.js               |  63 ++++-
 src/py_doc/_cli.py                        |  59 ++--
 src/py_doc/convert.py                     |  23 +-
 src/py_doc/errors.py                      |   4 +
 src/py_doc/pandoc/engine.py               |   6 +-
 src/py_doc/pandoc/resources/html.css      |   9 -
 src/py_doc/pandoc/resources/pagebreak.lua |   2 +-
 src/py_doc/pandoc/resources/preview.css   |  12 +
 src/py_doc/poster_watch.py                |   9 +-
 tests/test_cli.py                         |  47 +++-
 tests/test_slides_cli.py                  |   7 +-
 24 files changed, 465 insertions(+), 245 deletions(-)
 create mode 100644 src/py_doc/pandoc/resources/preview.css

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e7d358a..e3511e4 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -114,10 +114,22 @@ jobs:
       - run: python -m build
       - run: python -m twine check dist/*
 
+  vscode:
+    name: VS Code extension
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    defaults:
+      run:
+        working-directory: editors/vscode
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - run: npm ci --ignore-scripts  # the runner's own Node; markdown-it is the only (dev) dependency
+      - run: npm test
+
   gate:
     name: CI gate
     if: always()
-    needs: [lint, test, build]
+    needs: [lint, test, build, vscode]
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
diff --git a/README.md b/README.md
index 79ba647..73378a6 100644
--- a/README.md
+++ b/README.md
@@ -16,8 +16,8 @@ Pandoc writes every output, and it runs in a container with every other tool, so
 | `py-doc init` | Start a project: `py-doc.yml`, a first document, and optionally a C4 model, templates and a site |
 | `py-doc new` | Start a legacy document, or number an existing Markdown file, from `doc-numbers.yml` at the repository root |
 | `py-doc build` | Build every document described in `py-doc.yml` (generators, lint, documents, site), or one legacy `createdocs` file with `--legacy` |
-| `py-doc docx` | Convert Markdown to Word |
-| `py-doc slides` | Convert Markdown to PowerPoint |
+| `py-doc docx` | Convert Markdown to Word, or with `--watch` rebuild on every save and serve a live HTML preview |
+| `py-doc slides` | Convert Markdown to PowerPoint, with the same `--watch` live preview |
 | `py-doc lint` | Check writing style, glossary terms, acronyms, structure, links and project conventions; text, CSV, GitHub, JSON or SARIF |
 | `py-doc check` | Check a project without building it: `py-doc.yml`, sources, templates, the site and lint |
 | `py-doc generate` | Write the Markdown that `content.generators` makes: glossaries, indexes, traceability, API references |
@@ -25,7 +25,7 @@ Pandoc writes every output, and it runs in a container with every other tool, so
 | `py-doc diff` | Compare two versions of documents section by section, or against a Git revision |
 | `py-doc c4` | Check, export, draw and edit Structurizr workspaces (`c4 up` opens the live editor) |
 | `py-doc site` | Make and build a web site of the documents with MkDocs or Astro + Starlight |
-| `py-doc poster` | Build self-contained HTML posters from Markdown, and print them to PDF |
+| `py-doc poster` | Build self-contained HTML posters from Markdown, and print them to PDF; `--watch` reloads them on every save |
 | `py-doc import` | Convert a Word document or a PowerPoint deck to Markdown |
 | `py-doc template` | Check and list the styles of a Word or PowerPoint template |
 | `py-doc tools`, `doctor`, `setup` | Build and check the tool container, and install Docker Engine |
@@ -59,6 +59,8 @@ py-doc c4 up architecture/workspace.dsl     # arrange the C4 views in Structuriz
 py-doc site build                           # site/build/index.html
 ```
 
+While writing, `py-doc docx guide.md --watch` (or `slides`, or `poster`) builds on every save and keeps a live preview open in the browser, with every diagram drawn. The [VS Code extension](editors/vscode/README.md) runs it for the open file and shows the preview beside the editor, and also previews py-doc Markdown instantly as you type.
+
 ## Documentation
 
 py-doc documents itself with py-doc. The sources are in [`docs/`](docs), and the [`py-doc.yml`](py-doc.yml) at the root of this repository builds them: `py-doc build` for Word, HTML and PDF, `py-doc site build` for the web site.
@@ -79,8 +81,8 @@ src/
 │   ├── new.py            # py-doc new
 │   ├── cli.py            # py-doc docx (and the old py-doc2docx)
 │   ├── slides_cli.py     # py-doc slides (and the old py-doc2slides)
-│   ├── _cli.py           # options, output paths and batch conversion shared by both
-│   ├── convert.py        # DocxConverter and SlidesConverter, one file through pandoc
+│   ├── _cli.py           # options, output paths, batch conversion and --watch shared by both
+│   ├── convert.py        # DocxConverter and SlidesConverter, one file through pandoc, and its HTML preview twin
 │   ├── config.py         # py-doc.yml model and validation
 │   ├── build.py          # joins a document's sources and renders it
 │   ├── directives.py     # includes, conditions and variables
@@ -97,11 +99,12 @@ src/
 │   ├── analysis/         # py-doc stats, check and diff
 │   ├── migrate.py        # createdocs to py-doc.yml
 │   ├── report.py         # the JSON build report
-│   └── poster*.py        # py-doc poster: Markdown to an HTML poster, its blocks, settings, themes, fonts and --watch
+│   ├── poster*.py        # py-doc poster: Markdown to an HTML poster, its blocks, settings, themes and fonts
+│   └── poster_watch.py   # the --watch loop and preview server of poster, docx and slides
 ├── pydoc2docx/           # old import names, kept as aliases
 ├── pydoc2slides/
 └── pydoclint/
-editors/                  # editor integrations: VS Code preview extension for documents, slides and posters
+editors/vscode/           # VS Code extension: instant in-editor preview, and the --watch live preview beside the editor
 docs/                     # py-doc's own user guide, requirements and architecture
 examples/                 # a project that uses every feature
 tests/
@@ -114,6 +117,7 @@ pip install -e ".[dev]"
 python -m pytest
 ruff check .
 py-doc lint docs --strict
+cd editors/vscode && npm ci && npm test   # the VS Code extension
 ```
 
 CI runs on Linux and Windows with Python 3.14, the newest supported. Python 3.10, the oldest supported, is not tested in CI. macOS is not supported.
diff --git a/docs/architecture/00_introduction.md b/docs/architecture/00_introduction.md
index 1005036..5581240 100644
--- a/docs/architecture/00_introduction.md
+++ b/docs/architecture/00_introduction.md
@@ -13,7 +13,7 @@ keywords: [py-doc, architecture, C4]
 
 This document describes how py-doc meets its [requirements](../requirements/00_introduction.md). It covers what py-doc is made of, how a document travels from Markdown to each output, where the tools run, and why it is built this way. It is for maintainers and contributors.
 
-py-doc writes the C4 chapters from the Structurizr model in `docs/architecture/workspace.dsl`, the way any py-doc project documents its architecture. They cover the context, containers, components, relationships, deployment, the dynamic view of a build, and the element catalogue. Change the model, not those chapters. `py-doc c4 up docs/architecture/workspace.dsl` opens it in Structurizr to arrange its views.
+py-doc writes the C4 chapters from the Structurizr model in `docs/architecture/workspace.dsl`, the way any py-doc project documents its architecture. They cover the context, containers, components, relationships, deployment, the dynamic views of a build and of a live preview, and the element catalogue. Change the model, not those chapters. `py-doc c4 up docs/architecture/workspace.dsl` opens it in Structurizr to arrange its views.
 
 ## Goals
 
diff --git a/docs/architecture/02_pipeline.md b/docs/architecture/02_pipeline.md
index e2d8ac9..d3044e2 100644
--- a/docs/architecture/02_pipeline.md
+++ b/docs/architecture/02_pipeline.md
@@ -68,3 +68,12 @@ flowchart LR
 - **Check outputs**: every file the build wrote is there and not empty.
 
 `py-doc check`, `py-doc stats` and `py-doc diff` (`analysis/`) read the same configuration and the same document model, and build nothing. The diff splits each version into sections by its top-level headings. It matches them by heading path, then by text, so a renamed or moved section is not mistaken for one removed and another added.
+
+## Live previews
+
+`--watch` on `py-doc poster`, `py-doc docx` and `py-doc slides` runs one loop (`poster_watch.py`). It builds, then serves the pages on 127.0.0.1 from a thread of its own. Every half second it looks at the modification times of the source files: the Markdown, includes, pictures, diagram sources and templates below the folders of the sources. The pages it wrote and hidden folders are not watched. A change builds again. Each page is served with a small script that asks `/__status` whether a newer build is there and reloads when it is, so the files written are the same as without `--watch`. A build that fails keeps the last good page and shows its error over it.
+
+A poster is already a web page. A Word document or deck is not, so `docx` and `slides` (`_cli.py`) also write an *HTML twin* of each file (`convert.py`, `convert_twin`). The twin is the same Markdown through the same pipeline to pandoc's HTML. It adds `preview.css` after `html.css` to show page breaks, speaker notes and columns. The twins go to `.py-doc/preview/` below the input's folder and are served by their path. No file of the user's is overwritten, and two `readme.md` in different folders stay apart. When Word or PowerPoint has the output open, the engine raises `OutputLocked`; the watch loop warns and still writes the twin.
+
+The VS Code extension (`editors/vscode`) is outside the Python package. Its instant preview is a markdown-it plugin in the editor and runs no tool. Its live preview starts `py-doc <command> --watch` in a terminal, waits until `/__status` answers, and opens the served page in VS Code's Simple Browser. The extension and the instant preview choose the command with one function, from the front matter and the blocks only a deck has.
+
diff --git a/docs/architecture/05_decisions.md b/docs/architecture/05_decisions.md
index 77f2b8e..c17a45f 100644
--- a/docs/architecture/05_decisions.md
+++ b/docs/architecture/05_decisions.md
@@ -47,3 +47,10 @@ Each decision records the context, the choice and its consequences.
 - **Context**: lint findings need exact lines and source text, and must skip code, links and front matter reliably.
 - **Decision**: the linter parses with markdown-it-py into py-doc's own document model.
 - **Consequences**: precise, fast checks without the container. Two parsers can disagree on edge cases, so the anchor rules are tested against pandoc's own identifiers.
+
+## AD-08 Previews are served, not written beside the outputs
+
+- **Context**: authors want to see a document while they write it, but Word and PowerPoint have no live view, a document open in Word cannot be written, and the in-editor Markdown preview cannot draw most diagrams.
+- **Decision**: `--watch` builds an HTML twin of each document with the same pipeline, keeps it in `.py-doc/preview`, and serves it with a reload script added as it is served. The VS Code extension runs that command; its own instant preview is an approximation for typing.
+- **Consequences**: the preview shows every diagram exactly as the build draws it, and a document open in Word does not stop it. It is one HTML page, so slide boundaries and Word page layout are not shown, and a first build waits for the tool container.
+
diff --git a/docs/architecture/workspace.dsl b/docs/architecture/workspace.dsl
index 14ccd3a..0cf3517 100644
--- a/docs/architecture/workspace.dsl
+++ b/docs/architecture/workspace.dsl
@@ -12,7 +12,7 @@ workspace "py-doc" "The C4 model of py-doc, the Markdown technical documentation
 
         pydoc = softwareSystem "py-doc" "Turns Markdown into Word, PowerPoint, PDF, HTML and web sites, checks the writing, and documents C4 models." {
             cli = container "py-doc command" "The py-doc command and Python package. Reads py-doc.yml, prepares the Markdown and starts every tool in the tool image." "Python 3.10+" {
-                commands = component "Commands" "Parses the command line and hands each command to its module: build, docx, slides, lint, check, generate, stats, diff, c4, site, import, init, new, template, tools, doctor, setup, migrate. Runs the build pipeline around the documents." "argparse"
+                commands = component "Commands" "Parses the command line and hands each command to its module: build, docx, slides, poster, lint, check, generate, stats, diff, c4, site, import, init, new, template, tools, doctor, setup, migrate. Runs the build pipeline around the documents." "argparse"
                 configuration = component "Configuration" "Loads py-doc.yml and checks every key, so a mistake is an error that names its place." "PyYAML"
                 pipeline = component "Build pipeline" "Joins a document's sources, expands includes, conditions and variables, and picks the template and the output name." "Python"
                 diagrams = component "Diagram renderer" "Turns diagram fences into pictures with the right tool, and keeps them in a cache." "Python"
@@ -26,15 +26,23 @@ workspace "py-doc" "The C4 model of py-doc, the Markdown technical documentation
                 generators = component "Content generators" "Write Markdown from other sources before the build: glossaries, indexes, traceability, API references, diagram files, commands." "Python, entry points"
                 analysis = component "Analysis" "Counts what documents hold, checks a project without building it, and compares versions by section." "Python, Git"
                 report = component "Build report" "Records the tools, sources, outputs, diagrams and warnings of a build as JSON." "JSON schema"
+                watch = component "Live preview" "With --watch, builds documents, decks and posters again on every save, writes an HTML twin of each document and deck, and serves the pages on 127.0.0.1 with a script that reloads them." "Python, http.server"
             }
             toolImage = container "Tool image" "Every program that is not Python: pandoc, XeLaTeX, PlantUML, Mermaid, Graphviz, the diagram tools, Chromium, structurizr-cli, Vale, markdownlint, MkDocs and Node." "Docker image on Debian 12"
+            vscode = container "VS Code extension" "Previews py-doc Markdown in the editor as it is typed, and starts the live preview of the open file and shows it beside the editor." "JavaScript, markdown-it"
             local = container "Structurizr Local" "Shows a workspace in a browser to view it and arrange its views, and draws the pictures for documents." "Docker image structurizr/structurizr"
-            cache = container "Caches" "Diagram pictures (user cache folder), Structurizr exports and generated chapters (.py-doc in the project)." "Files" "Store"
+            cache = container "Caches" "Diagram pictures (user cache folder), Structurizr exports, generated chapters and live preview pages (.py-doc in the project)." "Files" "Store"
         }
 
         author -> pydoc.cli.commands "Runs py-doc commands" "Terminal"
         author -> pydoc.local "Views the model and arranges its views" "Browser, HTTP"
         reader -> office "Opens the documents in"
+        author -> pydoc.vscode "Writes and previews documents in" "VS Code"
+        pydoc.vscode -> pydoc.cli.commands "Starts py-doc docx, slides or poster --watch for the open file" "Terminal"
+        pydoc.vscode -> pydoc.cli.watch "Shows the served preview from" "HTTP on 127.0.0.1"
+        pydoc.cli.commands -> pydoc.cli.watch "Runs --watch with"
+        pydoc.cli.watch -> pydoc.cli.pipeline "Builds each document and its HTML twin with"
+        pydoc.cli.watch -> pydoc.cache "Keeps the HTML twins in" "Files"
         ci -> pydoc.cli.commands "Runs builds and lint checks" "Shell"
         pydoc.cli.commands -> pydoc.cli.configuration "Loads the project from"
         pydoc.cli.commands -> pydoc.cli.pipeline "Builds documents with"
@@ -73,6 +81,9 @@ workspace "py-doc" "The C4 model of py-doc, the Markdown technical documentation
                 deploymentNode "Python" "The py-doc package, installed with pip." "Python 3.10+" {
                     containerInstance pydoc.cli
                 }
+                deploymentNode "Visual Studio Code" "The author's editor, with the py-doc extension installed from editors/vscode." "VS Code 1.75+" {
+                    containerInstance pydoc.vscode
+                }
                 deploymentNode "Cache folders" "The user cache folder and the project's .py-doc folder." "File system" {
                     containerInstance pydoc.cache
                 }
@@ -110,6 +121,15 @@ workspace "py-doc" "The C4 model of py-doc, the Markdown technical documentation
             pydoc.cli.pipeline -> pydoc.cli.report "Records the outputs"
             autoLayout lr
         }
+        dynamic pydoc.cli "LivePreview" "How the VS Code extension shows a live preview of a Word document." {
+            author -> pydoc.vscode "Clicks the eye button"
+            pydoc.vscode -> pydoc.cli.commands "py-doc docx guide.md --watch"
+            pydoc.cli.commands -> pydoc.cli.watch "Watches guide.md"
+            pydoc.cli.watch -> pydoc.cli.pipeline "Builds guide.docx and its HTML twin"
+            pydoc.cli.watch -> pydoc.cache "Writes the twin to .py-doc/preview"
+            pydoc.vscode -> pydoc.cli.watch "Shows the twin, which reloads on every save"
+            autoLayout lr
+        }
         deployment pydoc live "Deployment" "Where py-doc runs on an author's computer." {
             include *
             autoLayout lr
diff --git a/docs/guide/02_projects.md b/docs/guide/02_projects.md
index c23bbac..c1bf828 100644
--- a/docs/guide/02_projects.md
+++ b/docs/guide/02_projects.md
@@ -146,6 +146,7 @@ py-doc docx Technical_Specification.md -t Template.docx
 py-doc docx docs/ -o dist/docx/              # a whole folder, structure kept
 py-doc slides talk.md -o talk.pptx
 py-doc slides talk.md -t Corporate.pptx --split-level 1
+py-doc docx Technical_Specification.md --watch   # build on every save, with a live HTML preview
 ```
 
 | Option | Commands | Description |
@@ -155,6 +156,9 @@ py-doc slides talk.md -t Corporate.pptx --split-level 1
 | `-t`, `--template` | both | A reference `.docx` or `.dotx` (Word), or `.pptx` or `.potx` (PowerPoint). `-r`, `--reference` is the old slides name |
 | `--allow-missing-template` | both | Warn and use a blank document if the template file is missing (default: fail) |
 | `--split-level N` | slides | Start a new slide at each heading up to level N (default 2) |
+| `--watch` | both | Build again on every save, and serve an HTML preview of each file that reloads itself (Ctrl+C stops) |
+| `--port N` | both | With `--watch`, the local port to serve the preview on (default: a free one) |
+| `--no-open` | both | With `--watch`, do not open the browser |
 | `-q`, `-v` | both | Only warnings and errors, or debug detail |
 | `--version` | both | Print the version |
 
@@ -165,6 +169,16 @@ A file that uses `[[IF:]]` needs its conditions defined, and only `py-doc build`
 - Two sources that would write the same output (`a.md` and `a.markdown`) are refused before anything is converted.
 - The input is checked before any folder is created, so a typo leaves nothing behind.
 
+### Live preview
+
+`--watch` builds the files, then builds them again whenever a source below their folder changes: the Markdown, an included file, a picture, a diagram source or the template. Next to each `.docx` or `.pptx` it writes an HTML twin of the same Markdown, to `.py-doc/preview/` below the input's folder, and serves the twins on this computer only. The page in the browser reloads after each build, and a build that fails shows its error over the last good page.
+
+- A document open in Word or PowerPoint cannot be written, so it is left as it is, with a warning, and its preview is still updated.
+- The twin shows page breaks as dashed lines, speaker notes in boxes and columns side by side. It is one page: a deck is not split into slides.
+- The twin is a preview, not an output. Build HTML with `py-doc build` and `outputs: html`.
+
+The [VS Code extension](03_writing.md#vs-code-preview) starts `--watch` for the open file and shows the preview beside it.
+
 The old commands `py-doc2docx`, `py-doc2slides` and `py-doclint` still work and print a one-line note naming their replacement. `-q` hides the note.
 
 ## File names and versions
diff --git a/docs/guide/03_writing.md b/docs/guide/03_writing.md
index f020a29..2c2fe5a 100644
--- a/docs/guide/03_writing.md
+++ b/docs/guide/03_writing.md
@@ -25,7 +25,9 @@ py-doc itself never drops a word or a sentence. Anything pandoc cannot represent
 
 ## VS Code preview
 
-A companion VS Code extension in [`editors/vscode/`](../../editors/vscode) provides live preview for py-doc Markdown as you write. It formats numbered captions, Word callout boxes, presentation slide cards, speaker notes, and poster structures (stat strips, card grids, flow sequences) directly in VS Code's built-in Markdown preview (`Ctrl+Shift+V` or `Ctrl+K V`).
+A companion VS Code extension in [`editors/vscode/`](../../editors/vscode) provides live preview for py-doc Markdown as you write. It works in VS Code's built-in Markdown preview (`Ctrl+Shift+V` or `Ctrl+K V`). There it formats numbered captions, Word callout boxes, slide cards, speaker notes, and poster stat strips, card grids and flows. This preview is instant and needs no tools, but it only approximates the output: diagrams other than Mermaid show as their source.
+
+For the real output, use the eye button in the editor title bar. It runs `py-doc docx`, `py-doc slides` or `py-doc poster` with `--watch` on the open file, and shows the page it serves beside the editor. It rebuilds on every save, with every diagram drawn. The extension chooses the command from the file. A poster setting such as `paper` or `byline` in the front matter means a poster. `split_level` or speaker notes mean a deck, and anything else is a Word document. See [live preview](02_projects.md#live-preview) and the extension's [README](../../editors/vscode/README.md).
 
 ## Front matter
 
diff --git a/docs/requirements/01_functional.md b/docs/requirements/01_functional.md
index 8ad9ff1..acac62f 100644
--- a/docs/requirements/01_functional.md
+++ b/docs/requirements/01_functional.md
@@ -125,6 +125,8 @@ title: Functional requirements
 | FR-158 | `py-doc lint` and `py-doc build --lint` shall lint the posters of `py-doc.yml` with every rule but the document structure, acronym and passive voice rules. | Should | Met |
 | FR-159 | `py-doc poster --watch` shall build the posters again on every save of their sources and reload them in the browser, and show a failed build's error over the last good page. | Could | Met |
 | FR-160 | A poster's sections shall say in braces what they are and how they are laid out: `{.stats}`, `{.abstract}`, `{.summary}`, `{.references}`, `{.wide}` and `{cols=}`. No heading name shall have a meaning of its own, and every part shall be placed in the order of the file. Each kind shall have a choice of looks (`style=`), and `colour=` shall colour every one. | Should | Met |
+| FR-161 | `py-doc docx --watch` and `py-doc slides --watch` shall build again on every save, serve an HTML preview of each file that reloads itself, and keep updating the preview while the document is open in Word or PowerPoint. The preview shall never overwrite a file of the user's. | Could | Met |
+| FR-162 | The VS Code extension in `editors/vscode` shall preview py-doc Markdown in the editor without any tools, and start the live preview of the open file with the command that suits it. | Could | Met |
 
 ## Tool container
 
diff --git a/docs/requirements/04_traceability.md b/docs/requirements/04_traceability.md
index 0fb9945..f4f2930 100644
--- a/docs/requirements/04_traceability.md
+++ b/docs/requirements/04_traceability.md
@@ -20,6 +20,8 @@ title: Traceability
 | FR-100 to FR-106 | `lint/`, `markdown/` | `test_lint.py`, `test_lint_cli.py`, `test_structure.py`, `test_vale.py`, `test_markdownlint.py`, `test_markdown_ast.py` |
 | FR-120 to FR-127, QR-082 | `site/`, `pandoc/resources/site.lua` | `test_site.py` |
 | FR-130 to FR-139, FR-150 to FR-160 | `poster.py`, `poster_blocks.py`, `poster_fonts.py`, `poster_settings.py`, `poster_themes.py`, `poster_cli.py`, `poster_watch.py`, `config.py`, `app.py`, `lint/linter.py`, `diagrams/tools/poster_pdf.js` | `test_poster.py`, `test_poster_browser.py` |
+| FR-161 | `_cli.py`, `convert.py`, `poster_watch.py`, `pandoc/engine.py`, `pandoc/resources/preview.css` | `test_cli.py`, `test_slides_cli.py`, `test_convert.py` |
+| FR-162 | `editors/vscode/extension.js` | `editors/vscode/test/test.js` |
 | FR-028 | `diagrams/render.py`, `config.py` | `test_diagrams.py` |
 | FR-128 | `site/pages.py`, `site/engines.py` | `test_site.py` |
 | FR-140 to FR-143, QR-040 to QR-043 | `runtime/`, `tools_cli.py` | `test_runtime.py`, `test_image.py`, `test_setup.py`, `test_doctor.py`, `test_platform.py` |
diff --git a/editors/vscode/README.md b/editors/vscode/README.md
index 498b905..7e240b7 100644
--- a/editors/vscode/README.md
+++ b/editors/vscode/README.md
@@ -18,7 +18,7 @@ This extension provides two complementary ways to preview your documents:
 | **Formats Supported** | Technical Documents, Slide Decks, Posters | Technical Documents (`docx`), Slide Decks (`slides`), Posters (`poster`) |
 | **Diagrams** | Live client SVG preview for Mermaid, PlantUML syntax cards | Full 100% compilation of all 12 diagram engines (Mermaid, PlantUML, Graphviz, Ditaa, Wavedrom, Vega, Pikchr, Bytefield, etc.) |
 | **Where it Displays** | Native VS Code Markdown preview pane | Side-by-side inside VS Code via `Simple Browser` or external browser |
-| **File Lock Tolerance** | Never touches output files | Tolerates open Word/PowerPoint locks; always serves HTML twin reliably |
+| **File Lock Tolerance** | Never touches output files | Skips a `.docx`/`.pptx` open in Word or PowerPoint, with a warning, and still updates the HTML twin |
 
 ---
 
@@ -26,16 +26,23 @@ This extension provides two complementary ways to preview your documents:
 
 When you run `py-doc` with `--watch` (or click `👁️` in VS Code):
 1. **Technical Documents (`py-doc docx file.md --watch`)**:
-   - Rebuilds `file.docx` on save (gracefully warning if Word has it open).
-   - Compiles an **HTML twin** (`file.html`) with Pandoc, MathML, admonitions, and all diagrams.
-   - Serves the twin at `http://127.0.0.1:8765` with auto-reload polling.
+   - Rebuilds `file.docx` on save. If Word has it open, it is left as it is, with a warning, and the preview still updates.
+   - Builds an **HTML twin** with Pandoc, MathML, admonitions, all diagrams, and page breaks shown as dashed lines.
+   - The twin is written to `.py-doc/preview/` below the document's folder, so no file of yours is overwritten.
 2. **Slide Decks (`py-doc slides deck.md --watch`)**:
-   - Rebuilds `deck.pptx` on save.
-   - Compiles an HTML presentation twin with styled slides, columns, and formatted speaker notes (`::: notes` / `<!-- notes: ... -->`).
-   - Serves the twin with auto-reload polling.
+   - Rebuilds `deck.pptx` on save (PowerPoint locks are handled the same way).
+   - Builds an HTML twin of the deck's content as one continuous page: columns side by side, and speaker notes (`::: notes` / `<!-- notes: ... -->`) in labelled boxes. It does not split the content into slides; use the instant preview for slide layout.
 3. **Posters (`py-doc poster poster.md --watch`)**:
    - Rebuilds the self-contained poster HTML file on save with true vector graphics and barcodes.
-   - Serves the poster with auto-reload polling.
+
+Every format is served at `http://127.0.0.1:8765` (the `pydoc.watch.port` setting) and reloads on each save.
+
+The `👁️` button chooses the command from the file itself, the same way the instant preview chooses its mode:
+- **Poster**: the front matter has a poster setting (`paper`, `byline`, `orientation`, `theme`, `columns`, `width`, `colours`, `palette`, `logo`, `embed_fonts`).
+- **Slides**: the front matter has `split_level` or a `format` of `slides`/`pptx`, or the body has `:::: columns`, `::: notes`, `::: incremental` or `<!-- notes: -->` outside code blocks.
+- **Word document**: anything else.
+
+Use **py-doc: Open Live Word Document / Presentation / Poster Preview** from the Command Palette to choose the format yourself. Opening a new preview stops the one already running, and **py-doc: Stop Live Preview Server** stops it.
 
 ---
 
@@ -58,7 +65,7 @@ When you run `py-doc` with `--watch` (or click `👁️` in VS Code):
 
 ### 2. Slide Decks (PowerPoint `.pptx`)
 
-When authoring a slide deck (e.g. `slides.md`, `format: pptx`, or using slide directives), the preview switches to **Slide Deck Mode**:
+When authoring a slide deck (`format: pptx`, `split_level`, or columns, speaker notes and incremental lists in the body), the preview switches to **Slide Deck Mode**. With `split_level: 1`, each `#` heading starts a content slide, as it does in PowerPoint:
 
 | Slide Feature | `py-doc` Syntax | Preview Rendering |
 |:---|:---|:---|
@@ -73,7 +80,7 @@ When authoring a slide deck (e.g. `slides.md`, `format: pptx`, or using slide di
 
 ### 3. Posters (HTML & PDF Posters)
 
-When authoring a poster (e.g. `paper: a1`, `byline: ...`, or headings with `{.stats}`), the preview switches to **Poster Mode**:
+When authoring a poster (a poster setting such as `paper: a1` or `byline: ...` in the front matter), the preview switches to **Poster Mode**:
 
 | Poster Feature | `py-doc` Syntax | Preview Rendering |
 |:---|:---|:---|
@@ -129,4 +136,4 @@ In projects initialized with `py-doc init`, or at the root of `py-doc`:
 npm test
 ```
 
-Runs all 9 test suites validating documents, slides, posters, image dimensions, diagram features, and format auto-detection.
+Runs all 10 test suites validating documents, slides, posters, image dimensions, diagram features, format auto-detection, and regressions.
diff --git a/editors/vscode/extension.js b/editors/vscode/extension.js
index b523fd1..dae3179 100644
--- a/editors/vscode/extension.js
+++ b/editors/vscode/extension.js
@@ -54,14 +54,18 @@ function parseSimpleYaml(yamlStr) {
     const trimmed = line.trim();
     if (!trimmed || trimmed.startsWith('#')) continue;
 
+    const item = trimmed.match(/^-\s+(.*)$/);
+    if (item && currentKey) {
+      if (!Array.isArray(result[currentKey])) result[currentKey] = [];
+      result[currentKey].push(unquote(item[1].trim()));
+      continue;
+    }
+
     if (line.startsWith('  ') && currentKey) {
       const subColon = trimmed.indexOf(':');
       if (subColon > 0) {
         const subKey = trimmed.slice(0, subColon).trim();
-        let subVal = trimmed.slice(subColon + 1).trim();
-        if ((subVal.startsWith('"') && subVal.endsWith('"')) || (subVal.startsWith("'") && subVal.endsWith("'"))) {
-          subVal = subVal.slice(1, -1);
-        }
+        const subVal = unquote(trimmed.slice(subColon + 1).trim());
         if (typeof result[currentKey] !== 'object' || result[currentKey] === null) {
           result[currentKey] = {};
         }
@@ -73,23 +77,36 @@ function parseSimpleYaml(yamlStr) {
     const colonIdx = trimmed.indexOf(':');
     if (colonIdx > 0) {
       const key = trimmed.slice(0, colonIdx).trim();
-      let val = trimmed.slice(colonIdx + 1).trim();
-      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
-        val = val.slice(1, -1);
-      }
-      if (val === '') {
-        currentKey = key;
-        result[key] = {};
-      } else {
-        currentKey = key;
-        result[key] = val;
-      }
+      const val = unquote(trimmed.slice(colonIdx + 1).trim());
+      currentKey = key;
+      result[key] = val === '' ? {} : val;
     }
   }
   return result;
 }
 
-function escapeHtml(str) {
+function unquote(val) {
+  if (val.length >= 2 && ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'")))) {
+    return val.slice(1, -1);
+  }
+  return val;
+}
+
+// Front matter values may be lists (author: [- Jane, - Joe]) or mappings, so anything is turned into text first
+function asText(val) {
+  if (val === null || val === undefined) return '';
+  if (Array.isArray(val)) return val.map(asText).join(', ');
+  if (typeof val === 'object') return Object.values(val).map(asText).join(', ');
+  return String(val);
+}
+
+// A colour name written in the Markdown, made safe to use as part of a class name
+function cssName(val) {
+  return asText(val).toLowerCase().replace(/[^a-z0-9_-]/g, '');
+}
+
+function escapeHtml(val) {
+  const str = asText(val);
   if (!str) return '';
   return str.replace(/&/g, '&amp;')
             .replace(/</g, '&lt;')
@@ -113,7 +130,7 @@ function renderFrontMatterBlock(meta, docMode) {
     }
     html += '  <div class="pydoc-poster-meta">\n';
     if (meta.paper) {
-      html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Paper:</span> ${escapeHtml(meta.paper.toUpperCase())}</span>\n`;
+      html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Paper:</span> ${escapeHtml(asText(meta.paper).toUpperCase())}</span>\n`;
     }
     if (meta.document_number) {
       html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Doc #:</span> ${escapeHtml(meta.document_number)}</span>\n`;
@@ -142,7 +159,7 @@ function renderFrontMatterBlock(meta, docMode) {
     html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Version:</span> ${escapeHtml(meta.version)}</span>\n`;
   }
   if (meta.status) {
-    const statusClass = meta.status.toLowerCase() === 'draft' ? 'draft' : 'released';
+    const statusClass = asText(meta.status).toLowerCase() === 'draft' ? 'draft' : 'released';
     html += `    <span class="pydoc-meta-item pydoc-status-${statusClass}"><span class="pydoc-meta-key">Status:</span> ${escapeHtml(meta.status)}</span>\n`;
   }
   if (meta.author) {
@@ -156,7 +173,54 @@ function renderFrontMatterBlock(meta, docMode) {
   return html;
 }
 
+// Front matter keys only a poster has (see py_doc/poster_settings.py)
+const POSTER_KEYS = ['paper', 'byline', 'orientation', 'theme', 'columns', 'width', 'colours', 'palette', 'embed_fonts', 'logo'];
+const SLIDE_DIVS = /^:{3,4}\s*\{?\.?(columns|column|notes|incremental)\}?\s*$/;
+
+/**
+ * Which py-doc command a Markdown file is for: 'poster', 'slides' or 'docx'.
+ * Decided from the front matter, then from blocks only a deck has (columns, speaker notes, incremental lists).
+ * The instant preview and the live watch button both use this, so they always agree.
+ */
+function detectFormat(meta, body) {
+  meta = meta || {};
+  const fmt = asText(meta.format || meta.output || meta.type || meta.layout).toLowerCase();
+  if (fmt.includes('pptx') || fmt.includes('slide') || meta.split_level) return 'slides';
+  if (fmt.includes('poster') || POSTER_KEYS.some((k) => meta[k] !== undefined && meta[k] !== '')) return 'poster';
+
+  let fence = null;
+  for (const line of (body || '').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/);
+    if (fenceMatch) {
+      if (!fence) fence = fenceMatch[1][0];
+      else if (trimmed[0] === fence) fence = null;
+      continue;
+    }
+    if (fence) continue;
+    if (SLIDE_DIVS.test(trimmed) || /^<!--\s*notes:/i.test(trimmed)) return 'slides';
+  }
+  return 'docx';
+}
+
+function splitFrontMatter(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/);
+  return m ? { meta: parseSimpleYaml(m[1]), body: text.slice(m[0].length) } : { meta: {}, body: text };
+}
+
+function detectDocumentFormat(document) {
+  const text = document && typeof document.getText === 'function' ? document.getText() : String(document);
+  const { meta, body } = splitFrontMatter(text);
+  return detectFormat(meta, body);
+}
+
+const PREVIEW_MODE = { poster: 'poster', slides: 'slide', docx: 'document' };
+
 function pyDocPlugin(md) {
+  // The front matter token carries the mode of its document in .info, so a nested md.renderInline call
+  // (made while processing captions and callouts) cannot change how the outer document's header renders
+  md.renderer.rules.pydoc_front_matter = (ts, idx) => renderFrontMatterBlock(ts[idx].meta, ts[idx].info || 'document');
+
   // 1. Block rule to parse Front Matter at line 0
   md.block.ruler.before('table', 'pydoc_front_matter', (state, startLine, endLine, silent) => {
     if (startLine !== 0) return false;
@@ -267,37 +331,10 @@ function pyDocPlugin(md) {
   md.core.ruler.push('pydoc_core', (state) => {
     const counters = {};
     const tokens = state.tokens;
-
-    let docMode = 'document';
-    let docTitle = 'py-doc Document';
-    let frontMeta = null;
-
-    if (tokens.length > 0 && tokens[0].type === 'pydoc_front_matter' && tokens[0].meta) {
-      frontMeta = tokens[0].meta;
-      if (frontMeta.title) docTitle = frontMeta.title;
-
-      if (frontMeta.paper || frontMeta.byline || (frontMeta.theme && !frontMeta.split_level)) {
-        docMode = 'poster';
-      }
-
-      const fmt = (frontMeta.format || frontMeta.output || frontMeta.type || frontMeta.layout || '').toLowerCase();
-      if (fmt.includes('pptx') || fmt.includes('slide') || frontMeta.split_level) {
-        docMode = 'slide';
-      }
-    }
-
-    if (docMode === 'document') {
-      for (const t of tokens) {
-        if (t.type === 'pydoc_div_open' && (t.info === 'columns' || t.info === 'notes' || t.info === 'incremental')) {
-          docMode = 'slide';
-          break;
-        }
-      }
-    }
-
-    md.renderer.rules.pydoc_front_matter = (ts, idx) => {
-      return renderFrontMatterBlock(ts[idx].meta, docMode);
-    };
+    const frontMeta = (tokens.length > 0 && tokens[0].type === 'pydoc_front_matter' && tokens[0].meta) || null;
+    const docTitle = (frontMeta && asText(frontMeta.title)) || 'py-doc Document';
+    const docMode = PREVIEW_MODE[detectFormat(frontMeta, splitFrontMatter(state.src).body)];
+    if (frontMeta) tokens[0].info = docMode;
 
     for (let i = 0; i < tokens.length; i++) {
       const token = tokens[i];
@@ -345,22 +382,31 @@ function pyDocPlugin(md) {
             token.attrs.push(['class', `pydoc-heading-${headingClass}`]);
           }
 
-          const colonIdx = text.indexOf(':');
-          if (colonIdx > 0 && !classMatch) {
-            const prefix = text.slice(0, colonIdx + 1);
-            const accent = text.slice(colonIdx + 1);
-            next.content = '';
-            next.children = [new state.Token('html_inline', '', 0)];
-            next.children[0].content = `${escapeHtml(prefix)} <span class="pydoc-heading-accent">${escapeHtml(accent)}</span>`;
-          } else {
-            next.content = text;
-            if (classMatch) {
-              for (const c of next.children) {
-                if (c.type === 'text') {
-                  c.content = c.content.replace(/\s*\{([.#][\w\s.-]+)\}\s*$/, '');
-                }
+          next.content = text;
+          if (classMatch) {
+            for (const c of next.children) {
+              if (c.type === 'text') {
+                c.content = c.content.replace(/\s*\{([.#][\w\s.-]+)\}\s*$/, '');
               }
             }
+          } else if (docMode === 'poster') {
+            // Poster headings: what follows the first colon is the accent. The inline tokens are split, not
+            // re-rendered, so code, bold and links after the colon keep their formatting
+            const children = next.children || [];
+            const k = children.findIndex((c) => c.type === 'text' && c.content.indexOf(':') > 0);
+            if (k !== -1) {
+              const colon = children[k].content.indexOf(':');
+              const rest = children[k].content.slice(colon + 1);
+              children[k].content = children[k].content.slice(0, colon + 1);
+              const open = new state.Token('html_inline', '', 0);
+              open.content = '<span class="pydoc-heading-accent">';
+              const restToken = new state.Token('text', '', 0);
+              restToken.content = rest;
+              const close = new state.Token('html_inline', '', 0);
+              close.content = '</span>';
+              children.splice(k + 1, 0, open, restToken);
+              children.push(close);
+            }
           }
 
           if (headingClass === 'stats') {
@@ -436,7 +482,7 @@ function pyDocPlugin(md) {
               const title = parts[0];
               const desc = parts[1];
               const color = parts[2] || 'blue';
-              cardsHtml += `  <div class="pydoc-card-item pydoc-card-${color}">\n`;
+              cardsHtml += `  <div class="pydoc-card-item pydoc-card-${cssName(color)}">\n`;
               cardsHtml += `    <div class="pydoc-card-title">${escapeHtml(title)}</div>\n`;
               cardsHtml += `    <div class="pydoc-card-desc">${escapeHtml(desc)}</div>\n`;
               cardsHtml += '  </div>\n';
@@ -475,7 +521,7 @@ function pyDocPlugin(md) {
           }
           segHtml += '  <div class="pydoc-segments-bar">\n';
           for (const it of items) {
-            segHtml += `    <div class="pydoc-segment-slice pydoc-bg-${it.color}" style="flex: ${it.weight}" title="${escapeHtml(it.label)}: ${escapeHtml(it.value)}"><span class="pydoc-segment-text">${escapeHtml(it.label)}</span></div>\n`;
+            segHtml += `    <div class="pydoc-segment-slice pydoc-bg-${cssName(it.color)}" style="flex: ${Number.parseFloat(it.weight) || 1}" title="${escapeHtml(it.label)}: ${escapeHtml(it.value)}"><span class="pydoc-segment-text">${escapeHtml(it.label)}</span></div>\n`;
           }
           segHtml += '  </div>\n';
           segHtml += '</div>\n';
@@ -497,7 +543,7 @@ function pyDocPlugin(md) {
                 const nodeMatch = item.match(/^\[(.*?)(?:\|(.*?))?\]$/);
                 const nodeText = nodeMatch ? nodeMatch[1] : item;
                 const nodeColor = (nodeMatch && nodeMatch[2]) ? nodeMatch[2] : 'blue';
-                flowHtml += `    <span class="pydoc-flow-node pydoc-bg-${nodeColor}">${escapeHtml(nodeText)}</span>\n`;
+                flowHtml += `    <span class="pydoc-flow-node pydoc-bg-${cssName(nodeColor)}">${escapeHtml(nodeText)}</span>\n`;
               } else {
                 flowHtml += `    <span class="pydoc-flow-arrow">➔ ${escapeHtml(item)}</span>\n`;
               }
@@ -662,7 +708,7 @@ function pyDocPlugin(md) {
 
     // G. If in Slide Deck mode, group tokens into presentation slide cards
     if (docMode === 'slide') {
-      groupTokensIntoSlides(state, docTitle);
+      groupTokensIntoSlides(state, docTitle, Number.parseInt(asText(frontMeta && frontMeta.split_level), 10) || 2);
     }
 
     // H. If in Poster mode, append poster footer if defined
@@ -683,7 +729,8 @@ function pyDocPlugin(md) {
   });
 }
 
-function groupTokensIntoSlides(state, docTitle) {
+// A heading at splitLevel or above starts a slide, as pandoc's --slide-level does; one above it is a section slide
+function groupTokensIntoSlides(state, docTitle, splitLevel) {
   const tokens = state.tokens;
   const newTokens = [];
   let currentSlideTokens = [];
@@ -718,9 +765,9 @@ function groupTokensIntoSlides(state, docTitle) {
 
     if (token.type === 'heading_open') {
       const level = parseInt(token.tag.slice(1), 10);
-      if (level <= 2) {
+      if (level <= splitLevel) {
         flushSlide(isCurrentSection);
-        isCurrentSection = (level === 1);
+        isCurrentSection = (level < splitLevel);
       }
     }
 
@@ -742,99 +789,93 @@ try { vscode = require('vscode'); } catch (e) { vscode = null; }
 
 let watchTerminal = null;
 
-function detectDocumentFormat(document) {
-  const text = typeof document.getText === 'function' ? document.getText() : String(document);
-  const frontMatterMatch = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  const frontMatter = frontMatterMatch ? frontMatterMatch[1] : '';
-  const parsed = parseSimpleYaml(frontMatter);
-  const fileName = ((document && document.fileName) || (document && document.name) || '').toLowerCase();
-
-  // 1. Poster detection
-  if (parsed.theme || parsed.size || parsed.columns || parsed.posters || fileName.includes('poster')) {
-    return 'poster';
-  }
+const WATCH_START_TIMEOUT = 120000;  // ms: a first build may have to start the tool container
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
-  // 2. Slides detection
-  if (parsed.format === 'slides' || parsed.aspect_ratio || parsed.split_level || fileName.includes('slide') || fileName.includes('talk') || fileName.includes('deck')) {
-    return 'slides';
-  }
+// Whether a py-doc watch server answers on this port
+function serverUp(port) {
+  return new Promise((resolve) => {
+    const req = require('http').get({ host: '127.0.0.1', port, path: '/__status', timeout: 500 }, (res) => {
+      res.resume();
+      resolve(res.statusCode === 200);
+    });
+    req.on('timeout', () => req.destroy());
+    req.on('error', () => resolve(false));
+  });
+}
 
-  // 3. Default to Word document
-  return 'docx';
+function stopWatch() {
+  if (watchTerminal) {
+    watchTerminal.dispose();  // ends the py-doc process running in it
+    watchTerminal = null;
+    return true;
+  }
+  return false;
 }
 
-function launchWatchTerminal(subcommand, filePath, port) {
-  if (!vscode) return;
+async function launchWatch(subcommand, filePath) {
+  const port = vscode.workspace.getConfiguration('pydoc').get('watch.port', 8765);
 
-  if (!watchTerminal || watchTerminal.exitStatus !== undefined) {
-    watchTerminal = vscode.window.createTerminal({
-      name: `py-doc ${subcommand} watch`,
-      iconPath: new vscode.ThemeIcon('eye')
-    });
+  // A running watch is stopped first: typing a new command into its terminal would go to the running process
+  if (stopWatch()) {
+    for (let waited = 0; waited < 5000 && await serverUp(port); waited += 250) await delay(250);
   }
 
-  watchTerminal.show(true);
-  watchTerminal.sendText(`py-doc ${subcommand} "${filePath}" --watch --port ${port} --no-open`);
-
-  setTimeout(() => {
+  const terminal = vscode.window.createTerminal({
+    name: `py-doc ${subcommand} watch`,
+    iconPath: new vscode.ThemeIcon('eye')
+  });
+  watchTerminal = terminal;
+  terminal.show(true);
+  terminal.sendText(`py-doc ${subcommand} "${filePath}" --watch --port ${port} --no-open`);
+
+  const started = await vscode.window.withProgress(
+    { location: vscode.ProgressLocation.Window, title: `py-doc: building the ${subcommand} preview` },
+    async () => {
+      for (let waited = 0; waited < WATCH_START_TIMEOUT; waited += 500) {
+        if (watchTerminal !== terminal || terminal.exitStatus !== undefined) return false;
+        if (await serverUp(port)) return true;
+        await delay(500);
+      }
+      return false;
+    }
+  );
+  if (started) {
     vscode.commands.executeCommand('simpleBrowser.show', `http://127.0.0.1:${port}`);
-  }, 1500);
+  } else if (watchTerminal === terminal) {
+    vscode.window.showWarningMessage(`The py-doc preview server did not start on port ${port}. See the "${terminal.name}" terminal.`);
+  }
 }
 
 function activate(context) {
   if (!vscode) return;
 
-  const getActiveFile = () => {
+  const withActiveFile = (run) => async () => {
     const editor = vscode.window.activeTextEditor;
     if (!editor) {
       vscode.window.showErrorMessage('No active Markdown file to preview.');
-      return null;
+      return;
     }
-    return editor;
+    await run(editor.document);
   };
 
-  const port = 8765;
-
-  const liveWatchCmd = vscode.commands.registerCommand('pydoc.openLiveWatch', async () => {
-    const editor = getActiveFile();
-    if (!editor) return;
-    const format = detectDocumentFormat(editor.document);
-    launchWatchTerminal(format, editor.document.uri.fsPath, port);
-  });
-
-  const docxWatchCmd = vscode.commands.registerCommand('pydoc.openDocxWatch', async () => {
-    const editor = getActiveFile();
-    if (!editor) return;
-    launchWatchTerminal('docx', editor.document.uri.fsPath, port);
-  });
-
-  const slidesWatchCmd = vscode.commands.registerCommand('pydoc.openSlidesWatch', async () => {
-    const editor = getActiveFile();
-    if (!editor) return;
-    launchWatchTerminal('slides', editor.document.uri.fsPath, port);
-  });
-
-  const posterWatchCmd = vscode.commands.registerCommand('pydoc.openPosterWatch', async () => {
-    const editor = getActiveFile();
-    if (!editor) return;
-    launchWatchTerminal('poster', editor.document.uri.fsPath, port);
-  });
-
-  const stopWatchCmd = vscode.commands.registerCommand('pydoc.stopLiveWatch', async () => {
-    if (watchTerminal) {
-      watchTerminal.dispose();
-      watchTerminal = null;
-      vscode.window.showInformationMessage('py-doc live watch server stopped.');
-    }
-  });
-
-  context.subscriptions.push(liveWatchCmd, docxWatchCmd, slidesWatchCmd, posterWatchCmd, stopWatchCmd);
+  context.subscriptions.push(
+    vscode.commands.registerCommand('pydoc.openLiveWatch',
+      withActiveFile((doc) => launchWatch(detectDocumentFormat(doc), doc.uri.fsPath))),
+    vscode.commands.registerCommand('pydoc.openDocxWatch', withActiveFile((doc) => launchWatch('docx', doc.uri.fsPath))),
+    vscode.commands.registerCommand('pydoc.openSlidesWatch', withActiveFile((doc) => launchWatch('slides', doc.uri.fsPath))),
+    vscode.commands.registerCommand('pydoc.openPosterWatch', withActiveFile((doc) => launchWatch('poster', doc.uri.fsPath))),
+    vscode.commands.registerCommand('pydoc.stopLiveWatch', () => {
+      if (stopWatch()) vscode.window.showInformationMessage('py-doc live preview server stopped.');
+    }),
+    vscode.window.onDidCloseTerminal((closed) => {
+      if (closed === watchTerminal) watchTerminal = null;
+    })
+  );
 }
 
 function deactivate() {
-  if (watchTerminal) {
-    watchTerminal.dispose();
-  }
+  stopWatch();
 }
 
 function extendMarkdownIt(md) {
@@ -847,5 +888,6 @@ module.exports = {
   extendMarkdownIt,
   pyDocPlugin,
   parseSimpleYaml,
+  detectFormat,
   detectDocumentFormat
 };
diff --git a/editors/vscode/package.json b/editors/vscode/package.json
index 6b3e2ab..c6faeeb 100644
--- a/editors/vscode/package.json
+++ b/editors/vscode/package.json
@@ -29,28 +29,28 @@
     "commands": [
       {
         "command": "pydoc.openLiveWatch",
-        "title": "py-doc: Open Live Preview (HTML Twin Watch Server)",
+        "title": "Open Live Preview (HTML Twin Watch Server)",
         "category": "py-doc",
         "icon": "$(eye)"
       },
       {
         "command": "pydoc.openDocxWatch",
-        "title": "py-doc: Open Live Word Document Preview (docx --watch)",
+        "title": "Open Live Word Document Preview (docx --watch)",
         "category": "py-doc"
       },
       {
         "command": "pydoc.openSlidesWatch",
-        "title": "py-doc: Open Live Presentation Preview (slides --watch)",
+        "title": "Open Live Presentation Preview (slides --watch)",
         "category": "py-doc"
       },
       {
         "command": "pydoc.openPosterWatch",
-        "title": "py-doc: Open Live Poster Preview (poster --watch)",
+        "title": "Open Live Poster Preview (poster --watch)",
         "category": "py-doc"
       },
       {
         "command": "pydoc.stopLiveWatch",
-        "title": "py-doc: Stop Live Preview Server",
+        "title": "Stop Live Preview Server",
         "category": "py-doc"
       }
     ],
@@ -63,6 +63,16 @@
         }
       ]
     },
+    "configuration": {
+      "title": "py-doc",
+      "properties": {
+        "pydoc.watch.port": {
+          "type": "number",
+          "default": 8765,
+          "description": "The local port the live preview watch server (py-doc ... --watch) serves on."
+        }
+      }
+    },
     "markdown.markdownItPlugins": true,
     "markdown.previewStyles": [
       "./styles/py-doc-preview.css"
diff --git a/editors/vscode/test/test.js b/editors/vscode/test/test.js
index b68cf0b..950021b 100644
--- a/editors/vscode/test/test.js
+++ b/editors/vscode/test/test.js
@@ -212,21 +212,66 @@ digraph G {
 
 // Test 9: Document format detection
 {
+  const fs = require('fs');
+  const path = require('path');
   const { detectDocumentFormat } = require('../extension');
+  const doc = (text) => ({ getText: () => text, fileName: 'c:/docs/anything.md' });
 
-  // Poster detection
-  assert(detectDocumentFormat('---\ntitle: Poster\ntheme: dark\nsize: a0\n---\n# Poster') === 'poster', 'theme in front-matter means poster');
-  assert(detectDocumentFormat({ getText: () => '# Just doc', fileName: 'c:/docs/sn100-poster.md' }) === 'poster', 'poster in filename means poster');
+  // Posters: any poster-only front matter key
+  assert(detectDocumentFormat('---\ntitle: Poster\ntheme: dark\n---\n# Poster') === 'poster', 'theme in front matter means poster');
+  assert(detectDocumentFormat('---\ntitle: P\norientation: landscape\npaper: a1\n---\n## A') === 'poster', 'paper/orientation mean poster');
+  const landscape = path.join(__dirname, '..', '..', '..', 'examples', 'poster', 'landscape.md');
+  if (fs.existsSync(landscape)) {
+    assert(detectDocumentFormat(doc(fs.readFileSync(landscape, 'utf8'))) === 'poster', 'examples/poster/landscape.md is a poster');
+  }
 
-  // Slides detection
+  // Slides: front matter, or blocks only a deck has
   assert(detectDocumentFormat('---\ntitle: Deck\nformat: slides\n---\n# Slide 1') === 'slides', 'format: slides means slides');
-  assert(detectDocumentFormat({ getText: () => '# Presentation', fileName: 'c:/decks/talk.md' }) === 'slides', 'talk/deck in filename means slides');
+  assert(detectDocumentFormat('---\nsplit_level: 1\n---\n# S') === 'slides', 'split_level means slides');
+  assert(detectDocumentFormat('# Talk\n\n## One\n\n::: notes\nSay this\n:::\n') === 'slides', 'speaker notes mean slides');
+  assert(detectDocumentFormat('# Doc\n\n```markdown\n::: notes\n```\n') === 'docx', 'notes inside a code fence do not count');
 
-  // Docx default
-  assert(detectDocumentFormat('---\ntitle: Tech Spec\nauthor: Jane\n---\n# Chapter 1') === 'docx', 'standard technical doc defaults to docx');
-  assert(detectDocumentFormat({ getText: () => '# Guide', fileName: 'c:/docs/guide.md' }) === 'docx', 'guide.md defaults to docx');
+  // The file name decides nothing
+  assert(detectDocumentFormat({ getText: () => '# Just doc', fileName: 'c:/docs/sn100-poster.md' }) === 'docx', 'poster in a file name is not a poster');
+  assert(detectDocumentFormat({ getText: () => '# Guide', fileName: 'c:/decks/talk.md' }) === 'docx', 'talk in a file name is not a deck');
+  assert(detectDocumentFormat('---\ntitle: Tech Spec\nauthor: Jane\n---\n# Chapter 1') === 'docx', 'a technical doc defaults to docx');
 
   console.log('✓ Document format detection for live watch server (docx, slides, poster) works correctly');
 }
 
-console.log('\nAll 9 test suites passed successfully! 🎉');
+// Test 10: Regressions: front matter mode with nested renders, list values, heading accents, split_level, escaping
+{
+  const fresh = () => new MarkdownIt({ html: true }).use(pyDocPlugin);
+  const poster = '---\ntitle: P\nbyline: me\npaper: a1\n---\n\n## A\n\n';
+
+  // A callout (rendered with md.renderInline) must not turn the poster header into a document header
+  let html = fresh().render(poster + '> [!NOTE]\n> hi\n\n[[CAPTION:Figure]] A figure\n');
+  assert(html.includes('pydoc-poster-header'), 'poster header survives callouts and captions');
+  assert(!html.includes('pydoc-frontmatter'), 'no document header in a poster');
+
+  // A list in the front matter is shown, not a crash
+  html = fresh().render('---\ntitle: T\nauthor:\n  - Jane\n  - Joe\n---\n\n# x\n');
+  assert(html.includes('Jane, Joe'), 'author list is joined');
+
+  // Heading accents: posters only, formatting kept
+  html = fresh().render(poster + '## Step 1: install `py-doc` with **pip**\n');
+  assert(html.includes('<span class="pydoc-heading-accent">'), 'poster heading gets an accent');
+  assert(html.includes('<code>py-doc</code>') && html.includes('<strong>pip</strong>'), 'accent keeps inline formatting');
+  html = fresh().render('# Doc\n\n## Step 1: install `py-doc`\n');
+  assert(!html.includes('pydoc-heading-accent'), 'documents get no heading accent');
+  assert(html.includes('<code>py-doc</code>'), 'document heading keeps inline code');
+
+  // split_level 1: each # heading is a content slide, ## does not split
+  html = fresh().render('---\nsplit_level: 1\n---\n\n# One\n\n## Sub\n\ntext\n\n# Two\n');
+  assert((html.match(/<section class="pydoc-slide /g) || []).length === 2, 'split_level 1 makes one slide per # heading');
+  assert(!html.includes('pydoc-slide-section'), 'no section slides at split_level 1');
+
+  // Colours and weights from the Markdown cannot break out of attributes
+  html = fresh().render(poster + '```cards\nA | B | blue" onclick="x\n```\n\n```segments\nx" y | L | 1 | red\n```\n');
+  assert(!html.includes('onclick="'), 'card colour is sanitised');
+  assert(!html.includes('flex: x"'), 'segment weight is sanitised');
+
+  console.log('✓ Regressions: nested renders, list front matter, heading accents, split_level and escaping');
+}
+
+console.log('\nAll 10 test suites passed successfully! 🎉');
diff --git a/src/py_doc/_cli.py b/src/py_doc/_cli.py
index 7dbcf2f..d2fa4d4 100644
--- a/src/py_doc/_cli.py
+++ b/src/py_doc/_cli.py
@@ -12,7 +12,7 @@
 
 from . import __version__
 from ._logging import configure_logging
-from .errors import ConversionError, exit_status
+from .errors import ConversionError, OutputLocked, exit_status
 from .files import find_markdown, is_markdown
 
 logger = logging.getLogger(__name__)
@@ -23,6 +23,8 @@ def validate_template(self) -> None: ...
 
     def convert_file(self, md_path: Path, output_path: Path) -> Path: ...
 
+    def convert_twin(self, md_path: Path, output_path: Path) -> Path: ...
+
 
 def safe_console() -> None:
     """Let a character the output's encoding lacks become ``?`` instead of stopping the command.
@@ -140,16 +142,26 @@ def convert_all(converter: Converter, args: argparse.Namespace, suffix: str, lab
     return status
 
 
+PREVIEW_DIR = Path(".py-doc") / "preview"  # where --watch writes the HTML twins, below the input folder
+
+
 def watch_converter(converter: Converter, args: argparse.Namespace, suffix: str, label: str) -> int:
-    """Watch source files, rebuild the document and an HTML twin preview on every save, and reload in browser."""
+    """Build the documents and an HTML twin of each on every save, and serve the twins with a live reload.
+
+    The twins go to ``.py-doc/preview`` below the input's folder, so no file of the user's is overwritten and
+    the folder of documents stays clean. A document open in Word or PowerPoint is left as it is, with a
+    warning, and its twin is still built.
+    """
     input_path = Path(args.input).resolve()
     try:
         converter.validate_template()
         if input_path.is_file():
             if not is_markdown(input_path):
                 logger.warning(f"'{input_path.name}' does not end in .md or .markdown")
+            base = input_path.parent
             pairs = [(input_path, output_for_file(input_path, args.output, suffix).resolve())]
         elif input_path.is_dir():
+            base = input_path
             pairs = plan_directory(input_path, args.output, suffix)
         else:
             error(f"Path not found: {input_path}")
@@ -162,45 +174,30 @@ def watch_converter(converter: Converter, args: argparse.Namespace, suffix: str,
         logger.warning(f"No Markdown files found in '{input_path}'")
         return 0
 
+    sources = {src for src, _ in pairs}
+    template_path = getattr(converter, "template_path", None)
+    if template_path:
+        sources.add(Path(template_path).resolve())
+
     def build_all() -> tuple[dict[str, Path], set[Path]]:
         pages: dict[str, Path] = {}
-        sources: set[Path] = {p[0].resolve() for p in pairs}
-        template_path = getattr(converter, "template_path", None)
-        if template_path:
-            sources.add(template_path.resolve())
-
         for src, dst in pairs:
-            # 1. Attempt primary document (.docx or .pptx)
             try:
                 converter.convert_file(src, dst)
                 print(f"wrote {dst}")
-            except PermissionError:
-                logger.warning(f"{dst.name} is open in Word/PowerPoint; skipped writing {dst.suffix}")
-            except ConversionError as exc:
-                if "locked" in str(exc).lower():
-                    logger.warning(f"{dst.name} is open in Word/PowerPoint; skipped writing {dst.suffix}")
-                else:
-                    raise
-
-            # 2. Render HTML preview twin
-            twin_path = dst.with_suffix(".html")
-            if hasattr(converter, "convert_twin"):
-                converter.convert_twin(src, twin_path)
-            else:
-                twin_path = converter.convert_file(src, twin_path)
-            print(f"wrote {twin_path} (HTML preview twin)")
-            pages[src.stem] = twin_path.resolve()
-
+            except OutputLocked:
+                logger.warning(f"{dst.name} is open in {label}, so it was not written; the preview is up to date")
+            name = src.relative_to(base).with_suffix("").as_posix()  # by path, so a/readme and b/readme both show
+            pages[name] = converter.convert_twin(src, base / PREVIEW_DIR / f"{name}.html").resolve()
         return pages, sources
 
     from .poster_watch import watch
 
-    errors = (ConversionError, FileNotFoundError, OSError)
     return watch(
         build_all,
-        errors,
-        port=getattr(args, "port", 0),
-        open_browser=not getattr(args, "no_open", False),
+        (ConversionError, FileNotFoundError, OSError),
+        port=args.port,
+        open_browser=not args.no_open,
         title=f"{label} Preview",
     )
 
@@ -224,6 +221,8 @@ def run(
     configure_logging(quiet=args.quiet, verbose=args.verbose)
     if notice:
         logger.info(notice)
-    if getattr(args, "watch", False):
+    if args.watch:
         return watch_converter(make_converter(args), args, suffix, label)
+    if args.port or args.no_open:
+        logger.warning("--port and --no-open only apply with --watch, so they are ignored")
     return convert_all(make_converter(args), args, suffix, label)
diff --git a/src/py_doc/convert.py b/src/py_doc/convert.py
index 43dc47d..8c6711b 100644
--- a/src/py_doc/convert.py
+++ b/src/py_doc/convert.py
@@ -60,25 +60,18 @@ def validate_template(self) -> None:
             raise ConversionError(f"The {self.kind} template must be one of {', '.join(self.template_suffixes)}: {path}")
 
     def convert_file(self, md_path: Path, output_path: Path) -> Path:
-        md_path = Path(md_path).resolve()
-        if not md_path.is_file():
-            raise FileNotFoundError(f"Markdown file not found: {md_path}")
-        joined = join_sources([Source(md_path)], {}, {}, md_path.name)
-        metadata = joined.metadata
-        if not metadata.title:
-            metadata = replace(metadata, title=joined.first_heading or md_path.stem)
-        return render_output(
-            self.fmt, joined, metadata, Path(output_path), md_path.name, [md_path.parent], self.template_path,
-            self.options, self.runtime, keep_going=False,
-        )  # fmt: skip
+        return self._render(md_path, output_path, self.fmt, self.template_path, self.options)
 
     def convert_twin(self, md_path: Path, output_path: Path) -> Path:
-        """Render an HTML preview twin of the document or presentation."""
+        """Write an HTML preview twin of the document or deck: the same Markdown, as a web page, for ``--watch``."""
+        return self._render(md_path, output_path, "html", None, {**self.options, "preview": True})
+
+    def _render(self, md_path: Path, output_path: Path, fmt: str, template: Path | None, options: dict) -> Path:
         md_path = Path(md_path).resolve()
         if not md_path.is_file():
             raise FileNotFoundError(f"Markdown file not found: {md_path}")
         joined = join_sources([Source(md_path)], {}, {}, md_path.name)
-        if self.fmt == "pptx":
+        if self.fmt == "pptx" and fmt == "html":  # speaker notes written as comments show in the twin too
             from .pandoc.pptx_finish import notes_to_divs
 
             joined = replace(joined, parts=[(src, notes_to_divs(md)) for src, md in joined.parts])
@@ -86,8 +79,8 @@ def convert_twin(self, md_path: Path, output_path: Path) -> Path:
         if not metadata.title:
             metadata = replace(metadata, title=joined.first_heading or md_path.stem)
         return render_output(
-            "html", joined, metadata, Path(output_path), md_path.name, [md_path.parent], None,
-            self.options, self.runtime, keep_going=False,
+            fmt, joined, metadata, Path(output_path), md_path.name, [md_path.parent], template,
+            options, self.runtime, keep_going=False,
         )  # fmt: skip
 
 
diff --git a/src/py_doc/errors.py b/src/py_doc/errors.py
index c90d2c8..e9405f5 100644
--- a/src/py_doc/errors.py
+++ b/src/py_doc/errors.py
@@ -12,6 +12,10 @@ class EnvironmentProblem(ConversionError):
     """
 
 
+class OutputLocked(ConversionError):
+    """The output file cannot be written because another program, such as Word, has it open."""
+
+
 def exit_status(error: BaseException) -> int:
     """The exit status for a failure: 2 for an environment problem, 1 for anything else."""
     return 2 if isinstance(error, EnvironmentProblem) else 1
diff --git a/src/py_doc/pandoc/engine.py b/src/py_doc/pandoc/engine.py
index 9c8feae..e8441e7 100644
--- a/src/py_doc/pandoc/engine.py
+++ b/src/py_doc/pandoc/engine.py
@@ -14,7 +14,7 @@
 import yaml
 
 from py_doc.diagrams import copy_pictures
-from py_doc.errors import ConversionError
+from py_doc.errors import ConversionError, OutputLocked
 from py_doc.files import template_source
 from py_doc.markdown import Metadata
 from py_doc.runtime import Mount, Runtime
@@ -160,6 +160,8 @@ def _command(job: PandocJob, runtime: Runtime, work: Path, reference: Path | Non
     elif fmt == "html":
         argv += ["--to=html5", "--standalone", "--embed-resources", "--mathml"]
         argv += ["--css", job.template if job.template is not None else _required(RESOURCES / "html.css", "stylesheet")]
+        if options.get("preview", False):  # the HTML twin of a document or deck, for --watch
+            argv += ["--css", _required(RESOURCES / "preview.css", "stylesheet")]
         if options.get("toc", False):
             argv.append("--toc")
     else:  # pdf
@@ -216,7 +218,7 @@ def convert(runtime: Runtime, job: PandocJob) -> Path:
             job.output.parent.mkdir(parents=True, exist_ok=True)
             shutil.move(produced, job.output)
         except PermissionError as exc:
-            raise ConversionError(f"Cannot write {job.output}: it is locked (open in another program?)") from exc
+            raise OutputLocked(f"Cannot write {job.output}: it is locked (open in another program?)") from exc
         except OSError as exc:
             raise ConversionError(f"Cannot write '{job.output}': {exc.strerror or exc}") from exc
     logger.info(f"Wrote {job.output}")
diff --git a/src/py_doc/pandoc/resources/html.css b/src/py_doc/pandoc/resources/html.css
index 6831a51..567b4b7 100644
--- a/src/py_doc/pandoc/resources/html.css
+++ b/src/py_doc/pandoc/resources/html.css
@@ -12,13 +12,4 @@ div.tip { background: #e8f5e9; border-color: #2e7d32; }
 div.important { background: #f1ecf9; border-color: #6a3fb5; }
 div.warning { background: #fff4e0; border-color: #e08a00; }
 div.caution { background: #fce8e8; border-color: #c62828; }
-figure { margin: 1.5em 0; text-align: center; }
-figcaption { font-size: 0.9em; color: #4b5563; margin-top: 0.5em; font-style: italic; }
-caption { font-size: 0.9em; font-weight: 600; color: #003c64; padding-bottom: 0.5em; text-align: left; }
-div.notes { background: #f1f5f9; border-left: 4px solid #64748b; border-radius: 4px; padding: 0.5em 1em; margin: 1.2em 0; font-size: 0.9em; color: #334155; }
-div.notes > p:first-child::before { content: "📝 Speaker Note: "; font-weight: 600; color: #1e293b; }
-div.columns { display: flex; gap: 1.5em; margin: 1em 0; }
-div.column { flex: 1; min-width: 0; }
-hr.pagebreak, hr.pydoc-pagebreak { border: none; border-top: 2px dashed #cbd5e1; margin: 2em 0; position: relative; }
-hr.pagebreak::after, hr.pydoc-pagebreak::after { content: "Page Break"; position: absolute; right: 0; top: -0.8em; background: #fff; padding: 0 0.5em; font-size: 0.75em; color: #94a3b8; text-transform: uppercase; letter-spacing: 0.05em; }
 @media print { h1, h2, h3 { break-after: avoid; } pre, table, img { break-inside: avoid; } }
diff --git a/src/py_doc/pandoc/resources/pagebreak.lua b/src/py_doc/pandoc/resources/pagebreak.lua
index c2235b7..48624da 100644
--- a/src/py_doc/pandoc/resources/pagebreak.lua
+++ b/src/py_doc/pandoc/resources/pagebreak.lua
@@ -8,7 +8,7 @@ function Div(el)
   if FORMAT:match("latex") then
     return pandoc.RawBlock("latex", "\\newpage")
   elseif FORMAT:match("html") then
-    return pandoc.RawBlock("html", '<div style="break-after: page"></div>')
+    return pandoc.RawBlock("html", '<div class="pagebreak" style="break-after: page"></div>')
   elseif FORMAT:match("docx") then
     return pandoc.RawBlock("openxml", '<w:p><w:r><w:br w:type="page"/></w:r></w:p>')
   elseif FORMAT:match("pptx") then
diff --git a/src/py_doc/pandoc/resources/preview.css b/src/py_doc/pandoc/resources/preview.css
new file mode 100644
index 0000000..3c04df4
--- /dev/null
+++ b/src/py_doc/pandoc/resources/preview.css
@@ -0,0 +1,12 @@
+/* Added after html.css for the HTML preview twin of `py-doc docx|slides --watch` only, so the twin shows
+   what a Word document or deck has that a web page does not: page breaks, speaker notes and columns. */
+figure { margin: 1.5em 0; text-align: center; }
+figcaption { font-size: 0.9em; color: #4b5563; margin-top: 0.5em; font-style: italic; }
+caption { font-size: 0.9em; font-weight: 600; color: #003c64; padding-bottom: 0.5em; text-align: left; }
+div.notes { background: #f1f5f9; border-left: 4px solid #64748b; border-radius: 4px; padding: 0.5em 1em; margin: 1.2em 0; font-size: 0.9em; color: #334155; }
+div.notes > p:first-child::before { content: "📝 Speaker note: "; font-weight: 600; color: #1e293b; }
+div.columns { display: flex; gap: 1.5em; margin: 1em 0; }
+div.column { flex: 1; min-width: 0; }
+div.pagebreak { border-top: 2px dashed #cbd5e1; margin: 2em 0; position: relative; }
+div.pagebreak::after { content: "Page break"; position: absolute; right: 0; top: -0.8em; background: #fff; padding: 0 0.5em; font-size: 0.75em; color: #94a3b8; text-transform: uppercase; letter-spacing: 0.05em; }
+@media print { div.pagebreak { border: none; margin: 0; } div.pagebreak::after { content: none; } }
diff --git a/src/py_doc/poster_watch.py b/src/py_doc/poster_watch.py
index 7124fea..2ce143f 100644
--- a/src/py_doc/poster_watch.py
+++ b/src/py_doc/poster_watch.py
@@ -14,6 +14,7 @@
 import os
 import threading
 import time
+import urllib.parse
 import webbrowser
 from collections.abc import Callable
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
@@ -81,7 +82,7 @@ def serve(state: State, port: int) -> ThreadingHTTPServer:
 
     class Handler(BaseHTTPRequestHandler):
         def do_GET(self):  # noqa: N802 (the name http.server calls)
-            path = self.path.split("?", 1)[0]
+            path = urllib.parse.unquote(self.path.split("?", 1)[0])
             with state.lock:
                 pages, version, error = dict(state.pages), state.version, state.error
             if path == "/__status":
@@ -94,9 +95,9 @@ def do_GET(self):  # noqa: N802 (the name http.server calls)
                 script = RELOAD.replace("__VERSION__", str(version))
                 return self._send(200, "text/html; charset=utf-8", page.replace("</body>", script + "</body>", 1))
             if not name:
-                links = "".join(f'<li><a href="/{html.escape(n)}.html">{html.escape(n)}</a></li>' for n in pages)
-                return self._send(200, "text/html; charset=utf-8", f"<!doctype html><title>{state.title}</title><ul>{links}</ul>")
-            self._send(404, "text/plain", f"No poster {name}")
+                links = "".join(f'<li><a href="/{html.escape(urllib.parse.quote(n))}.html">{html.escape(n)}</a></li>' for n in pages)
+                return self._send(200, "text/html; charset=utf-8", f"<!doctype html><title>{html.escape(state.title)}</title><ul>{links}</ul>")
+            self._send(404, "text/plain", f"No page {name}")
 
         def _send(self, code: int, kind: str, body: str) -> None:
             data = body.encode("utf-8")
diff --git a/tests/test_cli.py b/tests/test_cli.py
index dcf386a..f915f92 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -303,7 +303,8 @@ def test_docx_watch_mode(self, tmp_path, monkeypatch):
         from py_doc import poster_watch
 
         src = tmp_path / "spec.md"
-        src.write_text("# Spec\n\nText\n", encoding="utf-8")
+        src.write_text("# Spec\n\nText\n\n::: {.pagebreak}\n:::\n\nMore\n", encoding="utf-8")
+        (tmp_path / "spec.html").write_text("mine", encoding="utf-8")
 
         called = []
 
@@ -317,9 +318,49 @@ def fake_watch(build, errors, port=0, open_browser=True, stop=None, interval=0.5
         assert code == 0
         assert len(called) == 1
         pages, sources, port, open_browser, title = called[0]
-        assert "spec" in pages
-        assert pages["spec"].is_file()
+        assert pages == {"spec": (tmp_path / ".py-doc" / "preview" / "spec.html").resolve()}
         assert (tmp_path / "spec.docx").is_file()
+        assert (tmp_path / "spec.html").read_text(encoding="utf-8") == "mine"  # a file of the user's is left alone
         assert port == 9876
         assert open_browser is False
         assert "Word Preview" in title
+        twin = pages["spec"].read_text(encoding="utf-8")
+        assert 'class="pagebreak"' in twin and "Page break" in twin  # preview.css is in the twin
+
+    def test_docx_watch_keeps_files_of_the_same_name_apart(self, tmp_path, monkeypatch):
+        from py_doc import poster_watch
+        from py_doc.cli import run_docx
+
+        for folder in ("a", "b"):
+            (tmp_path / folder).mkdir()
+            (tmp_path / folder / "readme.md").write_text(f"# {folder}\n", encoding="utf-8")
+        called = []
+        monkeypatch.setattr(poster_watch, "watch", lambda build, errors, **kw: called.append(build()[0]) or 0)
+        assert run_docx([str(tmp_path), "--watch", "--no-open"]) == 0
+        assert sorted(called[0]) == ["a/readme", "b/readme"]
+
+    def test_docx_watch_builds_the_twin_of_a_document_open_in_word(self, tmp_path, monkeypatch, capsys):
+        from py_doc import convert, poster_watch
+        from py_doc.cli import run_docx
+        from py_doc.errors import OutputLocked
+
+        src = tmp_path / "spec.md"
+        src.write_text("# Spec\n", encoding="utf-8")
+
+        def locked(self, md_path, output_path):
+            raise OutputLocked(f"Cannot write {output_path}: it is locked")
+
+        monkeypatch.setattr(convert.DocxConverter, "convert_file", locked)
+        called = []
+        monkeypatch.setattr(poster_watch, "watch", lambda build, errors, **kw: called.append(build()[0]) or 0)
+        assert run_docx([str(src), "--watch", "--no-open"]) == 0
+        assert called[0]["spec"].is_file()
+        assert "is open in Word" in capsys.readouterr().err
+
+    def test_port_without_watch_is_reported(self, tmp_path, capsys):
+        from py_doc.cli import run_docx
+
+        src = tmp_path / "spec.md"
+        src.write_text("# Spec\n", encoding="utf-8")
+        assert run_docx([str(src), "--port", "9000"]) == 0
+        assert "only apply with --watch" in capsys.readouterr().err
diff --git a/tests/test_slides_cli.py b/tests/test_slides_cli.py
index 1a7a79f..c77044a 100644
--- a/tests/test_slides_cli.py
+++ b/tests/test_slides_cli.py
@@ -108,7 +108,7 @@ def test_slides_watch_mode(tmp_path, monkeypatch):
     from py_doc import poster_watch
 
     src = tmp_path / "deck.md"
-    src.write_text("# Deck\n\n## S1\n\n- a\n", encoding="utf-8")
+    src.write_text("# Deck\n\n## S1\n\n- a\n\n<!-- notes: Say this -->\n", encoding="utf-8")
 
     called = []
 
@@ -122,9 +122,10 @@ def fake_watch(build, errors, port=0, open_browser=True, stop=None, interval=0.5
     assert code == 0
     assert len(called) == 1
     pages, sources, port, open_browser, title = called[0]
-    assert "deck" in pages
-    assert pages["deck"].is_file()
+    assert pages == {"deck": (tmp_path / ".py-doc" / "preview" / "deck.html").resolve()}
     assert (tmp_path / "deck.pptx").is_file()
     assert port == 9875
     assert open_browser is False
     assert "PowerPoint Preview" in title
+    twin = pages["deck"].read_text(encoding="utf-8")
+    assert 'class="notes"' in twin and "Say this" in twin

From 9dd85177309d261a12d8f9a51931568fced628e8 Mon Sep 17 00:00:00 2001
From: Mark Bacon <mark@bacon.me.uk>
Date: Wed, 21 Oct 2026 15:18:55 +0100
Subject: [PATCH 3/6] Live preview: child process, slide boxes, shared cases,
 js-yaml, module split

- The VS Code extension runs py-doc --watch as a child process instead of in
  a terminal. py-doc picks a free port and the extension reads the address
  from its "serving" line, so windows never fight over a port. Output goes
  to an output channel, failures are reported, and stopping ends the whole
  process tree. New pydoc.executable setting; pydoc.watch.port defaults to 0.
- The HTML twin of a deck shows each slide as a numbered 16:9 box, split
  where PowerPoint splits it (slides-preview.lua, split level and breaks).
- Shared preview cases (tests/fixtures/preview/cases.json) run through both
  the instant preview and the HTML twin, so the two cannot drift apart.
- Front matter is read with js-yaml (core schema) instead of a hand parser.
- extension.js is split into src/ modules (plugin, detect, frontmatter, text,
  watch), with ESLint, node --test and tests for the live preview.
- Ready to package: license, icon, repository, bugs and homepage fields; the
  .vsix keeps js-yaml and leaves out dev dependencies. Install docs added.
- poster_watch.py is now watch.py, as it serves docx and slides too.
- CI lints the extension; docs, model and traceability updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      |    3 +-
 README.md                                     |    4 +-
 docs/architecture/02_pipeline.md              |    8 +-
 docs/architecture/05_decisions.md             |    2 +-
 docs/architecture/workspace.dsl               |    4 +-
 docs/guide/02_projects.md                     |    2 +-
 docs/requirements/04_traceability.md          |    6 +-
 editors/vscode/.vscodeignore                  |    2 +-
 editors/vscode/LICENSE                        |   21 +
 editors/vscode/README.md                      |   56 +-
 editors/vscode/eslint.config.js               |   23 +
 editors/vscode/extension.js                   |  883 +------------
 editors/vscode/images/icon.png                |  Bin 0 -> 6651 bytes
 editors/vscode/package-lock.json              | 1120 ++++++++++++++++-
 editors/vscode/package.json                   |   34 +-
 editors/vscode/src/detect.js                  |   43 +
 editors/vscode/src/frontmatter.js             |   21 +
 editors/vscode/src/plugin.js                  |  679 ++++++++++
 editors/vscode/src/text.js                    |   25 +
 editors/vscode/src/watch.js                   |  121 ++
 editors/vscode/test/cases.test.js             |   39 +
 editors/vscode/test/watch.test.js             |   98 ++
 src/py_doc/_cli.py                            |    2 +-
 src/py_doc/convert.py                         |    3 +-
 src/py_doc/pandoc/engine.py                   |    5 +-
 src/py_doc/pandoc/resources/preview.css       |   10 +-
 .../pandoc/resources/slides-preview.lua       |   39 +
 src/py_doc/poster_cli.py                      |    2 +-
 src/py_doc/{poster_watch.py => watch.py}      |    6 +-
 tests/fixtures/preview/cases.json             |   30 +
 tests/test_cli.py                             |   13 +-
 tests/test_logging_policy.py                  |    2 +-
 tests/test_poster.py                          |   12 +-
 tests/test_preview_cases.py                   |   41 +
 tests/test_slides_cli.py                      |   20 +-
 35 files changed, 2458 insertions(+), 921 deletions(-)
 create mode 100644 editors/vscode/LICENSE
 create mode 100644 editors/vscode/eslint.config.js
 create mode 100644 editors/vscode/images/icon.png
 create mode 100644 editors/vscode/src/detect.js
 create mode 100644 editors/vscode/src/frontmatter.js
 create mode 100644 editors/vscode/src/plugin.js
 create mode 100644 editors/vscode/src/text.js
 create mode 100644 editors/vscode/src/watch.js
 create mode 100644 editors/vscode/test/cases.test.js
 create mode 100644 editors/vscode/test/watch.test.js
 create mode 100644 src/py_doc/pandoc/resources/slides-preview.lua
 rename src/py_doc/{poster_watch.py => watch.py} (95%)
 create mode 100644 tests/fixtures/preview/cases.json
 create mode 100644 tests/test_preview_cases.py

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e3511e4..b9efb7e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -123,7 +123,8 @@ jobs:
         working-directory: editors/vscode
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - run: npm ci --ignore-scripts  # the runner's own Node; markdown-it is the only (dev) dependency
+      - run: npm ci --ignore-scripts  # the runner's own Node
+      - run: npm run lint
       - run: npm test
 
   gate:
diff --git a/README.md b/README.md
index 73378a6..c9e863f 100644
--- a/README.md
+++ b/README.md
@@ -100,7 +100,7 @@ src/
 │   ├── migrate.py        # createdocs to py-doc.yml
 │   ├── report.py         # the JSON build report
 │   ├── poster*.py        # py-doc poster: Markdown to an HTML poster, its blocks, settings, themes and fonts
-│   └── poster_watch.py   # the --watch loop and preview server of poster, docx and slides
+│   └── watch.py          # the --watch loop and preview server of poster, docx and slides
 ├── pydoc2docx/           # old import names, kept as aliases
 ├── pydoc2slides/
 └── pydoclint/
@@ -117,7 +117,7 @@ pip install -e ".[dev]"
 python -m pytest
 ruff check .
 py-doc lint docs --strict
-cd editors/vscode && npm ci && npm test   # the VS Code extension
+cd editors/vscode && npm ci && npm run lint && npm test   # the VS Code extension
 ```
 
 CI runs on Linux and Windows with Python 3.14, the newest supported. Python 3.10, the oldest supported, is not tested in CI. macOS is not supported.
diff --git a/docs/architecture/02_pipeline.md b/docs/architecture/02_pipeline.md
index d3044e2..d99d6b2 100644
--- a/docs/architecture/02_pipeline.md
+++ b/docs/architecture/02_pipeline.md
@@ -63,7 +63,7 @@ flowchart LR
 - **Generators** (`generators/`): each entry of `content.generators` returns Markdown, written only when it changes. The built-in types are in `generators/builtin.py`, and others are found through the `py_doc.generators` entry point group, so the core depends on none of their tools. They run before anything reads the sources, because the files they write are sources.
 - **Lint** (`lint/`): with `build.lint` or `--lint`, the sources of the documents being built are linted before anything is written, and the issues can go to a SARIF, JSON or CSV file for CI (`lint/formats.py`).
 - **Documents and bundles**: a bundle is a document whose sources are those of its documents, so it takes the same path.
-- **Posters** (`poster*.py`): every poster under `posters:`, one self-contained HTML page each, with its PDF when it asks for one. The settings come in layers (`poster_settings.py`): `poster:`, the front matter, the poster's entry, then the command line. The page is built in Python, with diagrams through the same cache as the documents. A script in the page balances the columns by measured height and fits the poster to its paper. The PDF is that page printed by the container's Chromium (`diagrams/tools/poster_pdf.js`), from a copy with the web fonts inside, as the container has no network. `py-doc poster --watch` (`poster_watch.py`) runs the same build on every save and serves the page with a script that reloads it.
+- **Posters** (`poster*.py`): every poster under `posters:`, one self-contained HTML page each, with its PDF when it asks for one. The settings come in layers (`poster_settings.py`): `poster:`, the front matter, the poster's entry, then the command line. The page is built in Python, with diagrams through the same cache as the documents. A script in the page balances the columns by measured height and fits the poster to its paper. The PDF is that page printed by the container's Chromium (`diagrams/tools/poster_pdf.js`), from a copy with the web fonts inside, as the container has no network. `py-doc poster --watch` (`watch.py`) runs the same build on every save and serves the page with a script that reloads it.
 - **Site** (`site/`): with `build.site` or `--site`, the pages are written and the site tool runs. The posters `site.posters` names are built into it as pages of their own.
 - **Check outputs**: every file the build wrote is there and not empty.
 
@@ -71,9 +71,9 @@ flowchart LR
 
 ## Live previews
 
-`--watch` on `py-doc poster`, `py-doc docx` and `py-doc slides` runs one loop (`poster_watch.py`). It builds, then serves the pages on 127.0.0.1 from a thread of its own. Every half second it looks at the modification times of the source files: the Markdown, includes, pictures, diagram sources and templates below the folders of the sources. The pages it wrote and hidden folders are not watched. A change builds again. Each page is served with a small script that asks `/__status` whether a newer build is there and reloads when it is, so the files written are the same as without `--watch`. A build that fails keeps the last good page and shows its error over it.
+`--watch` on `py-doc poster`, `py-doc docx` and `py-doc slides` runs one loop (`watch.py`). It builds, then serves the pages on 127.0.0.1 from a thread of its own. Every half second it looks at the modification times of the source files: the Markdown, includes, pictures, diagram sources and templates below the folders of the sources. The pages it wrote and hidden folders are not watched. A change builds again. Each page is served with a small script that asks `/__status` whether a newer build is there and reloads when it is, so the files written are the same as without `--watch`. A build that fails keeps the last good page and shows its error over it.
 
-A poster is already a web page. A Word document or deck is not, so `docx` and `slides` (`_cli.py`) also write an *HTML twin* of each file (`convert.py`, `convert_twin`). The twin is the same Markdown through the same pipeline to pandoc's HTML. It adds `preview.css` after `html.css` to show page breaks, speaker notes and columns. The twins go to `.py-doc/preview/` below the input's folder and are served by their path. No file of the user's is overwritten, and two `readme.md` in different folders stay apart. When Word or PowerPoint has the output open, the engine raises `OutputLocked`; the watch loop warns and still writes the twin.
+A poster is already a web page. A Word document or deck is not, so `docx` and `slides` (`_cli.py`) also write an *HTML twin* of each file (`convert.py`, `convert_twin`). The twin is the same Markdown through the same pipeline to pandoc's HTML. It adds `preview.css` after `html.css` to show page breaks, speaker notes and columns. The twin of a deck also runs `slides-preview.lua`, which puts each slide in a box. A box starts where pandoc's PowerPoint writer starts a slide: at headings up to the split level and at page breaks. The twins go to `.py-doc/preview/` below the input's folder and are served by their path. No file of the user's is overwritten, and two `readme.md` in different folders stay apart. When Word or PowerPoint has the output open, the engine raises `OutputLocked`; the watch loop warns and still writes the twin.
 
-The VS Code extension (`editors/vscode`) is outside the Python package. Its instant preview is a markdown-it plugin in the editor and runs no tool. Its live preview starts `py-doc <command> --watch` in a terminal, waits until `/__status` answers, and opens the served page in VS Code's Simple Browser. The extension and the instant preview choose the command with one function, from the front matter and the blocks only a deck has.
+The VS Code extension (`editors/vscode`) is outside the Python package. Its instant preview is a markdown-it plugin in the editor and runs no tool. Its live preview (`src/watch.js`) runs `py-doc <command> --watch --no-open` as a child process, with the output in an output channel. py-doc picks a free port, and the extension reads the address from the `serving` line it prints, then opens it in VS Code's Simple Browser. Stopping the preview ends the whole process tree. The extension and the instant preview choose the command with one function (`src/detect.js`), from the front matter and the blocks only a deck has.
 
diff --git a/docs/architecture/05_decisions.md b/docs/architecture/05_decisions.md
index c17a45f..7f3a7f5 100644
--- a/docs/architecture/05_decisions.md
+++ b/docs/architecture/05_decisions.md
@@ -52,5 +52,5 @@ Each decision records the context, the choice and its consequences.
 
 - **Context**: authors want to see a document while they write it, but Word and PowerPoint have no live view, a document open in Word cannot be written, and the in-editor Markdown preview cannot draw most diagrams.
 - **Decision**: `--watch` builds an HTML twin of each document with the same pipeline, keeps it in `.py-doc/preview`, and serves it with a reload script added as it is served. The VS Code extension runs that command; its own instant preview is an approximation for typing.
-- **Consequences**: the preview shows every diagram exactly as the build draws it, and a document open in Word does not stop it. It is one HTML page, so slide boundaries and Word page layout are not shown, and a first build waits for the tool container.
+- **Consequences**: the preview shows every diagram exactly as the build draws it, and a document open in Word does not stop it. It is one HTML page: slides are boxes and page breaks are lines, but Word's page layout is not shown, and a first build waits for the tool container.
 
diff --git a/docs/architecture/workspace.dsl b/docs/architecture/workspace.dsl
index 0cf3517..d3ed7f4 100644
--- a/docs/architecture/workspace.dsl
+++ b/docs/architecture/workspace.dsl
@@ -29,7 +29,7 @@ workspace "py-doc" "The C4 model of py-doc, the Markdown technical documentation
                 watch = component "Live preview" "With --watch, builds documents, decks and posters again on every save, writes an HTML twin of each document and deck, and serves the pages on 127.0.0.1 with a script that reloads them." "Python, http.server"
             }
             toolImage = container "Tool image" "Every program that is not Python: pandoc, XeLaTeX, PlantUML, Mermaid, Graphviz, the diagram tools, Chromium, structurizr-cli, Vale, markdownlint, MkDocs and Node." "Docker image on Debian 12"
-            vscode = container "VS Code extension" "Previews py-doc Markdown in the editor as it is typed, and starts the live preview of the open file and shows it beside the editor." "JavaScript, markdown-it"
+            vscode = container "VS Code extension" "Previews py-doc Markdown in the editor as it is typed, and starts the live preview of the open file and shows it beside the editor." "JavaScript, markdown-it, js-yaml"
             local = container "Structurizr Local" "Shows a workspace in a browser to view it and arrange its views, and draws the pictures for documents." "Docker image structurizr/structurizr"
             cache = container "Caches" "Diagram pictures (user cache folder), Structurizr exports, generated chapters and live preview pages (.py-doc in the project)." "Files" "Store"
         }
@@ -38,7 +38,7 @@ workspace "py-doc" "The C4 model of py-doc, the Markdown technical documentation
         author -> pydoc.local "Views the model and arranges its views" "Browser, HTTP"
         reader -> office "Opens the documents in"
         author -> pydoc.vscode "Writes and previews documents in" "VS Code"
-        pydoc.vscode -> pydoc.cli.commands "Starts py-doc docx, slides or poster --watch for the open file" "Terminal"
+        pydoc.vscode -> pydoc.cli.commands "Starts py-doc docx, slides or poster --watch for the open file" "Child process"
         pydoc.vscode -> pydoc.cli.watch "Shows the served preview from" "HTTP on 127.0.0.1"
         pydoc.cli.commands -> pydoc.cli.watch "Runs --watch with"
         pydoc.cli.watch -> pydoc.cli.pipeline "Builds each document and its HTML twin with"
diff --git a/docs/guide/02_projects.md b/docs/guide/02_projects.md
index c1bf828..72691d1 100644
--- a/docs/guide/02_projects.md
+++ b/docs/guide/02_projects.md
@@ -174,7 +174,7 @@ A file that uses `[[IF:]]` needs its conditions defined, and only `py-doc build`
 `--watch` builds the files, then builds them again whenever a source below their folder changes: the Markdown, an included file, a picture, a diagram source or the template. Next to each `.docx` or `.pptx` it writes an HTML twin of the same Markdown, to `.py-doc/preview/` below the input's folder, and serves the twins on this computer only. The page in the browser reloads after each build, and a build that fails shows its error over the last good page.
 
 - A document open in Word or PowerPoint cannot be written, so it is left as it is, with a warning, and its preview is still updated.
-- The twin shows page breaks as dashed lines, speaker notes in boxes and columns side by side. It is one page: a deck is not split into slides.
+- The twin shows page breaks as dashed lines, speaker notes in boxes and columns side by side. The twin of a deck shows each slide as a numbered 16:9 box, split as PowerPoint splits it.
 - The twin is a preview, not an output. Build HTML with `py-doc build` and `outputs: html`.
 
 The [VS Code extension](03_writing.md#vs-code-preview) starts `--watch` for the open file and shows the preview beside it.
diff --git a/docs/requirements/04_traceability.md b/docs/requirements/04_traceability.md
index f4f2930..24fba2c 100644
--- a/docs/requirements/04_traceability.md
+++ b/docs/requirements/04_traceability.md
@@ -19,9 +19,9 @@ title: Traceability
 | FR-080 to FR-086, QR-081 | `c4/` | `test_c4.py` |
 | FR-100 to FR-106 | `lint/`, `markdown/` | `test_lint.py`, `test_lint_cli.py`, `test_structure.py`, `test_vale.py`, `test_markdownlint.py`, `test_markdown_ast.py` |
 | FR-120 to FR-127, QR-082 | `site/`, `pandoc/resources/site.lua` | `test_site.py` |
-| FR-130 to FR-139, FR-150 to FR-160 | `poster.py`, `poster_blocks.py`, `poster_fonts.py`, `poster_settings.py`, `poster_themes.py`, `poster_cli.py`, `poster_watch.py`, `config.py`, `app.py`, `lint/linter.py`, `diagrams/tools/poster_pdf.js` | `test_poster.py`, `test_poster_browser.py` |
-| FR-161 | `_cli.py`, `convert.py`, `poster_watch.py`, `pandoc/engine.py`, `pandoc/resources/preview.css` | `test_cli.py`, `test_slides_cli.py`, `test_convert.py` |
-| FR-162 | `editors/vscode/extension.js` | `editors/vscode/test/test.js` |
+| FR-130 to FR-139, FR-150 to FR-160 | `poster.py`, `poster_blocks.py`, `poster_fonts.py`, `poster_settings.py`, `poster_themes.py`, `poster_cli.py`, `watch.py`, `config.py`, `app.py`, `lint/linter.py`, `diagrams/tools/poster_pdf.js` | `test_poster.py`, `test_poster_browser.py` |
+| FR-161 | `_cli.py`, `convert.py`, `watch.py`, `pandoc/engine.py`, `pandoc/resources/preview.css`, `pandoc/resources/slides-preview.lua` | `test_cli.py`, `test_slides_cli.py`, `test_convert.py`, `test_preview_cases.py` |
+| FR-162 | `editors/vscode/extension.js`, `editors/vscode/src/` | `editors/vscode/test/`, `test_preview_cases.py` |
 | FR-028 | `diagrams/render.py`, `config.py` | `test_diagrams.py` |
 | FR-128 | `site/pages.py`, `site/engines.py` | `test_site.py` |
 | FR-140 to FR-143, QR-040 to QR-043 | `runtime/`, `tools_cli.py` | `test_runtime.py`, `test_image.py`, `test_setup.py`, `test_doctor.py`, `test_platform.py` |
diff --git a/editors/vscode/.vscodeignore b/editors/vscode/.vscodeignore
index bf57179..57df9cf 100644
--- a/editors/vscode/.vscodeignore
+++ b/editors/vscode/.vscodeignore
@@ -1,5 +1,5 @@
 .vscode/**
 .git/**
-node_modules/**
 test/**
+eslint.config.js
 .vscodeignore
diff --git a/editors/vscode/LICENSE b/editors/vscode/LICENSE
new file mode 100644
index 0000000..e9513c5
--- /dev/null
+++ b/editors/vscode/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Bacon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/editors/vscode/README.md b/editors/vscode/README.md
index 7e240b7..8b14af5 100644
--- a/editors/vscode/README.md
+++ b/editors/vscode/README.md
@@ -17,7 +17,7 @@ This extension provides two complementary ways to preview your documents:
 | **Docker / Tooling** | **Zero dependencies**, 100% offline pure JavaScript | Uses `py-doc`'s tool container via Pandoc |
 | **Formats Supported** | Technical Documents, Slide Decks, Posters | Technical Documents (`docx`), Slide Decks (`slides`), Posters (`poster`) |
 | **Diagrams** | Live client SVG preview for Mermaid, PlantUML syntax cards | Full 100% compilation of all 12 diagram engines (Mermaid, PlantUML, Graphviz, Ditaa, Wavedrom, Vega, Pikchr, Bytefield, etc.) |
-| **Where it Displays** | Native VS Code Markdown preview pane | Side-by-side inside VS Code via `Simple Browser` or external browser |
+| **Where it Displays** | Native VS Code Markdown preview pane | Side-by-side inside VS Code via `Simple Browser`, on a free local port |
 | **File Lock Tolerance** | Never touches output files | Skips a `.docx`/`.pptx` open in Word or PowerPoint, with a warning, and still updates the HTML twin |
 
 ---
@@ -31,11 +31,11 @@ When you run `py-doc` with `--watch` (or click `👁️` in VS Code):
    - The twin is written to `.py-doc/preview/` below the document's folder, so no file of yours is overwritten.
 2. **Slide Decks (`py-doc slides deck.md --watch`)**:
    - Rebuilds `deck.pptx` on save (PowerPoint locks are handled the same way).
-   - Builds an HTML twin of the deck's content as one continuous page: columns side by side, and speaker notes (`::: notes` / `<!-- notes: ... -->`) in labelled boxes. It does not split the content into slides; use the instant preview for slide layout.
+   - Builds an HTML twin of the deck: each slide a numbered 16:9 box, split where PowerPoint splits it (headings up to `--split-level`, and page breaks), with columns side by side and speaker notes (`::: notes` / `<!-- notes: ... -->`) in labelled boxes.
 3. **Posters (`py-doc poster poster.md --watch`)**:
    - Rebuilds the self-contained poster HTML file on save with true vector graphics and barcodes.
 
-Every format is served at `http://127.0.0.1:8765` (the `pydoc.watch.port` setting) and reloads on each save.
+py-doc serves the preview on a free local port and the page reloads on each save. Its output is in the **py-doc live preview** output channel.
 
 The `👁️` button chooses the command from the file itself, the same way the instant preview chooses its mode:
 - **Poster**: the front matter has a poster setting (`paper`, `byline`, `orientation`, `theme`, `columns`, `width`, `colours`, `palette`, `logo`, `embed_fonts`).
@@ -96,6 +96,30 @@ When authoring a poster (a poster setting such as `paper: a1` or `byline: ...` i
 
 ---
 
+## Install
+
+The extension is not on the Marketplace yet. Build it and install the file:
+
+```bash
+cd editors/vscode
+npm ci
+npx @vscode/vsce package          # writes vscode-py-doc-preview-<version>.vsix
+code --install-extension vscode-py-doc-preview-*.vsix
+```
+
+The live preview needs py-doc itself (`pip install -e .` at the root of this repository, and Docker).
+
+---
+
+## Settings
+
+| Setting | Default | What it does |
+|:---|:---|:---|
+| `pydoc.executable` | `py-doc` | The py-doc program the live preview runs. Set it to the `py-doc` of a virtual environment (`.venv/Scripts/py-doc.exe` on Windows, `.venv/bin/py-doc` elsewhere) when it is not on the `PATH`. |
+| `pydoc.watch.port` | `0` | The local port of the live preview. `0` lets py-doc pick a free one, so each window can have its own preview. |
+
+---
+
 ## Adding to the `py-doc` Repository
 
 To include this extension as a standard writing tool in the [`markbac/py-doc`](https://github.com/markbac/py-doc) repository:
@@ -105,16 +129,20 @@ Located in `editors/vscode`:
 ```text
 py-doc/
 ├── src/py_doc/
-├── docs/
-├── examples/
+├── tests/fixtures/preview/cases.json   <-- shared by the Python and the extension tests
 └── editors/
-    └── vscode/             <-- VS Code extension
+    └── vscode/                         <-- VS Code extension
         ├── package.json
-        ├── extension.js
-        ├── styles/
-        │   └── py-doc-preview.css
+        ├── extension.js                # activation and commands
+        ├── src/
+        │   ├── plugin.js               # the instant preview (markdown-it plugin)
+        │   ├── detect.js               # which command a file is for
+        │   ├── frontmatter.js          # front matter (js-yaml)
+        │   ├── text.js                 # escaping
+        │   └── watch.js                # the live preview process
+        ├── styles/py-doc-preview.css
+        ├── images/icon.png
         ├── test/
-        │   └── test.js
         └── README.md
 ```
 
@@ -133,7 +161,11 @@ In projects initialized with `py-doc init`, or at the root of `py-doc`:
 ## Running Automated Tests
 
 ```bash
-npm test
+npm ci
+npm run lint   # ESLint
+npm test       # node --test
 ```
 
-Runs all 10 test suites validating documents, slides, posters, image dimensions, diagram features, format auto-detection, and regressions.
+- `test/test.js`: the instant preview of documents, slides and posters, format detection, and regressions.
+- `test/cases.test.js`: the shared cases of `tests/fixtures/preview/cases.json`. The Python tests (`tests/test_preview_cases.py`) run the same cases through the HTML twin that `--watch` builds, so the two previews cannot drift apart.
+- `test/watch.test.js`: the live preview, against a fake `py-doc`.
diff --git a/editors/vscode/eslint.config.js b/editors/vscode/eslint.config.js
new file mode 100644
index 0000000..0155b8f
--- /dev/null
+++ b/editors/vscode/eslint.config.js
@@ -0,0 +1,23 @@
+'use strict';
+
+const js = require('@eslint/js');
+const globals = require('globals');
+
+module.exports = [
+  { ignores: ['node_modules/**'] },
+  js.configs.recommended,
+  {
+    files: ['**/*.js'],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'commonjs',
+      globals: { ...globals.node },
+    },
+    rules: {
+      'no-unused-vars': ['error', { caughtErrors: 'none' }],
+      eqeqeq: ['error', 'always'],
+      'prefer-const': 'error',
+      'no-var': 'error',
+    },
+  },
+];
diff --git a/editors/vscode/extension.js b/editors/vscode/extension.js
index dae3179..7a3c8d1 100644
--- a/editors/vscode/extension.js
+++ b/editors/vscode/extension.js
@@ -1,881 +1,58 @@
 /**
- * vscode-py-doc-preview extension
+ * vscode-py-doc-preview: previews of py-doc Markdown in VS Code.
  *
- * Extends VS Code's built-in Markdown preview for all py-doc outputs:
- *  1. Word Technical Documents (.docx):
- *     - Numbered captions: [[CAPTION:Figure]] text, [[CAPTION:Table]] text
- *     - Word callout boxes: > [!NOTE] and > **Note:** text (Note, Tip, Important, Warning, Caution)
- *     - Page breaks: [[PAGEBREAK]] and ::: {.pagebreak}
- *     - Section breaks: [[LANDSCAPE]] and [[PORTRAIT]]
- *     - Paragraph Word styles: [[STYLE:StyleName]] text
- *     - Image width attributes: ![](images/board.png){width=60%}
- *     - Diagram types: plantuml, dot/graphviz, ditaa, wavedrom, vega, bytefield, etc.
- *     - Directives: [[INCLUDE:...]], [[INCLUDE-CODE:...]], [[IF:...]], [[ENDIF]]
- *  2. PowerPoint Slide Decks (.pptx):
- *     - Section Header slides (# Section Title)
- *     - Content slide cards (## Slide Title) with slide footers
- *     - Responsive two-column layouts (:::: columns / ::: column)
- *     - Speaker notes (::: notes and <!-- notes: ... -->)
- *     - Incremental lists (::: incremental)
- *  3. HTML & PDF Posters (py-doc poster):
- *     - Stat strip (## ... {.stats}) with KPI cards & trend indicators
- *     - Abstract introduction banner (## ... {.abstract})
- *     - Headings with colon accent (## 1. Title: Accent) and class stripping
- *     - Card grid blocks (```cards cols=N style=...```)
- *     - Segments bar blocks (```segments```)
- *     - Flow sequence blocks (```flow```)
- *     - Summary closing banner (## ... {.summary})
- *     - Poster header & footer (paper size, byline, QR code label)
+ *  - The instant preview (src/plugin.js) extends VS Code's built-in Markdown preview as you type.
+ *  - The live preview (src/watch.js) runs `py-doc docx|slides|poster --watch` on the open file and shows
+ *    the page it serves beside the editor, rebuilt with every diagram on each save.
+ *  - Both choose the format of a file the same way (src/detect.js).
  */
 
 'use strict';
 
-const KINDS = {
-  NOTE: { title: 'Note', icon: 'ℹ️', class: 'note' },
-  TIP: { title: 'Tip', icon: '💡', class: 'tip' },
-  IMPORTANT: { title: 'Important', icon: '❗', class: 'important' },
-  WARNING: { title: 'Warning', icon: '⚠️', class: 'warning' },
-  CAUTION: { title: 'Caution', icon: '🛑', class: 'caution' },
-};
-
-const DIAGRAM_TYPES = new Set([
-  'mermaid', 'plantuml', 'puml', 'dot', 'graphviz', 'ditaa',
-  'blockdiag', 'seqdiag', 'actdiag', 'nwdiag', 'packetdiag',
-  'wavedrom', 'bytefield-svg', 'pikchr', 'railroad', 'wireviz',
-  'vega', 'vega-lite'
-]);
-
-function parseSimpleYaml(yamlStr) {
-  const result = {};
-  const lines = yamlStr.split('\n');
-  let currentKey = null;
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-
-    const item = trimmed.match(/^-\s+(.*)$/);
-    if (item && currentKey) {
-      if (!Array.isArray(result[currentKey])) result[currentKey] = [];
-      result[currentKey].push(unquote(item[1].trim()));
-      continue;
-    }
-
-    if (line.startsWith('  ') && currentKey) {
-      const subColon = trimmed.indexOf(':');
-      if (subColon > 0) {
-        const subKey = trimmed.slice(0, subColon).trim();
-        const subVal = unquote(trimmed.slice(subColon + 1).trim());
-        if (typeof result[currentKey] !== 'object' || result[currentKey] === null) {
-          result[currentKey] = {};
-        }
-        result[currentKey][subKey] = subVal;
-      }
-      continue;
-    }
-
-    const colonIdx = trimmed.indexOf(':');
-    if (colonIdx > 0) {
-      const key = trimmed.slice(0, colonIdx).trim();
-      const val = unquote(trimmed.slice(colonIdx + 1).trim());
-      currentKey = key;
-      result[key] = val === '' ? {} : val;
-    }
-  }
-  return result;
-}
-
-function unquote(val) {
-  if (val.length >= 2 && ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'")))) {
-    return val.slice(1, -1);
-  }
-  return val;
-}
-
-// Front matter values may be lists (author: [- Jane, - Joe]) or mappings, so anything is turned into text first
-function asText(val) {
-  if (val === null || val === undefined) return '';
-  if (Array.isArray(val)) return val.map(asText).join(', ');
-  if (typeof val === 'object') return Object.values(val).map(asText).join(', ');
-  return String(val);
-}
-
-// A colour name written in the Markdown, made safe to use as part of a class name
-function cssName(val) {
-  return asText(val).toLowerCase().replace(/[^a-z0-9_-]/g, '');
-}
-
-function escapeHtml(val) {
-  const str = asText(val);
-  if (!str) return '';
-  return str.replace(/&/g, '&amp;')
-            .replace(/</g, '&lt;')
-            .replace(/>/g, '&gt;')
-            .replace(/"/g, '&quot;');
-}
-
-function renderFrontMatterBlock(meta, docMode) {
-  if (!meta || Object.keys(meta).length === 0) return '';
-
-  if (docMode === 'poster') {
-    let html = '<div class="pydoc-poster-header">\n';
-    if (meta.title) {
-      html += `  <h1 class="pydoc-poster-title">${escapeHtml(meta.title)}</h1>\n`;
-    }
-    if (meta.subtitle) {
-      html += `  <div class="pydoc-poster-subtitle">${escapeHtml(meta.subtitle)}</div>\n`;
-    }
-    if (meta.byline) {
-      html += `  <div class="pydoc-poster-byline">${escapeHtml(meta.byline)}</div>\n`;
-    }
-    html += '  <div class="pydoc-poster-meta">\n';
-    if (meta.paper) {
-      html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Paper:</span> ${escapeHtml(asText(meta.paper).toUpperCase())}</span>\n`;
-    }
-    if (meta.document_number) {
-      html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Doc #:</span> ${escapeHtml(meta.document_number)}</span>\n`;
-    }
-    if (meta.version) {
-      html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Version:</span> ${escapeHtml(meta.version)}</span>\n`;
-    }
-    html += '  </div>\n';
-    html += '</div>\n';
-    return html;
-  }
-
-  const isSlide = (docMode === 'slide');
-  let html = `<div class="pydoc-frontmatter ${isSlide ? 'pydoc-slide-title' : ''}">\n`;
-  if (meta.title) {
-    html += `  <h1 class="pydoc-doc-title">${escapeHtml(meta.title)}</h1>\n`;
-  }
-  if (meta.subtitle) {
-    html += `  <div class="pydoc-doc-subtitle">${escapeHtml(meta.subtitle)}</div>\n`;
-  }
-  html += '  <div class="pydoc-doc-meta">\n';
-  if (meta.document_number) {
-    html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Doc #:</span> ${escapeHtml(meta.document_number)}</span>\n`;
-  }
-  if (meta.version) {
-    html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Version:</span> ${escapeHtml(meta.version)}</span>\n`;
-  }
-  if (meta.status) {
-    const statusClass = asText(meta.status).toLowerCase() === 'draft' ? 'draft' : 'released';
-    html += `    <span class="pydoc-meta-item pydoc-status-${statusClass}"><span class="pydoc-meta-key">Status:</span> ${escapeHtml(meta.status)}</span>\n`;
-  }
-  if (meta.author) {
-    html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Author:</span> ${escapeHtml(meta.author)}</span>\n`;
-  }
-  if (meta.date) {
-    html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Date:</span> ${escapeHtml(meta.date)}</span>\n`;
-  }
-  html += '  </div>\n';
-  html += '</div>\n';
-  return html;
-}
-
-// Front matter keys only a poster has (see py_doc/poster_settings.py)
-const POSTER_KEYS = ['paper', 'byline', 'orientation', 'theme', 'columns', 'width', 'colours', 'palette', 'embed_fonts', 'logo'];
-const SLIDE_DIVS = /^:{3,4}\s*\{?\.?(columns|column|notes|incremental)\}?\s*$/;
-
-/**
- * Which py-doc command a Markdown file is for: 'poster', 'slides' or 'docx'.
- * Decided from the front matter, then from blocks only a deck has (columns, speaker notes, incremental lists).
- * The instant preview and the live watch button both use this, so they always agree.
- */
-function detectFormat(meta, body) {
-  meta = meta || {};
-  const fmt = asText(meta.format || meta.output || meta.type || meta.layout).toLowerCase();
-  if (fmt.includes('pptx') || fmt.includes('slide') || meta.split_level) return 'slides';
-  if (fmt.includes('poster') || POSTER_KEYS.some((k) => meta[k] !== undefined && meta[k] !== '')) return 'poster';
-
-  let fence = null;
-  for (const line of (body || '').split(/\r?\n/)) {
-    const trimmed = line.trim();
-    const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/);
-    if (fenceMatch) {
-      if (!fence) fence = fenceMatch[1][0];
-      else if (trimmed[0] === fence) fence = null;
-      continue;
-    }
-    if (fence) continue;
-    if (SLIDE_DIVS.test(trimmed) || /^<!--\s*notes:/i.test(trimmed)) return 'slides';
-  }
-  return 'docx';
-}
-
-function splitFrontMatter(text) {
-  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/);
-  return m ? { meta: parseSimpleYaml(m[1]), body: text.slice(m[0].length) } : { meta: {}, body: text };
-}
-
-function detectDocumentFormat(document) {
-  const text = document && typeof document.getText === 'function' ? document.getText() : String(document);
-  const { meta, body } = splitFrontMatter(text);
-  return detectFormat(meta, body);
-}
-
-const PREVIEW_MODE = { poster: 'poster', slides: 'slide', docx: 'document' };
-
-function pyDocPlugin(md) {
-  // The front matter token carries the mode of its document in .info, so a nested md.renderInline call
-  // (made while processing captions and callouts) cannot change how the outer document's header renders
-  md.renderer.rules.pydoc_front_matter = (ts, idx) => renderFrontMatterBlock(ts[idx].meta, ts[idx].info || 'document');
-
-  // 1. Block rule to parse Front Matter at line 0
-  md.block.ruler.before('table', 'pydoc_front_matter', (state, startLine, endLine, silent) => {
-    if (startLine !== 0) return false;
-    const start = state.bMarks[startLine] + state.tShift[startLine];
-    const max = state.eMarks[startLine];
-    if (state.src.slice(start, max).trim() !== '---') return false;
-
-    let nextLine = startLine + 1;
-    let found = false;
-    while (nextLine < endLine) {
-      const s = state.bMarks[nextLine] + state.tShift[nextLine];
-      const m = state.eMarks[nextLine];
-      if (state.src.slice(s, m).trim() === '---') {
-        found = true;
-        break;
-      }
-      nextLine++;
-    }
-    if (!found) return false;
-    if (silent) return true;
-
-    const yamlContent = state.src.slice(state.eMarks[startLine] + 1, state.bMarks[nextLine]);
-    state.line = nextLine + 1;
-
-    const token = state.push('pydoc_front_matter', '', 0);
-    token.meta = parseSimpleYaml(yamlContent);
-    return true;
-  });
-
-  // 2. Block rule for fenced divs (:::: columns, ::: column, ::: notes, ::: incremental)
-  md.block.ruler.before('fence', 'pydoc_fenced_div', (state, startLine, endLine, silent) => {
-    const start = state.bMarks[startLine] + state.tShift[startLine];
-    const max = state.eMarks[startLine];
-    const lineText = state.src.slice(start, max).trim();
-
-    const openMatch = lineText.match(/^(:{3,4})\s*(?:\{\.([\w-]+)\}|([\w-]+))?(?:\s+(.*))?$/);
-    if (!openMatch) return false;
-
-    const colons = openMatch[1];
-    const tag = (openMatch[2] || openMatch[3] || '').trim().toLowerCase();
-    const isClosing = !tag && lineText === colons;
-
-    if (isClosing) return false;
-    if (silent) return true;
-
-    let nextLine = startLine + 1;
-    let found = false;
-    let depth = 1;
-
-    while (nextLine < endLine) {
-      const s = state.bMarks[nextLine] + state.tShift[nextLine];
-      const m = state.eMarks[nextLine];
-      const cur = state.src.slice(s, m).trim();
-
-      if (cur.startsWith(colons)) {
-        const subMatch = cur.match(/^(:{3,4})\s*(?:\{\.([\w-]+)\}|([\w-]+))?/);
-        if (subMatch && subMatch[1] === colons) {
-          if (!subMatch[2] && !subMatch[3]) {
-            depth--;
-            if (depth === 0) {
-              found = true;
-              break;
-            }
-          } else {
-            depth++;
-          }
-        }
-      }
-      nextLine++;
-    }
-
-    if (!found) return false;
-
-    if (tag === 'pagebreak') {
-      const pbreak = state.push('html_block', '', 0);
-      pbreak.content = '<div class="pydoc-pagebreak"><span class="pydoc-pagebreak-line"></span><span class="pydoc-badge">PAGE BREAK</span><span class="pydoc-pagebreak-line"></span></div>\n';
-      state.line = nextLine + 1;
-      return true;
-    }
-
-    const tokenOpen = state.push('pydoc_div_open', 'div', 1);
-    tokenOpen.block = true;
-    tokenOpen.attrs = [['class', `pydoc-div pydoc-${tag}`]];
-    tokenOpen.info = tag;
-
-    if (tag === 'notes') {
-      const notesHeader = state.push('html_block', '', 0);
-      notesHeader.content = '<div class="pydoc-speaker-notes-header"><span class="pydoc-notes-icon">📝</span> Speaker Notes</div>\n';
-    } else if (tag === 'incremental') {
-      const incBadge = state.push('html_block', '', 0);
-      incBadge.content = '<div class="pydoc-incremental-header"><span class="pydoc-inc-icon">⚡</span> Click-by-click list (incremental)</div>\n';
-    }
-
-    state.line = startLine + 1;
-    const oldParentType = state.parentType;
-    state.parentType = 'div';
-    state.md.block.tokenize(state, startLine + 1, nextLine);
-    state.parentType = oldParentType;
-
-    const tokenClose = state.push('pydoc_div_close', 'div', -1);
-    tokenClose.block = true;
-
-    state.line = nextLine + 1;
-    return true;
-  });
-
-  // 3. Core rule for py-doc markers, numbered captions, callouts, slides, and posters
-  md.core.ruler.push('pydoc_core', (state) => {
-    const counters = {};
-    const tokens = state.tokens;
-    const frontMeta = (tokens.length > 0 && tokens[0].type === 'pydoc_front_matter' && tokens[0].meta) || null;
-    const docTitle = (frontMeta && asText(frontMeta.title)) || 'py-doc Document';
-    const docMode = PREVIEW_MODE[detectFormat(frontMeta, splitFrontMatter(state.src).body)];
-    if (frontMeta) tokens[0].info = docMode;
-
-    for (let i = 0; i < tokens.length; i++) {
-      const token = tokens[i];
-
-      // A. Process Image width attributes: ![](img.png){width=60%}
-      if (token.type === 'inline' && token.children) {
-        for (let c = 0; c < token.children.length; c++) {
-          if (token.children[c].type === 'image') {
-            const nextChild = token.children[c + 1];
-            if (nextChild && nextChild.type === 'text') {
-              const m = nextChild.content.match(/^\{width=([^}]+)\}/);
-              if (m) {
-                const widthVal = m[1].replace(/["']/g, '').trim();
-                token.children[c].attrs = token.children[c].attrs || [];
-                token.children[c].attrs.push(['style', `width: ${widthVal}; max-width: 100%;`]);
-                nextChild.content = nextChild.content.replace(/^\{width=([^}]+)\}\s*/, '');
-              }
-            }
-          }
-        }
-      }
-
-      // B. Process HTML comments for speaker notes: <!-- notes: ... -->
-      if (token.type === 'html_block') {
-        const commentNoteMatch = token.content.match(/<!--\s*notes:\s*([\s\S]*?)\s*-->/i);
-        if (commentNoteMatch) {
-          const noteText = commentNoteMatch[1].trim();
-          token.content = `<div class="pydoc-div pydoc-notes"><div class="pydoc-speaker-notes-header"><span class="pydoc-notes-icon">📝</span> Speaker Notes</div><p>${escapeHtml(noteText)}</p></div>\n`;
-          continue;
-        }
-      }
-
-      // C. Process Headings: {.stats}, {.abstract}, {.summary}, {.references}, and accent colons
-      if (token.type === 'heading_open') {
-        const next = tokens[i + 1];
-        if (next && next.type === 'inline' && next.content) {
-          let text = next.content;
-
-          const classMatch = text.match(/\s*\{([.#][\w\s.-]+)\}\s*$/);
-          let headingClass = '';
-          if (classMatch) {
-            headingClass = classMatch[1].replace(/^\./, '').trim();
-            text = text.replace(/\s*\{([.#][\w\s.-]+)\}\s*$/, '').trim();
-            token.attrs = token.attrs || [];
-            token.attrs.push(['class', `pydoc-heading-${headingClass}`]);
-          }
-
-          next.content = text;
-          if (classMatch) {
-            for (const c of next.children) {
-              if (c.type === 'text') {
-                c.content = c.content.replace(/\s*\{([.#][\w\s.-]+)\}\s*$/, '');
-              }
-            }
-          } else if (docMode === 'poster') {
-            // Poster headings: what follows the first colon is the accent. The inline tokens are split, not
-            // re-rendered, so code, bold and links after the colon keep their formatting
-            const children = next.children || [];
-            const k = children.findIndex((c) => c.type === 'text' && c.content.indexOf(':') > 0);
-            if (k !== -1) {
-              const colon = children[k].content.indexOf(':');
-              const rest = children[k].content.slice(colon + 1);
-              children[k].content = children[k].content.slice(0, colon + 1);
-              const open = new state.Token('html_inline', '', 0);
-              open.content = '<span class="pydoc-heading-accent">';
-              const restToken = new state.Token('text', '', 0);
-              restToken.content = rest;
-              const close = new state.Token('html_inline', '', 0);
-              close.content = '</span>';
-              children.splice(k + 1, 0, open, restToken);
-              children.push(close);
-            }
-          }
-
-          if (headingClass === 'stats') {
-            let tableOpenIdx = -1;
-            let tableCloseIdx = -1;
-            for (let j = i + 1; j < tokens.length; j++) {
-              if (tokens[j].type === 'table_open') tableOpenIdx = j;
-              if (tokens[j].type === 'table_close') {
-                tableCloseIdx = j;
-                break;
-              }
-              if (tokens[j].type === 'heading_open') break;
-            }
-
-            if (tableOpenIdx !== -1 && tableCloseIdx !== -1) {
-              const rows = [];
-              let curRow = null;
-              let inTbody = false;
-
-              for (let k = tableOpenIdx; k <= tableCloseIdx; k++) {
-                if (tokens[k].type === 'tbody_open') inTbody = true;
-                if (tokens[k].type === 'tbody_close') inTbody = false;
-                if (inTbody) {
-                  if (tokens[k].type === 'tr_open') curRow = [];
-                  if (tokens[k].type === 'tr_close' && curRow) {
-                    rows.push(curRow);
-                    curRow = null;
-                  }
-                  if (tokens[k].type === 'inline' && curRow) {
-                    curRow.push(tokens[k].content);
-                  }
-                }
-              }
-
-              let statsHtml = '<div class="pydoc-poster-stats">\n';
-              for (const r of rows) {
-                const val = r[0] || '';
-                const label = r[1] || '';
-                const change = r[2] || '';
-                const verdict = (r[3] || '').toLowerCase().trim();
-                const changeClass = verdict ? verdict : (change.startsWith('+') ? 'good' : (change.startsWith('-') ? 'bad' : ''));
-
-                statsHtml += '  <div class="pydoc-stat-card">\n';
-                statsHtml += `    <div class="pydoc-stat-value">${escapeHtml(val)}</div>\n`;
-                statsHtml += `    <div class="pydoc-stat-label">${escapeHtml(label)}</div>\n`;
-                if (change) {
-                  statsHtml += `    <div class="pydoc-stat-change ${changeClass}">${escapeHtml(change)}</div>\n`;
-                }
-                statsHtml += '  </div>\n';
-              }
-              statsHtml += '</div>\n';
-
-              const replacement = new state.Token('html_block', '', 0);
-              replacement.content = statsHtml;
-              tokens.splice(tableOpenIdx, (tableCloseIdx - tableOpenIdx + 1), replacement);
-            }
-          }
-        }
-      }
-
-      // D. Fenced Blocks: ```cards```, ```segments```, ```flow```, and diagram types
-      if (token.type === 'fence') {
-        const rawInfo = token.info.trim();
-        const mainTag = rawInfo.split(/\s+/)[0].toLowerCase();
-
-        // Cards: ```cards cols=3 style=top```
-        if (mainTag === 'cards') {
-          const lines = token.content.split('\n').filter(l => l.trim());
-          let cardsHtml = '<div class="pydoc-cards-grid">\n';
-          for (const line of lines) {
-            const parts = line.split('|').map(s => s.trim());
-            if (parts.length >= 2) {
-              const title = parts[0];
-              const desc = parts[1];
-              const color = parts[2] || 'blue';
-              cardsHtml += `  <div class="pydoc-card-item pydoc-card-${cssName(color)}">\n`;
-              cardsHtml += `    <div class="pydoc-card-title">${escapeHtml(title)}</div>\n`;
-              cardsHtml += `    <div class="pydoc-card-desc">${escapeHtml(desc)}</div>\n`;
-              cardsHtml += '  </div>\n';
-            }
-          }
-          cardsHtml += '</div>\n';
-          token.type = 'html_block';
-          token.content = cardsHtml;
-          continue;
-        }
-
-        // Segments: ```segments```
-        if (mainTag === 'segments') {
-          const lines = token.content.split('\n').filter(l => l.trim());
-          let segTitle = '';
-          const items = [];
-          for (const line of lines) {
-            if (line.toLowerCase().startsWith('title:')) {
-              segTitle = line.replace(/^title:\s*/i, '');
-            } else {
-              const parts = line.split('|').map(s => s.trim());
-              if (parts.length >= 2) {
-                items.push({
-                  weight: parts[0],
-                  label: parts[1],
-                  value: parts[2] || '',
-                  color: parts[3] || 'blue'
-                });
-              }
-            }
-          }
-
-          let segHtml = '<div class="pydoc-segments-box">\n';
-          if (segTitle) {
-            segHtml += `  <div class="pydoc-segments-title">${escapeHtml(segTitle)}</div>\n`;
-          }
-          segHtml += '  <div class="pydoc-segments-bar">\n';
-          for (const it of items) {
-            segHtml += `    <div class="pydoc-segment-slice pydoc-bg-${cssName(it.color)}" style="flex: ${Number.parseFloat(it.weight) || 1}" title="${escapeHtml(it.label)}: ${escapeHtml(it.value)}"><span class="pydoc-segment-text">${escapeHtml(it.label)}</span></div>\n`;
-          }
-          segHtml += '  </div>\n';
-          segHtml += '</div>\n';
-          token.type = 'html_block';
-          token.content = segHtml;
-          continue;
-        }
-
-        // Flow: ```flow```
-        if (mainTag === 'flow') {
-          const lines = token.content.split('\n').filter(l => l.trim());
-          let flowHtml = '<div class="pydoc-flow-diagram">\n';
-          for (const line of lines) {
-            const parts = line.split(/-(.*?)->/).map(s => s.trim());
-            flowHtml += '  <div class="pydoc-flow-step">\n';
-            for (let p = 0; p < parts.length; p++) {
-              const item = parts[p];
-              if (p % 2 === 0) {
-                const nodeMatch = item.match(/^\[(.*?)(?:\|(.*?))?\]$/);
-                const nodeText = nodeMatch ? nodeMatch[1] : item;
-                const nodeColor = (nodeMatch && nodeMatch[2]) ? nodeMatch[2] : 'blue';
-                flowHtml += `    <span class="pydoc-flow-node pydoc-bg-${cssName(nodeColor)}">${escapeHtml(nodeText)}</span>\n`;
-              } else {
-                flowHtml += `    <span class="pydoc-flow-arrow">➔ ${escapeHtml(item)}</span>\n`;
-              }
-            }
-            flowHtml += '  </div>\n';
-          }
-          flowHtml += '</div>\n';
-          token.type = 'html_block';
-          token.content = flowHtml;
-          continue;
-        }
-
-        // Other py-doc diagram types (plantuml, dot, ditaa, wavedrom, vega, bytefield, etc.)
-        if (DIAGRAM_TYPES.has(mainTag) && mainTag !== 'mermaid') {
-          const titleMatch = rawInfo.match(/(?:title|caption)=["']?([^"']+)["']?/i);
-          const diagTitle = titleMatch ? titleMatch[1] : '';
-          const escapedContent = md.utils.escapeHtml(token.content);
-
-          token.type = 'html_block';
-          token.content = `<div class="pydoc-diagram-box" data-diagram="${mainTag}">\n` +
-            `  <div class="pydoc-diagram-header"><span class="pydoc-diagram-badge">${mainTag.toUpperCase()}</span>${diagTitle ? ` <span class="pydoc-diagram-title">${escapeHtml(diagTitle)}</span>` : ''}</div>\n` +
-            `  <pre class="pydoc-diagram-code"><code>${escapedContent}</code></pre>\n` +
-            `</div>\n`;
-          continue;
-        }
-      }
-
-      // E. Process Paragraphs containing py-doc markers
-      if (token.type === 'paragraph_open') {
-        const next = tokens[i + 1];
-        if (next && next.type === 'inline' && next.content) {
-          const rawLines = next.content.split('\n');
-          let hasMarkers = false;
-
-          for (const line of rawLines) {
-            const trimmed = line.trim();
-            if (
-              trimmed === '[[PAGEBREAK]]' ||
-              trimmed === '::: {.pagebreak}' ||
-              /^\[\[(LANDSCAPE|PORTRAIT)\]\]$/i.test(trimmed) ||
-              /^\[\[CAPTION:[A-Za-z0-9 _-]+\]\]/i.test(trimmed) ||
-              /^\[\[STYLE:[A-Za-z0-9 _-]+\]\]/i.test(trimmed) ||
-              /^\[\[(INCLUDE|INCLUDE-CODE|IF|NOT|ENDIF)(?::.*)?\]\]$/i.test(trimmed)
-            ) {
-              hasMarkers = true;
-              break;
-            }
-          }
-
-          if (hasMarkers) {
-            let renderedHtml = '';
-            for (const line of rawLines) {
-              const trimmed = line.trim();
-              if (!trimmed) continue;
-
-              // Page Break
-              if (trimmed === '[[PAGEBREAK]]' || trimmed === '::: {.pagebreak}') {
-                renderedHtml += '<div class="pydoc-pagebreak"><span class="pydoc-pagebreak-line"></span><span class="pydoc-badge">PAGE BREAK</span><span class="pydoc-pagebreak-line"></span></div>\n';
-                continue;
-              }
-
-              // Orientation
-              const orientMatch = trimmed.match(/^\[\[(LANDSCAPE|PORTRAIT)\]\]$/i);
-              if (orientMatch) {
-                const orient = orientMatch[1].toUpperCase();
-                renderedHtml += `<div class="pydoc-orientation"><span class="pydoc-pagebreak-line"></span><span class="pydoc-badge">SECTION BREAK (${orient})</span><span class="pydoc-pagebreak-line"></span></div>\n`;
-                continue;
-              }
-
-              // Directives
-              const directiveMatch = trimmed.match(/^\[\[(INCLUDE|INCLUDE-CODE|IF|NOT|ENDIF)(?::\s*([^\]]+))?\]\]$/i);
-              if (directiveMatch) {
-                const dType = directiveMatch[1].toUpperCase();
-                const dArg = (directiveMatch[2] || '').trim();
-                renderedHtml += `<div class="pydoc-directive"><span class="pydoc-directive-badge">${escapeHtml(dType)}</span> <code class="pydoc-directive-arg">${escapeHtml(dArg)}</code></div>\n`;
-                continue;
-              }
-
-              // Numbered Caption
-              const capMatch = trimmed.match(/^\[\[CAPTION:([A-Za-z0-9 _-]+)\]\](?:\s*(.*))?$/);
-              if (capMatch) {
-                const label = capMatch[1].trim();
-                const text = (capMatch[2] || '').trim();
-                counters[label] = (counters[label] || 0) + 1;
-                const num = counters[label];
-                renderedHtml += `<div class="pydoc-caption"><span class="pydoc-caption-num">${escapeHtml(label)} ${num}:</span> <span class="pydoc-caption-text">${md.renderInline(text)}</span></div>\n`;
-                continue;
-              }
-
-              // Style
-              const styleMatch = trimmed.match(/^\[\[STYLE:([A-Za-z0-9 _-]+)\]\](?:\s*(.*))?$/);
-              if (styleMatch) {
-                const styleName = styleMatch[1].trim();
-                const text = (styleMatch[2] || '').trim();
-                renderedHtml += `<div class="pydoc-styled-block" data-word-style="${escapeHtml(styleName)}"><span class="pydoc-style-pill" title="Word Paragraph Style">${escapeHtml(styleName)}</span>${md.renderInline(text)}</div>\n`;
-                continue;
-              }
-
-              renderedHtml += `<p>${md.renderInline(line)}</p>\n`;
-            }
-
-            tokens[i] = new state.Token('html_block', '', 0);
-            tokens[i].content = renderedHtml;
-            tokens.splice(i + 1, 2);
-            continue;
-          }
-        }
-      }
-
-      // F. Process Blockquotes for Callouts / Admonitions
-      if (token.type === 'blockquote_open') {
-        let firstInlineIdx = -1;
-        for (let j = i + 1; j < tokens.length; j++) {
-          if (tokens[j].type === 'blockquote_close') break;
-          if (tokens[j].type === 'inline') {
-            firstInlineIdx = j;
-            break;
-          }
-        }
-
-        if (firstInlineIdx !== -1) {
-          const inlineToken = tokens[firstInlineIdx];
-          const rawContent = inlineToken.content.trim();
-          const ghMatch = rawContent.match(/^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]/i);
-          const boldMatch = rawContent.match(/^\*\*(Note|Tip|Important|Warning|Caution)\s*:\*\*/i)
-            || rawContent.match(/^\*\*(Note|Tip|Important|Warning|Caution)\*\*\s*:/i);
-
-          const kindRaw = ghMatch ? ghMatch[1] : (boldMatch ? boldMatch[1] : null);
-
-          if (kindRaw) {
-            const kindKey = kindRaw.toUpperCase();
-            const info = KINDS[kindKey] || { title: kindKey, icon: 'ℹ️', class: 'note' };
-
-            token.attrs = [['class', `pydoc-callout pydoc-callout-${info.class}`]];
-
-            let bodyText = rawContent;
-            if (ghMatch) {
-              bodyText = bodyText.replace(/^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*/i, '');
-            } else if (boldMatch) {
-              bodyText = bodyText.replace(/^\*\*(Note|Tip|Important|Warning|Caution)\s*:\*\*\s*/i, '')
-                                 .replace(/^\*\*(Note|Tip|Important|Warning|Caution)\*\*\s*:\s*/i, '');
-            }
-
-            const headerBlock = new state.Token('html_block', '', 0);
-            headerBlock.content = `<div class="pydoc-callout-header"><span class="pydoc-callout-icon">${info.icon}</span><span class="pydoc-callout-title">${info.title}</span></div>\n`;
-
-            const pOpenIdx = firstInlineIdx - 1;
-            tokens.splice(pOpenIdx, 0, headerBlock);
-            i++;
-
-            inlineToken.content = bodyText;
-            if (!bodyText) {
-              tokens.splice(pOpenIdx + 1, 3);
-            } else {
-              inlineToken.children = [new state.Token('html_inline', '', 0)];
-              inlineToken.children[0].content = md.renderInline(bodyText);
-            }
-          }
-        }
-      }
-    }
-
-    // G. If in Slide Deck mode, group tokens into presentation slide cards
-    if (docMode === 'slide') {
-      groupTokensIntoSlides(state, docTitle, Number.parseInt(asText(frontMeta && frontMeta.split_level), 10) || 2);
-    }
-
-    // H. If in Poster mode, append poster footer if defined
-    if (docMode === 'poster' && frontMeta && frontMeta.footer) {
-      const footer = frontMeta.footer;
-      let footerHtml = '<footer class="pydoc-poster-footer">\n';
-      footerHtml += `  <div class="pydoc-poster-footer-left">${escapeHtml(footer.left || '')}</div>\n`;
-      footerHtml += `  <div class="pydoc-poster-footer-right">${escapeHtml(footer.right || '')}</div>\n`;
-      if (footer.qr || footer['qr-label']) {
-        footerHtml += `  <div class="pydoc-poster-qr-badge">📱 ${escapeHtml(footer['qr-label'] || 'QR Code')}</div>\n`;
-      }
-      footerHtml += '</footer>\n';
-
-      const footToken = new state.Token('html_block', '', 0);
-      footToken.content = footerHtml;
-      tokens.push(footToken);
-    }
-  });
-}
-
-// A heading at splitLevel or above starts a slide, as pandoc's --slide-level does; one above it is a section slide
-function groupTokensIntoSlides(state, docTitle, splitLevel) {
-  const tokens = state.tokens;
-  const newTokens = [];
-  let currentSlideTokens = [];
-  let slideNum = 0;
-  let isCurrentSection = false;
-
-  function flushSlide(isSection) {
-    if (currentSlideTokens.length === 0) return;
-    slideNum++;
-    const cardOpen = new state.Token('html_block', '', 0);
-    const slideClass = isSection ? 'pydoc-slide pydoc-slide-section' : 'pydoc-slide pydoc-slide-content';
-    cardOpen.content = `<section class="${slideClass}"><div class="pydoc-slide-canvas">\n`;
-    newTokens.push(cardOpen);
-
-    for (const t of currentSlideTokens) {
-      newTokens.push(t);
-    }
-
-    const cardClose = new state.Token('html_block', '', 0);
-    cardClose.content = `</div><footer class="pydoc-slide-footer"><span class="pydoc-slide-deck-title">${escapeHtml(docTitle)}</span><span class="pydoc-slide-num">Slide ${slideNum}</span></footer></section>\n`;
-    newTokens.push(cardClose);
-    currentSlideTokens = [];
-  }
-
-  for (let i = 0; i < tokens.length; i++) {
-    const token = tokens[i];
-
-    if (token.type === 'pydoc_front_matter') {
-      newTokens.push(token);
-      continue;
-    }
-
-    if (token.type === 'heading_open') {
-      const level = parseInt(token.tag.slice(1), 10);
-      if (level <= splitLevel) {
-        flushSlide(isCurrentSection);
-        isCurrentSection = (level < splitLevel);
-      }
-    }
-
-    if (token.type === 'html_block' && token.content && token.content.includes('pydoc-pagebreak')) {
-      flushSlide(isCurrentSection);
-      isCurrentSection = false;
-      continue;
-    }
-
-    currentSlideTokens.push(token);
-  }
-
-  flushSlide(isCurrentSection);
-  state.tokens = newTokens;
-}
+const { pyDocPlugin } = require('./src/plugin');
+const { detectFormat, detectDocumentFormat } = require('./src/detect');
+const { parseFrontMatter } = require('./src/frontmatter');
 
 let vscode;
-try { vscode = require('vscode'); } catch (e) { vscode = null; }
-
-let watchTerminal = null;
-
-const WATCH_START_TIMEOUT = 120000;  // ms: a first build may have to start the tool container
-const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
-// Whether a py-doc watch server answers on this port
-function serverUp(port) {
-  return new Promise((resolve) => {
-    const req = require('http').get({ host: '127.0.0.1', port, path: '/__status', timeout: 500 }, (res) => {
-      res.resume();
-      resolve(res.statusCode === 200);
-    });
-    req.on('timeout', () => req.destroy());
-    req.on('error', () => resolve(false));
-  });
-}
-
-function stopWatch() {
-  if (watchTerminal) {
-    watchTerminal.dispose();  // ends the py-doc process running in it
-    watchTerminal = null;
-    return true;
-  }
-  return false;
-}
+try { vscode = require('vscode'); } catch (e) { vscode = null; }  // absent when the tests run in Node
 
-async function launchWatch(subcommand, filePath) {
-  const port = vscode.workspace.getConfiguration('pydoc').get('watch.port', 8765);
-
-  // A running watch is stopped first: typing a new command into its terminal would go to the running process
-  if (stopWatch()) {
-    for (let waited = 0; waited < 5000 && await serverUp(port); waited += 250) await delay(250);
-  }
-
-  const terminal = vscode.window.createTerminal({
-    name: `py-doc ${subcommand} watch`,
-    iconPath: new vscode.ThemeIcon('eye')
-  });
-  watchTerminal = terminal;
-  terminal.show(true);
-  terminal.sendText(`py-doc ${subcommand} "${filePath}" --watch --port ${port} --no-open`);
-
-  const started = await vscode.window.withProgress(
-    { location: vscode.ProgressLocation.Window, title: `py-doc: building the ${subcommand} preview` },
-    async () => {
-      for (let waited = 0; waited < WATCH_START_TIMEOUT; waited += 500) {
-        if (watchTerminal !== terminal || terminal.exitStatus !== undefined) return false;
-        if (await serverUp(port)) return true;
-        await delay(500);
-      }
-      return false;
-    }
-  );
-  if (started) {
-    vscode.commands.executeCommand('simpleBrowser.show', `http://127.0.0.1:${port}`);
-  } else if (watchTerminal === terminal) {
-    vscode.window.showWarningMessage(`The py-doc preview server did not start on port ${port}. See the "${terminal.name}" terminal.`);
-  }
-}
+let live = null;
 
 function activate(context) {
   if (!vscode) return;
+  const { LiveWatch } = require('./src/watch');
+  live = new LiveWatch(vscode);
 
-  const withActiveFile = (run) => async () => {
+  // Run a live preview command on the Markdown file of the active editor
+  const onActiveFile = (command) => async () => {
     const editor = vscode.window.activeTextEditor;
     if (!editor) {
       vscode.window.showErrorMessage('No active Markdown file to preview.');
       return;
     }
-    await run(editor.document);
+    const doc = editor.document;
+    if (doc.isUntitled) {
+      vscode.window.showErrorMessage('Save the file first: py-doc builds it from disk.');
+      return;
+    }
+    const folder = vscode.workspace.getWorkspaceFolder(doc.uri);  // where py-doc.yml and themes are found
+    await live.start(command || detectDocumentFormat(doc), doc.uri.fsPath, folder ? folder.uri.fsPath : undefined);
   };
 
   context.subscriptions.push(
-    vscode.commands.registerCommand('pydoc.openLiveWatch',
-      withActiveFile((doc) => launchWatch(detectDocumentFormat(doc), doc.uri.fsPath))),
-    vscode.commands.registerCommand('pydoc.openDocxWatch', withActiveFile((doc) => launchWatch('docx', doc.uri.fsPath))),
-    vscode.commands.registerCommand('pydoc.openSlidesWatch', withActiveFile((doc) => launchWatch('slides', doc.uri.fsPath))),
-    vscode.commands.registerCommand('pydoc.openPosterWatch', withActiveFile((doc) => launchWatch('poster', doc.uri.fsPath))),
-    vscode.commands.registerCommand('pydoc.stopLiveWatch', () => {
-      if (stopWatch()) vscode.window.showInformationMessage('py-doc live preview server stopped.');
+    vscode.commands.registerCommand('pydoc.openLiveWatch', onActiveFile(null)),
+    vscode.commands.registerCommand('pydoc.openDocxWatch', onActiveFile('docx')),
+    vscode.commands.registerCommand('pydoc.openSlidesWatch', onActiveFile('slides')),
+    vscode.commands.registerCommand('pydoc.openPosterWatch', onActiveFile('poster')),
+    vscode.commands.registerCommand('pydoc.stopLiveWatch', async () => {
+      if (await live.stop()) vscode.window.showInformationMessage('py-doc live preview stopped.');
     }),
-    vscode.window.onDidCloseTerminal((closed) => {
-      if (closed === watchTerminal) watchTerminal = null;
-    })
+    live
   );
 }
 
 function deactivate() {
-  stopWatch();
+  return live ? live.stop() : undefined;
 }
 
 function extendMarkdownIt(md) {
@@ -887,7 +64,7 @@ module.exports = {
   deactivate,
   extendMarkdownIt,
   pyDocPlugin,
-  parseSimpleYaml,
+  parseFrontMatter,
   detectFormat,
   detectDocumentFormat
 };
diff --git a/editors/vscode/images/icon.png b/editors/vscode/images/icon.png
new file mode 100644
index 0000000000000000000000000000000000000000..ebc6842f293e2b736c36493410595f303e0f6674
GIT binary patch
literal 6651
zcmV<X83g8uP)<h;3K|Lk000e1NJLTq004jh004jp1^@s6!#-il000@nNkl<Zc%1EB
z3zSsFnf|Koz1=<C^MqkwM3AUx9HSBpf`Fh=V@&XsWLQs<jS7gy#Lb#y*OOhd!(=zf
zp3NFfPBuYMOcpiDxJk|?Ig3#v6CNrmFL?+W1d%uMe)Qwss@n6{y*&?@neG{;XKoMu
zX%92E`*z>1|EvH1>#M)&0y&(~U?cRiMhaAx8l{S(awo&F3Wl<s3N<xyD89^yLsb>W
znl&7_n*Nulu2zHHj)O=5#ZWn)_iF69-zWwe0b%DnL0>Q|1rcT_Khcbu8ga_=m6Zl+
zDilyn?R?r83}Y}<R`PBad(~GbfXPolsmmedG%%Ea;e06KMb7?xLjjBfQXK(fhr#(a
zFl>duMi}Gvptjl>Od_0~HS|SzhM&H0EJEhZ5V#W%Q(y$bU<^>6Ly&_)*fWR(26X!o
z83<0o0cU%lSPi&(7PZUX>0*Nchu8rUKzZjer41i2zY3^(VOV3K1Rw;U=ojkp^eyx!
zdEX?5^q>?JQyp!{V1OF{Hz|z90rm_W`^R{7#rBSTp}POxfSp#apS}2gaP|<mSq5PP
zk}MAfrj4HS^@9tS4D=sk2FxHJoCFviL!0_8-dfhw%{FPGe@04vz*S!=hl)H2)4IVk
zyrVBFXY`?hf>N@B2-4XD=`6syC)W3u1nCoC?pzbKwGL)4oCR*yfEnd*;*NGrNjIOv
za1cSjFij}t0OIRdyZo{K<OS))<+)X!@fX|;Zmod=8DD@gGiUr^1%+D^!jVvp0VA*!
zvllJZ9-yi!tuUOr=O$gs%msJD3N3@M6_lhnluPRT1<DR20(k}!vE^95d~rJAfTd~t
zD`8seAtjCH=(L>ieG6qH5VjDHK7jR)Kk9mKPdn%*0m#TS%qv5HZv)sENRjLL+2IKU
zOv{9m_!QPZ@nT<|p!c3!SxMwju-Hl%RvDzAtTWg1{SOAFxbCdnScxmYT!xxe<hFaX
zUC#zhGG^AIufYmk4?CV5=H-wTU_=0^g*hYmGcDM;9s1N)_IykM*M5Bz5{Y*KRs<z;
z!cI1VLV*=9V8^e)`X|=(6berD0F|q_W=t%0Kg?i>W>QYz$zCX>z*Lp~y@Do>`t|_s
z-*Xp_hEVT-u~F`1PEOX%T99IB1~{BVk6xg=2bfz$ab7{l+h7Go=X(E$fb>S~i`_pf
z`|toXqqK7;!=a)LFwJRj9O+8ELkD*rX#_*jC~asz(KB-!q__|pRvhx|t}ml&Yr6+$
zd}Tb$&~89Q+^NXSyMHpe!5M^*P<lc!3!nzrGMvLO4IP@bt~Qj(pyS+zb<2L&H4K;?
zFG^PR7@_Gf%?Rv-7>eF+7#t#Q!->X#a2`sE3%XVj_!3Hy9T}wVAL;QR*_B$_Vi1k3
zK){3%4r$V79=b)TIOiGwztgpv9y$q-JjkeoON)R>*O4)B&LNuHP&Rfn?pt&VZk%~3
z&L3aq`!HZT5=R<ZF|n-BHEdU(+ULX_aHPH&8@BAhPikJm_MLmd^22U<O-7voV>+2<
zYN{^Sr2^C1lL?SKsN@t#UDv@fZG71t#SL?&V#PxXa8_wCvI!rYXhU<mz{IkGew{a}
zFoKFn<+x+sZ2aSY)!--3tcDQ`KxC2uRE_1@^a9L05JB~dmLz9839w{|!Wx(m2TNUA
z6E9ij+<tQ#uAeg%s~`QQKIRAk&bY5#e-aL<;!0uv(I$P}=av`iaFA9gptM{n-3E_*
z<8~AmMzG}3U&AOVgvez6LrDi%7|bpK&_Mv+WnNh!zOxVtlU;X_8B@^P%7l&4WuvgN
zYLUJ!Atg-1&~cTX&xQvWL%=d{xV{bVA87*jj-@(}US}Fyx4!KN{L5W8VeVBQ*B!#(
z8JlXM5TIa~`H*>&^$|}R?*56UMKqR~cKxa?hWl^-6vh(krOf0P&nT1vER*9<U8^QR
ze?qw?0}-B_@4}nG4X&s0GLDn%JLD}drGOa;;nvxgxhiEg`1}l!fV=^<!HkQ~#o3d}
zA>#?xlMEq-lmKLG<p>m(6ylt5r5!FY+o1+X0^J@82n8%m9$yB~$a^FcAPHi<&PhfP
z)M<DELQ+#0YGh~d9ib!`4&(@MhLa#ifHRx~IRc#FB*+oq3@1U30B1M}as)WTNzgeN
zl*5pbfbfxVMf%uq6CvjThSL-1`PSj3K+XdUBMIpDbIXe`oX8R2G%(=RGKwm~I1bmh
zLMn;#&ng+VI*1$r1_&zZaHIl14a3oN@Q24+ke?UyicE(-9OMWv08j<<M<;q~X4vTy
ziHP9nUDSr&4de(g0ML|eL0$lZ36qLqh9Mu!5nzBAEL$Z#z;KNPas(J42FqCw_p<A(
zAb{>2!>yPM6d9|nK0^pVl`?L{EwUCuDHuL2ee*Q|sMC}2DL-y%OMneytn4qe-cR*@
z7Dt|C40tKw8B2g<&wukkBNjZh2?tx^fZ-NVW(63)6%b|&)i+n*u4xlGy_t{TO9CWU
zB}Q$5FFw5q?|#q-giUvcx@-ai>Kuhd&uqr@iN&ZGTi`nq_>ut0v9>K0j<+Phf(A^J
z>mBF)({z2K!{r+cPFn&^QQJN4vsmCu0#FB`#Hlc7;?Y|##^R?pA<<_0d(C)n5EA!Y
zHyP8<8Krwasfd1pF9|@PteHB?9n&UY#-vd=Sl<p#IRLT<637pkm^LxF^4VX;_cZ~M
z%|*TD!Z8v3$W|yHZ+PKr0w6gI)GLXQonWpv^DBH$0D@jxjqHW;F?oGYfRUgC_5~W*
z3@1N)O@M4x0@G6p6-vT^Vf7NeB|z3IfhnNxsOLyrF|h=z7G8mXIXuPUz9hhiQ36we
zGraKT2l(f+iV?AlTtUc4QUX(f`nt&(;--OvO|e`-$cR+}`+$%N<)sn);4>HE+uOX2
z`-T|43;`oX2~4?hmqbN*A;uL1(VB3Eh2Xv=z(`U8Q-QV&9<CWeUlU+ND1oV<XyeS`
z3vIq9KsG3W>@+TJ$aW0RRsv*$5~z|JM*H|0vyuRQR|1)5{F1PRY=v(LkPS*8^VB>V
zrL6q&RE+Xu-E8s%z9c|aDS@2f|K2!&Zxw~`%iE{uvAv(Cf3t!B*`frh4mFSCP*co3
znAQb$*&1Y+iv)d1fNW9%g;Y3eOa%Wi?;@`dl=Wb2*`+Lq5?Z=7qxUoo0V&);!ekWo
z=oa8ZH!a{x0%VU8$h4Yw$@n6Si3Gf))q6^B03-o!0Cd;gF1%3jCigi?aOoDm;S#i~
zFr0Xhc8&&E0tTmhh>!-t&P)Pin-VBH>ire;?OC|#8eR$5M>fGexB-a+e}RnFLDcVn
zqSv@z5P{MQ@V&BTyf7_@jZJ4`Q^OdvMk4?hFw8_oiQsDjWQ!8WliS`aGOD4CFWZiy
zee*96+f@UnZYPx8B?6q(>al$raYYE2GX;ptt@xlVf|rg?#M1XZhIi`A0MmhC*bp5z
zcsYXzkPS*8y7YQ-?`<0&LHm}a5RFH*v6;odXuiKA`Sa?)Jcq%89BoRWB~G~jP@dO@
zd(Yp6znQoj|8rn69@#wwe{CEC9*pYK)F65T-xDAklt6ghI`RGsXnyhUU?1579t1cI
zU3CIT59id=Iz|FQ8$OvoBqT#L4wy{h?(=rz=JD_2Uw2Hy@^>!<3<1u?poIiq6Tq)Z
zAnREAMLn7!t{4ioejm-XOZ4+RLWUQBbO!kT3c5lJ!0|Xk$VlL4m#@c_rHAprra5S`
zgW!fUC?xPL0sO24D$ht1m>iXd9~b=yUvT~iWpTF`576*Efrf@c0mot-UzxNQ6C=&|
z{9kTDlM@&e68Mq;{#OE(_fH7_Ui5u@iM@!1fCWx&J_8J;wy?Owp(w|!(I@cyoZn;q
z+IeVn0$|J?E{-Sy_*n^5q)|X1A&T+sqQ~%H;fpvZOqi7BXBYu4aXij(b?FH#oBk)v
zUwbpSDYS<eQ3UX}5-1^1fVl<h@ZJ1paab5IFnBIM9TFUgaolp&Av{pA5kG!=CX8VF
zfQN{_B!F*~K&1y^knwg*`tu^#F^X0Falo`~h<8JFy~|{B>QLX=yYpBIm|UVh!SJ1r
zZox}O&cU|&vEZgXpnSl$1n{*Ixar?;tmy;TVG}&vgpUj_1XR><a~zKcS`whYEgDH0
zod;61i=%)-Q)0=-Uc={VZyoSg@ihVbr35Pdlcd}eYaay*FfbbGr33P2Q2`z)K&awY
zSmje;mR_Qdi>Cc>j&4Kj-RB|dKXg?>Z-OY*=%CSNxNhuW%o?{J>yJ!=VZ|Z(=>>dG
z0ADD93}Bwp7u))Cps5ZlVz}yGpXZSw8B{_dGUI-Pr#}dzVEn1Cy9CIeQ;q2MU!ir)
zLy(DPFpIk@M^h%Gz&9`0j15O84k$eO{)Q3B+p>E%=N_I10Ik)DIHEhB0=H84(5}WW
z`s^|kT=!Gg_(U2C8{|EbVv%&f0)+@qy&olCd=We}N}s2vjr)MX6j~gH*<+62yrL73
z!s@p{eeD5;TM1;zz5YxfFJK{Y_-#0Kdv&}{nXoAiWeXJDv<!Kd-VI3Gn<z5i2<dGR
zOX1DEd%FH+(t$PZ3XHmaHR_-JG*rAHWjJsYLuo+blVu;`JxT_H3CMno2z*NbUnqgh
z+v`s`_}=`haHsJ)L`=fWC#koO<c}FpF@eaHU+*+NcMC`9`c0$LKwLX<cd0m|*GL=Y
zxM?W*%u+Nwe><37GthgeA>vSF`IV!OU>Tzu(2sx|z*kBj1L|xWi=NqnkDmKmToeM@
zbp=mvuV*@Tvq(PjXI6QIADuge($gzfzlz_y@+Mkh3EViX0*gO)4GO}cE+lXeyr2?+
ziT{bj{*77))8V2APz6y;03R<ohHxl~c42B#sB9*HUz9+Vtk&ZeoM<~v)E$NyaC>X-
z7j8hs9fU8w1uU=Bn<h4(Bx(8z_dWbHmjCki0No{oF}(bz*Rbl9H}Qvu{~n`@@-_Qi
zy-R8D5r2Q9`*$B7NlIY8X(P|D(eBWAQe}4%c(M{m&eLwQAz}`kA$$n^uMH;#+&i-n
zSC6hkv*RXTeSw~}#?S2d%Mmn%%kbQv-_XVnj2jK3APggthu~RbuyMoN_|9X$b@Ls)
zQi#mLV2%3(c#u3_@2-!yVM~V6po7T;4S+DTS3tIV0N*HqQXxMtfNABxiC-jAtI<m8
zT+bMFk^8qE!n!9t`_e}6P!Li`2+yd}R^TQ1_~WbF(9$0BLV=qk8inV8<rP4+r%ndR
z=%fww7rrHc-;_WZZGh;Z=C@aLNPV4^!mY7{D+-<TQpFhJ30sd2y1xfi52qjW29hHA
zG6eLb1XB6+usnp+;fRsupN{fJ29|(q-tYdcC`)%ubK~@jA={%cO~Vzp7!a^bsFo<M
zs5lqJ`C;uDk|w9RLKScKG=<diaH`PMWBX#5&}Smm0|{u4-C=nc?m&%%8na}wmyGw-
zD`^w}*hk;&I6~umBJtff&B3%;mmz-m1e7D7ghc#!14_z@@xyy=OP<{^AK=vOfQrWG
z4SH`!PZq9=o7mf03~<@6n!#Zq0P`9)d!V!o%=1Qj*?1ofO!a*MAh!E?=<Jb^$m5<-
zQV_=KN4|->zkDMml$GeL|K{tb<K?B_!N(_)luI{|^6nnS7^2&s?D+V;K<PodFm$OH
zjR2INa{$IUqODOJZ)ibbB+s{Z(&z>~mglg_XCS)k1?|3jZDm*Kfv7u#==K%Jn{uBP
zcW8W1UT;)E7|Z_YF0{uINZ1aF3&P#*9;T&XZo)aX1@ZS@(iOvfsg5)S95fYnHIGJH
zJk;-L;U2nS=5Aj}4ZuwU(S{bR*|OVB@={EA_yWvrP;0^*H@8bUZ!f_D9L+C32<ONf
zt_nybp!|UH86go41+?)g=AUeQ6>C7#AMSv%qh9am-6W*^(Y(=Xbz`A~37)F|Q!>*l
z0UVpCozcbay6u7%9{%;8bVKN4!#~%X0&X)|V=sqMJl0iS`pVAf`)~zix1#>nH^5Gk
zKnXCd{nPX|#cHYDH?0foFn+uN_0Qb^`_Q(Oz2Chug?0hFa{O$)lBiE9*u7?}X9BpH
z1Fbwb;Lbv2#wvR9BOJmzJNM$-Kd*sl7`g{gPw*`d81+s87A!*Wym^p`t`!}<fJP1$
zhm19#;n`0kw(HrB$sqcdQEs4zdE7n5P1uKDNBz^+B5~jiusoV>?%Vh@UWk|q+Z&6q
zwQd}kNvnr?Bmim548n=RaX!>XDk@IOW~!<<s;ecgTKE!p;958~4SQ33%YlO^CKEQQ
z7T<;?3vcnwo;kfjFZ<$f>UZPB6PJNA;d#?kE|;c}r9M3{VJ7k}y%XlxDKLxA)6Fm1
z4#PR|4q`k08}Yq=gi1KB_MfWOK+gnnj1EZL@x~mi`s*by0@2=T16=|r*?>fJ5;i{F
zoSf|JOagaaoE(AdhQY7xoRY~5B+au2EmZ&XIjq~f2M>PbGnjelWJG9ntS@2epMlbg
zP(I@>9ACQ(GGwII2FQgQOwZ~iKG=Z7{ta&VSJ=Iah>Ex9nL`4jBtF2?GCn1G1*XK7
z#zOq=gA2i}c<<A|I{DHB*as1bYH#o50-Xdnw!^iyVsCgyGMk)x%jArb0=)d{HoUxX
z2PRAyi}TMegI~e)_?)9y731M@3;7Vb9+;(BOsadfoB2YuH@eSJ6d-r6Uy^=dsGIyL
z{9xB7kgzQn0U|)JS0cd;4w=}7w;s1K|2p#QqB{Yuu9l$PN;x(_*d%%n$<9ZV2paie
zEtDKMcnk;j9ZG&f|AEmD2{;iHT{aDmUA_TFV_YxVNDI0O$ooCHHz56;Mvw0bTXK|z
zB!0Q?Bl!LPi(mv|scHc|@6OkB>+IbKP_3n8hWe&`C@I_z!<?*VErviWN=}UMfCU!x
zYY6Cs0f{Hyy$rKT58=*9`}B$(s@Lxq2AJ_u1yHdiv7@;F4{n|dZc+tM3Liw-reiz0
zb9e3Rrx<r`m4Tf#2>{RN4Gw6WGK6q7f9d;&P2+Y$;9Hxn!J6Zx7!#ypnO8Q+_z^>)
z&JN(t*RDrnJkOPW`#MQMz#wNX)?(e`@43l-=e$w(tFEo~2Ij^}2s;ku${rc}Mp+7_
zYsCbb?0{aVxxTIxV?!<pGSyi0-bJR;i$ZVt%V)8zZk#RyPp$e<F0YFzAJ_3~O?R80
zOk0V{N&_2~{S`_)2Qx_0RTfBfLl3E#UY$z@`TW{>_}@ck>$t2d_y%zU2l^a(zcC?+
zJ#B^B_*?7BVFoGgr}8=^x|keJd^b$zH#+;Tt?rg^oca!~KtOY_KY*|uuQWO51yYdU
z3v1`$p|>yBg)GGZ)nT}Sg3i}2-&Fejp4xXFu6_A)*jhhMCw)#jA%`{`Gc4-FKSb@X
zVwgW)D|}sF((@IP7pSQbn7#04u=2i!MAQL0d1sp(l5lGUNZ885)G;68yB~W~muXX?
z-|D!rn|15}a;jMCT7>$X`z%SrR0B&&@Rr6B{Akxy{AT}!dat0gcL$-^Z(0U~y&3r*
zUWw_`ZB$pEqFnX%P7GC53@;vtz%aIe@sB__R27j;bGSnegGmU7sz!lp#vQ=@7i`7s
z(nBZ=NNrrwduSSgYWTXs<WvF=ggEU3KvTQGj>b{=#e0`v)q%;d?ErWn?(RI7_D+;c
z=o&gZF%7S-*xaG?o`l|dwHpRDtZ2ckJH7-Xv>uEq<o$N<Ykxr~uBT%OuN;|(SB_4=
zg++DvWZ6N?7=0L*l^jRDnLueU(NW?@(+pJ15fvtOG>^i@x^k>JJ|1t@jfEsKS#d4$
z^e>z!2UebiMC${1^~ufJqgQv2{YmuwuE|g^YvDbxLQ7%C9WZ~_5&8v2a>q}{1O#mr
zrjQqkB5c^0T+paDfYR=sDeP@6LW><hGY#tmO$<rEw6#YedADB)m{K+Zc^2&0udwd%
zJ2AJ)L~V7it5{OgD)|Pp7c7Mpxd(PTt#Kj}<UBzdAOn*L$=HGtH|ojqq&YS+IFsO9
z>etd(f)e)rXWq(&8M5HmZy<`RF|Rz<Q{3<N(J9}Ph7Cl5bt~?L6I%`|Z0T!ESF}FE
zA$2y-wF}qDBB#VW(e1%F<=Cp@wX*-lrvd}l?Mr(j(0T*jTGozg@3}sZPEw~d2`GtJ
zyL>U6_yan-WCqtCnnT)1c10pX*9Uor0gtmO+b0C_OgM=ZaGdL~?wJN{FPxh6os9mt
zad%{(YX%nG0L7n#X_do{k^fSetR2Xq2e<;Agc&d)^?LJvz}jVxx=*HOd<-a#&z)<c
zw${PS1!uu99|kvW*T)@N(2nF#F_#}?29!*=`^*}qq33I)^E#yZ2G%Wm-5ctqQKiy}
zff*_}Iv~us=Xxmh4`BRyP)W0}De#GoK@RB}r}J57E|m8(dHVorOG8iW=qe+7JD7R|
zZJSo&t+(uMHt7dW!zhZOYKa>XI*IVN0B!*{3*FT$RP0FCq_U*^*GJGrgH$i*)eRCH
zhlb&=fU&0#-v1m{ua4{Ey@)(%eavZJsAk?OHxD4pU34~-F%44A0WcLxR)Dbx3@fk8
zg6kZ5h1W)IO=dF~e-B{W!PQy__Bz%*wzK1<Zm&PB8;lH|HRxgpC%d7`7Z)LH6oTP=
zI7HZ-j?_0Czzou!;YYyo52N-cUhP;17%D6I=^DQC%?2G+9F;p6j#V(!Qv4d2Ys%py
zgC9G_P<!>Dx93p!V+K?)O^O`SM-5HO_b;Q*AqVsq{|}(`NEOe?t2F=s002ovPDHLk
FV1nE|XcYhe

literal 0
HcmV?d00001

diff --git a/editors/vscode/package-lock.json b/editors/vscode/package-lock.json
index 9dd18d0..4c0768d 100644
--- a/editors/vscode/package-lock.json
+++ b/editors/vscode/package-lock.json
@@ -7,31 +7,851 @@
     "": {
       "name": "vscode-py-doc-preview",
       "version": "1.0.0",
+      "dependencies": {
+        "js-yaml": "^4.1.0"
+      },
       "devDependencies": {
+        "@eslint/js": "^9.39.1",
+        "eslint": "^9.39.1",
+        "globals": "^16.5.0",
         "markdown-it": "^14.1.0"
       },
       "engines": {
-        "vscode": "^1.75.0"
+        "vscode": "^1.75.0"
+      }
+    },
+    "node_modules/@eslint-community/eslint-utils": {
+      "version": "4.10.1",
+      "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.10.1.tgz",
+      "integrity": "sha512-cuadcxVFE8sDK6iWJbs8Sn0av2Nrh2QSGQhVlBW9AaAHqHwjWsZHT8LJ4hFGPh7ASBV2deFdM7H/DPjulmh8rg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "eslint-visitor-keys": "^3.4.3"
+      },
+      "engines": {
+        "node": "^12.22.0 || ^14.17.0 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/eslint"
+      },
+      "peerDependencies": {
+        "eslint": "^6.0.0 || ^7.0.0 || >=8.0.0"
+      }
+    },
+    "node_modules/@eslint-community/eslint-utils/node_modules/eslint-visitor-keys": {
+      "version": "3.4.3",
+      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-3.4.3.tgz",
+      "integrity": "sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": "^12.22.0 || ^14.17.0 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/eslint"
+      }
+    },
+    "node_modules/@eslint-community/regexpp": {
+      "version": "4.12.2",
+      "resolved": "https://registry.npmjs.org/@eslint-community/regexpp/-/regexpp-4.12.2.tgz",
+      "integrity": "sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^12.0.0 || ^14.0.0 || >=16.0.0"
+      }
+    },
+    "node_modules/@eslint/config-array": {
+      "version": "0.21.2",
+      "resolved": "https://registry.npmjs.org/@eslint/config-array/-/config-array-0.21.2.tgz",
+      "integrity": "sha512-nJl2KGTlrf9GjLimgIru+V/mzgSK0ABCDQRvxw5BjURL7WfH5uoWmizbH7QB6MmnMBd8cIC9uceWnezL1VZWWw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@eslint/object-schema": "^2.1.7",
+        "debug": "^4.3.1",
+        "minimatch": "^3.1.5"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      }
+    },
+    "node_modules/@eslint/config-helpers": {
+      "version": "0.4.2",
+      "resolved": "https://registry.npmjs.org/@eslint/config-helpers/-/config-helpers-0.4.2.tgz",
+      "integrity": "sha512-gBrxN88gOIf3R7ja5K9slwNayVcZgK6SOUORm2uBzTeIEfeVaIhOpCtTox3P6R7o2jLFwLFTLnC7kU/RGcYEgw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@eslint/core": "^0.17.0"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      }
+    },
+    "node_modules/@eslint/core": {
+      "version": "0.17.0",
+      "resolved": "https://registry.npmjs.org/@eslint/core/-/core-0.17.0.tgz",
+      "integrity": "sha512-yL/sLrpmtDaFEiUj1osRP4TI2MDz1AddJL+jZ7KSqvBuliN4xqYY54IfdN8qD8Toa6g1iloph1fxQNkjOxrrpQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@types/json-schema": "^7.0.15"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      }
+    },
+    "node_modules/@eslint/eslintrc": {
+      "version": "3.3.7",
+      "resolved": "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-3.3.7.tgz",
+      "integrity": "sha512-F42g89Qd5oAWtp0k0nnSrjziAKza7w8SVT4mStc18LZMaRb4J1HQAHLCalEtDCxrTuksx7NU9qsmeLwpOfPqWw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ajv": "^6.14.0",
+        "debug": "^4.3.2",
+        "espree": "^10.0.1",
+        "globals": "^14.0.0",
+        "ignore": "^5.2.0",
+        "import-fresh": "^3.2.1",
+        "js-yaml": "^4.3.2",
+        "minimatch": "^3.1.5",
+        "strip-json-comments": "^3.1.1"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/eslint"
+      }
+    },
+    "node_modules/@eslint/eslintrc/node_modules/globals": {
+      "version": "14.0.0",
+      "resolved": "https://registry.npmjs.org/globals/-/globals-14.0.0.tgz",
+      "integrity": "sha512-oahGvuMGQlPw/ivIYBjVSrWAfWLBeku5tpPE2fOPLi+WHffIWbuh2tCjhyQhTBPMf5E9jDEH4FOmTYgYwbKwtQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/@eslint/js": {
+      "version": "9.39.1",
+      "resolved": "https://registry.npmjs.org/@eslint/js/-/js-9.39.1.tgz",
+      "integrity": "sha512-S26Stp4zCy88tH94QbBv3XCuzRQiZ9yXofEILmglYTh/Ug/a9/umqvgFtYBAo3Lp0nsI/5/qH1CCrbdK3AP1Tw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "url": "https://eslint.org/donate"
+      }
+    },
+    "node_modules/@eslint/object-schema": {
+      "version": "2.1.7",
+      "resolved": "https://registry.npmjs.org/@eslint/object-schema/-/object-schema-2.1.7.tgz",
+      "integrity": "sha512-VtAOaymWVfZcmZbp6E2mympDIHvyjXs/12LqWYjVw6qjrfF+VK+fyG33kChz3nnK+SU5/NeHOqrTEHS8sXO3OA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      }
+    },
+    "node_modules/@eslint/plugin-kit": {
+      "version": "0.4.1",
+      "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.4.1.tgz",
+      "integrity": "sha512-43/qtrDUokr7LJqoF2c3+RInu/t4zfrpYdoSDfYyhg52rwLV6TnOvdG4fXm7IkSB3wErkcmJS9iEhjVtOSEjjA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@eslint/core": "^0.17.0",
+        "levn": "^0.4.1"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      }
+    },
+    "node_modules/@humanfs/core": {
+      "version": "0.19.2",
+      "resolved": "https://registry.npmjs.org/@humanfs/core/-/core-0.19.2.tgz",
+      "integrity": "sha512-UhXNm+CFMWcbChXywFwkmhqjs3PRCmcSa/hfBgLIb7oQ5HNb1wS0icWsGtSAUNgefHeI+eBrA8I1fxmbHsGdvA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@humanfs/types": "^0.15.0"
+      },
+      "engines": {
+        "node": ">=18.18.0"
+      }
+    },
+    "node_modules/@humanfs/node": {
+      "version": "0.16.8",
+      "resolved": "https://registry.npmjs.org/@humanfs/node/-/node-0.16.8.tgz",
+      "integrity": "sha512-gE1eQNZ3R++kTzFUpdGlpmy8kDZD/MLyHqDwqjkVQI0JMdI1D51sy1H958PNXYkM2rAac7e5/CnIKZrHtPh3BQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@humanfs/core": "^0.19.2",
+        "@humanfs/types": "^0.15.0",
+        "@humanwhocodes/retry": "^0.4.0"
+      },
+      "engines": {
+        "node": ">=18.18.0"
+      }
+    },
+    "node_modules/@humanfs/types": {
+      "version": "0.15.0",
+      "resolved": "https://registry.npmjs.org/@humanfs/types/-/types-0.15.0.tgz",
+      "integrity": "sha512-ZZ1w0aoQkwuUuC7Yf+7sdeaNfqQiiLcSRbfI08oAxqLtpXQr9AIVX7Ay7HLDuiLYAaFPu8oBYNq/QIi9URHJ3Q==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=18.18.0"
+      }
+    },
+    "node_modules/@humanwhocodes/module-importer": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/@humanwhocodes/module-importer/-/module-importer-1.0.1.tgz",
+      "integrity": "sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=12.22"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/nzakas"
+      }
+    },
+    "node_modules/@humanwhocodes/retry": {
+      "version": "0.4.3",
+      "resolved": "https://registry.npmjs.org/@humanwhocodes/retry/-/retry-0.4.3.tgz",
+      "integrity": "sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=18.18"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/nzakas"
+      }
+    },
+    "node_modules/@types/estree": {
+      "version": "1.0.9",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
+      "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/json-schema": {
+      "version": "7.0.15",
+      "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.15.tgz",
+      "integrity": "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/acorn": {
+      "version": "8.19.0",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.19.0.tgz",
+      "integrity": "sha512-oJlA3XiRm7Cyk6qFD2Jn8ak9B7jSy0qy00ADO3+8dpT0LSjFihQYv4C02LFCSYJV3Q37xYwwRy5m+IpIiUzqWw==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "acorn": "bin/acorn"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
+    "node_modules/acorn-jsx": {
+      "version": "5.3.2",
+      "resolved": "https://registry.npmjs.org/acorn-jsx/-/acorn-jsx-5.3.2.tgz",
+      "integrity": "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0"
+      }
+    },
+    "node_modules/ajv": {
+      "version": "6.15.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.15.0.tgz",
+      "integrity": "sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.1",
+        "fast-json-stable-stringify": "^2.0.0",
+        "json-schema-traverse": "^0.4.1",
+        "uri-js": "^4.2.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/ansi-styles": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
+      "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "color-convert": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/argparse": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
+      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+      "license": "Python-2.0"
+    },
+    "node_modules/balanced-match": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
+      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/brace-expansion": {
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz",
+      "integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "balanced-match": "^1.0.0",
+        "concat-map": "0.0.1"
+      }
+    },
+    "node_modules/callsites": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/callsites/-/callsites-3.1.0.tgz",
+      "integrity": "sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/chalk": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz",
+      "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^4.1.0",
+        "supports-color": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/chalk?sponsor=1"
+      }
+    },
+    "node_modules/color-convert": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
+      "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "color-name": "~1.1.4"
+      },
+      "engines": {
+        "node": ">=7.0.0"
+      }
+    },
+    "node_modules/color-name": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
+      "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/concat-map": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
+      "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/cross-spawn": {
+      "version": "7.0.6",
+      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+      "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "path-key": "^3.1.0",
+        "shebang-command": "^2.0.0",
+        "which": "^2.0.1"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/debug": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ms": "^2.1.3"
+      },
+      "engines": {
+        "node": ">=6.0"
+      },
+      "peerDependenciesMeta": {
+        "supports-color": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/deep-is": {
+      "version": "0.1.4",
+      "resolved": "https://registry.npmjs.org/deep-is/-/deep-is-0.1.4.tgz",
+      "integrity": "sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/entities": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
+      "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
+    "node_modules/escape-string-regexp": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz",
+      "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/eslint": {
+      "version": "9.39.1",
+      "resolved": "https://registry.npmjs.org/eslint/-/eslint-9.39.1.tgz",
+      "integrity": "sha512-BhHmn2yNOFA9H9JmmIVKJmd288g9hrVRDkdoIgRCRuSySRUHH7r/DI6aAXW9T1WwUuY3DFgrcaqB+deURBLR5g==",
+      "deprecated": "This version is no longer supported. Please see https://eslint.org/version-support for other options.",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@eslint-community/eslint-utils": "^4.8.0",
+        "@eslint-community/regexpp": "^4.12.1",
+        "@eslint/config-array": "^0.21.1",
+        "@eslint/config-helpers": "^0.4.2",
+        "@eslint/core": "^0.17.0",
+        "@eslint/eslintrc": "^3.3.1",
+        "@eslint/js": "9.39.1",
+        "@eslint/plugin-kit": "^0.4.1",
+        "@humanfs/node": "^0.16.6",
+        "@humanwhocodes/module-importer": "^1.0.1",
+        "@humanwhocodes/retry": "^0.4.2",
+        "@types/estree": "^1.0.6",
+        "ajv": "^6.12.4",
+        "chalk": "^4.0.0",
+        "cross-spawn": "^7.0.6",
+        "debug": "^4.3.2",
+        "escape-string-regexp": "^4.0.0",
+        "eslint-scope": "^8.4.0",
+        "eslint-visitor-keys": "^4.2.1",
+        "espree": "^10.4.0",
+        "esquery": "^1.5.0",
+        "esutils": "^2.0.2",
+        "fast-deep-equal": "^3.1.3",
+        "file-entry-cache": "^8.0.0",
+        "find-up": "^5.0.0",
+        "glob-parent": "^6.0.2",
+        "ignore": "^5.2.0",
+        "imurmurhash": "^0.1.4",
+        "is-glob": "^4.0.0",
+        "json-stable-stringify-without-jsonify": "^1.0.1",
+        "lodash.merge": "^4.6.2",
+        "minimatch": "^3.1.2",
+        "natural-compare": "^1.4.0",
+        "optionator": "^0.9.3"
+      },
+      "bin": {
+        "eslint": "bin/eslint.js"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "url": "https://eslint.org/donate"
+      },
+      "peerDependencies": {
+        "jiti": "*"
+      },
+      "peerDependenciesMeta": {
+        "jiti": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/eslint-scope": {
+      "version": "8.4.0",
+      "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-8.4.0.tgz",
+      "integrity": "sha512-sNXOfKCn74rt8RICKMvJS7XKV/Xk9kA7DyJr8mJik3S7Cwgy3qlkkmyS2uQB3jiJg6VNdZd/pDBJu0nvG2NlTg==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "esrecurse": "^4.3.0",
+        "estraverse": "^5.2.0"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/eslint"
+      }
+    },
+    "node_modules/eslint-visitor-keys": {
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.1.tgz",
+      "integrity": "sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/eslint"
+      }
+    },
+    "node_modules/espree": {
+      "version": "10.4.0",
+      "resolved": "https://registry.npmjs.org/espree/-/espree-10.4.0.tgz",
+      "integrity": "sha512-j6PAQ2uUr79PZhBjP5C5fhl8e39FmRnOjsD5lGnWrFU8i2G776tBK7+nP8KuQUTTyAZUwfQqXAgrVH5MbH9CYQ==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "acorn": "^8.15.0",
+        "acorn-jsx": "^5.3.2",
+        "eslint-visitor-keys": "^4.2.1"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/eslint"
+      }
+    },
+    "node_modules/esquery": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/esquery/-/esquery-1.7.0.tgz",
+      "integrity": "sha512-Ap6G0WQwcU/LHsvLwON1fAQX9Zp0A2Y6Y/cJBl9r/JbW90Zyg4/zbG6zzKa2OTALELarYHmKu0GhpM5EO+7T0g==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "estraverse": "^5.1.0"
+      },
+      "engines": {
+        "node": ">=0.10"
+      }
+    },
+    "node_modules/esrecurse": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/esrecurse/-/esrecurse-4.3.0.tgz",
+      "integrity": "sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "estraverse": "^5.2.0"
+      },
+      "engines": {
+        "node": ">=4.0"
+      }
+    },
+    "node_modules/estraverse": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-5.3.0.tgz",
+      "integrity": "sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=4.0"
+      }
+    },
+    "node_modules/esutils": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/esutils/-/esutils-2.0.3.tgz",
+      "integrity": "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/fast-deep-equal": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+      "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/fast-json-stable-stringify": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz",
+      "integrity": "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/fast-levenshtein": {
+      "version": "2.0.6",
+      "resolved": "https://registry.npmjs.org/fast-levenshtein/-/fast-levenshtein-2.0.6.tgz",
+      "integrity": "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/file-entry-cache": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-8.0.0.tgz",
+      "integrity": "sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "flat-cache": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=16.0.0"
       }
     },
-    "node_modules/argparse": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
-      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+    "node_modules/find-up": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/find-up/-/find-up-5.0.0.tgz",
+      "integrity": "sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==",
       "dev": true,
-      "license": "Python-2.0"
+      "license": "MIT",
+      "dependencies": {
+        "locate-path": "^6.0.0",
+        "path-exists": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
     },
-    "node_modules/entities": {
-      "version": "4.5.0",
-      "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
-      "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==",
+    "node_modules/flat-cache": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/flat-cache/-/flat-cache-4.0.1.tgz",
+      "integrity": "sha512-f7ccFPK3SXFHpx15UIGyRJ/FJQctuKZ0zVuN3frBo4HnK3cay9VEW0R6yPYFHC0AgqhukPzKjq22t5DmAyqGyw==",
       "dev": true,
-      "license": "BSD-2-Clause",
+      "license": "MIT",
+      "dependencies": {
+        "flatted": "^3.2.9",
+        "keyv": "^4.5.4"
+      },
       "engines": {
-        "node": ">=0.12"
+        "node": ">=16"
+      }
+    },
+    "node_modules/flatted": {
+      "version": "3.4.4",
+      "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.4.4.tgz",
+      "integrity": "sha512-5+ybhBZANEJxaH3X5evAFatUxLfEHSr7n6kYJ+1Qd0mUqr4eu9gIf6GDbWHf8RJijHrjjO8G+la14SlL2SeS1Q==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/glob-parent": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-6.0.2.tgz",
+      "integrity": "sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "is-glob": "^4.0.3"
+      },
+      "engines": {
+        "node": ">=10.13.0"
+      }
+    },
+    "node_modules/globals": {
+      "version": "16.5.0",
+      "resolved": "https://registry.npmjs.org/globals/-/globals-16.5.0.tgz",
+      "integrity": "sha512-c/c15i26VrJ4IRt5Z89DnIzCGDn9EcebibhAOjw5ibqEHsE1wLUgkPn9RDmNcUKyU87GeaL633nyJ+pplFR2ZQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
       },
       "funding": {
-        "url": "https://github.com/fb55/entities?sponsor=1"
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/has-flag": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz",
+      "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/ignore": {
+      "version": "5.3.2",
+      "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz",
+      "integrity": "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 4"
+      }
+    },
+    "node_modules/import-fresh": {
+      "version": "3.3.1",
+      "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.1.tgz",
+      "integrity": "sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "parent-module": "^1.0.0",
+        "resolve-from": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/imurmurhash": {
+      "version": "0.1.4",
+      "resolved": "https://registry.npmjs.org/imurmurhash/-/imurmurhash-0.1.4.tgz",
+      "integrity": "sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.8.19"
+      }
+    },
+    "node_modules/is-extglob": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
+      "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/is-glob": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz",
+      "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "is-extglob": "^2.1.1"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/isexe": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
+      "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/js-yaml": {
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.2.tgz",
+      "integrity": "sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/puzrin"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/nodeca"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1"
+      },
+      "bin": {
+        "js-yaml": "bin/js-yaml.js"
+      }
+    },
+    "node_modules/json-buffer": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/json-buffer/-/json-buffer-3.0.1.tgz",
+      "integrity": "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/json-schema-traverse": {
+      "version": "0.4.1",
+      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz",
+      "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/json-stable-stringify-without-jsonify": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/json-stable-stringify-without-jsonify/-/json-stable-stringify-without-jsonify-1.0.1.tgz",
+      "integrity": "sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/keyv": {
+      "version": "4.5.4",
+      "resolved": "https://registry.npmjs.org/keyv/-/keyv-4.5.4.tgz",
+      "integrity": "sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "json-buffer": "3.0.1"
+      }
+    },
+    "node_modules/levn": {
+      "version": "0.4.1",
+      "resolved": "https://registry.npmjs.org/levn/-/levn-0.4.1.tgz",
+      "integrity": "sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "prelude-ls": "^1.2.1",
+        "type-check": "~0.4.0"
+      },
+      "engines": {
+        "node": ">= 0.8.0"
       }
     },
     "node_modules/linkify-it": {
@@ -54,6 +874,29 @@
         "uc.micro": "^2.0.0"
       }
     },
+    "node_modules/locate-path": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz",
+      "integrity": "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "p-locate": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/lodash.merge": {
+      "version": "4.6.2",
+      "resolved": "https://registry.npmjs.org/lodash.merge/-/lodash.merge-4.6.2.tgz",
+      "integrity": "sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/markdown-it": {
       "version": "14.3.3",
       "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.3.3.tgz",
@@ -89,6 +932,136 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/minimatch": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "brace-expansion": "^1.1.7"
+      },
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/ms": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/natural-compare": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/natural-compare/-/natural-compare-1.4.0.tgz",
+      "integrity": "sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/optionator": {
+      "version": "0.9.4",
+      "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.9.4.tgz",
+      "integrity": "sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "deep-is": "^0.1.3",
+        "fast-levenshtein": "^2.0.6",
+        "levn": "^0.4.1",
+        "prelude-ls": "^1.2.1",
+        "type-check": "^0.4.0",
+        "word-wrap": "^1.2.5"
+      },
+      "engines": {
+        "node": ">= 0.8.0"
+      }
+    },
+    "node_modules/p-limit": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz",
+      "integrity": "sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "yocto-queue": "^0.1.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/p-locate": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-5.0.0.tgz",
+      "integrity": "sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "p-limit": "^3.0.2"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/parent-module": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz",
+      "integrity": "sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "callsites": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/path-exists": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz",
+      "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/path-key": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
+      "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/prelude-ls": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz",
+      "integrity": "sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8.0"
+      }
+    },
+    "node_modules/punycode": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz",
+      "integrity": "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/punycode.js": {
       "version": "2.3.1",
       "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz",
@@ -99,12 +1072,133 @@
         "node": ">=6"
       }
     },
+    "node_modules/resolve-from": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-4.0.0.tgz",
+      "integrity": "sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/shebang-command": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
+      "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "shebang-regex": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/shebang-regex": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
+      "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/strip-json-comments": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz",
+      "integrity": "sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/supports-color": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",
+      "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "has-flag": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/type-check": {
+      "version": "0.4.0",
+      "resolved": "https://registry.npmjs.org/type-check/-/type-check-0.4.0.tgz",
+      "integrity": "sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "prelude-ls": "^1.2.1"
+      },
+      "engines": {
+        "node": ">= 0.8.0"
+      }
+    },
     "node_modules/uc.micro": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz",
       "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==",
       "dev": true,
       "license": "MIT"
+    },
+    "node_modules/uri-js": {
+      "version": "4.4.1",
+      "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz",
+      "integrity": "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "punycode": "^2.1.0"
+      }
+    },
+    "node_modules/which": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
+      "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "isexe": "^2.0.0"
+      },
+      "bin": {
+        "node-which": "bin/node-which"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/word-wrap": {
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/word-wrap/-/word-wrap-1.2.5.tgz",
+      "integrity": "sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/yocto-queue": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz",
+      "integrity": "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
     }
   }
 }
diff --git a/editors/vscode/package.json b/editors/vscode/package.json
index c6faeeb..04d9ec1 100644
--- a/editors/vscode/package.json
+++ b/editors/vscode/package.json
@@ -4,13 +4,24 @@
   "description": "Preview py-doc Markdown in VS Code: numbered captions, Word-style callouts, slide decks, and posters.",
   "version": "1.0.0",
   "publisher": "py-doc",
+  "license": "MIT",
+  "icon": "images/icon.png",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/markbac/py-doc.git",
+    "directory": "editors/vscode"
+  },
+  "bugs": {
+    "url": "https://github.com/markbac/py-doc/issues"
+  },
+  "homepage": "https://github.com/markbac/py-doc/tree/main/editors/vscode#readme",
   "engines": {
     "vscode": "^1.75.0"
   },
   "main": "./extension.js",
   "categories": [
     "Other",
-    "Formatters"
+    "Visualization"
   ],
   "keywords": [
     "py-doc",
@@ -68,8 +79,16 @@
       "properties": {
         "pydoc.watch.port": {
           "type": "number",
-          "default": 8765,
-          "description": "The local port the live preview watch server (py-doc ... --watch) serves on."
+          "default": 0,
+          "minimum": 0,
+          "maximum": 65535,
+          "description": "The local port the live preview serves on. 0 lets py-doc pick a free one, so several windows can each have a preview."
+        },
+        "pydoc.executable": {
+          "type": "string",
+          "default": "py-doc",
+          "scope": "machine-overridable",
+          "description": "The py-doc program the live preview runs, such as the py-doc of a virtual environment (.venv/Scripts/py-doc.exe or .venv/bin/py-doc)."
         }
       }
     },
@@ -79,9 +98,16 @@
     ]
   },
   "scripts": {
-    "test": "node test/test.js"
+    "test": "node --test test/test.js test/cases.test.js test/watch.test.js",
+    "lint": "eslint ."
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "eslint": "^9.39.1",
+    "globals": "^16.5.0",
     "markdown-it": "^14.1.0"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
   }
 }
diff --git a/editors/vscode/src/detect.js b/editors/vscode/src/detect.js
new file mode 100644
index 0000000..450eb62
--- /dev/null
+++ b/editors/vscode/src/detect.js
@@ -0,0 +1,43 @@
+'use strict';
+
+const { asText } = require('./text');
+const { splitFrontMatter } = require('./frontmatter');
+
+// Front matter keys only a poster has (see py_doc/poster_settings.py)
+const POSTER_KEYS = ['paper', 'byline', 'orientation', 'theme', 'columns', 'width', 'colours', 'palette', 'embed_fonts', 'logo'];
+const SLIDE_DIVS = /^:{3,4}\s*\{?\.?(columns|column|notes|incremental)\}?\s*$/;
+
+/**
+ * Which py-doc command a Markdown file is for: 'poster', 'slides' or 'docx'.
+ * Decided from the front matter, then from blocks only a deck has (columns, speaker notes, incremental lists).
+ * The instant preview and the live watch button both use this, so they always agree.
+ */
+function detectFormat(meta, body) {
+  meta = meta || {};
+  const fmt = asText(meta.format || meta.output || meta.type || meta.layout).toLowerCase();
+  if (fmt.includes('pptx') || fmt.includes('slide') || meta.split_level) return 'slides';
+  if (fmt.includes('poster') || POSTER_KEYS.some((k) => meta[k] !== undefined && meta[k] !== '')) return 'poster';
+
+  let fence = null;
+  for (const line of (body || '').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/);
+    if (fenceMatch) {
+      if (!fence) fence = fenceMatch[1][0];
+      else if (trimmed[0] === fence) fence = null;
+      continue;
+    }
+    if (fence) continue;
+    if (SLIDE_DIVS.test(trimmed) || /^<!--\s*notes:/i.test(trimmed)) return 'slides';
+  }
+  return 'docx';
+}
+
+
+function detectDocumentFormat(document) {
+  const text = document && typeof document.getText === 'function' ? document.getText() : String(document);
+  const { meta, body } = splitFrontMatter(text);
+  return detectFormat(meta, body);
+}
+
+module.exports = { detectFormat, detectDocumentFormat, POSTER_KEYS };
diff --git a/editors/vscode/src/frontmatter.js b/editors/vscode/src/frontmatter.js
new file mode 100644
index 0000000..ead0f88
--- /dev/null
+++ b/editors/vscode/src/frontmatter.js
@@ -0,0 +1,21 @@
+'use strict';
+
+const yaml = require('js-yaml');
+
+// The core schema reads dates as text, as written, where the default one would make Date objects
+function parseFrontMatter(text) {
+  try {
+    const data = yaml.load(text, { schema: yaml.CORE_SCHEMA });
+    return data && typeof data === 'object' && !Array.isArray(data) ? data : {};
+  } catch (e) {
+    return {};  // the build reports a front matter that is not valid YAML; the preview shows the body
+  }
+}
+
+// The front matter between --- lines at the top of a file, and the text after it
+function splitFrontMatter(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/);
+  return m ? { meta: parseFrontMatter(m[1]), body: text.slice(m[0].length) } : { meta: {}, body: text };
+}
+
+module.exports = { parseFrontMatter, splitFrontMatter };
diff --git a/editors/vscode/src/plugin.js b/editors/vscode/src/plugin.js
new file mode 100644
index 0000000..36c5d48
--- /dev/null
+++ b/editors/vscode/src/plugin.js
@@ -0,0 +1,679 @@
+/**
+ * The instant preview: a markdown-it plugin for VS Code's built-in Markdown preview, for all py-doc outputs:
+ *  1. Word Technical Documents (.docx):
+ *     - Numbered captions: [[CAPTION:Figure]] text, [[CAPTION:Table]] text
+ *     - Word callout boxes: > [!NOTE] and > **Note:** text (Note, Tip, Important, Warning, Caution)
+ *     - Page breaks: [[PAGEBREAK]] and ::: {.pagebreak}
+ *     - Section breaks: [[LANDSCAPE]] and [[PORTRAIT]]
+ *     - Paragraph Word styles: [[STYLE:StyleName]] text
+ *     - Image width attributes: ![](images/board.png){width=60%}
+ *     - Diagram types: plantuml, dot/graphviz, ditaa, wavedrom, vega, bytefield, etc.
+ *     - Directives: [[INCLUDE:...]], [[INCLUDE-CODE:...]], [[IF:...]], [[ENDIF]]
+ *  2. PowerPoint Slide Decks (.pptx):
+ *     - Section Header slides (# Section Title)
+ *     - Content slide cards (## Slide Title) with slide footers
+ *     - Responsive two-column layouts (:::: columns / ::: column)
+ *     - Speaker notes (::: notes and <!-- notes: ... -->)
+ *     - Incremental lists (::: incremental)
+ *  3. HTML & PDF Posters (py-doc poster):
+ *     - Stat strip (## ... {.stats}) with KPI cards & trend indicators
+ *     - Abstract introduction banner (## ... {.abstract})
+ *     - Headings with colon accent (## 1. Title: Accent) and class stripping
+ *     - Card grid blocks (```cards cols=N style=...```)
+ *     - Segments bar blocks (```segments```)
+ *     - Flow sequence blocks (```flow```)
+ *     - Summary closing banner (## ... {.summary})
+ *     - Poster header & footer (paper size, byline, QR code label)
+ */
+
+'use strict';
+
+const { asText, cssName, escapeHtml } = require('./text');
+const { parseFrontMatter, splitFrontMatter } = require('./frontmatter');
+const { detectFormat } = require('./detect');
+
+const KINDS = {
+  NOTE: { title: 'Note', icon: 'ℹ️', class: 'note' },
+  TIP: { title: 'Tip', icon: '💡', class: 'tip' },
+  IMPORTANT: { title: 'Important', icon: '❗', class: 'important' },
+  WARNING: { title: 'Warning', icon: '⚠️', class: 'warning' },
+  CAUTION: { title: 'Caution', icon: '🛑', class: 'caution' },
+};
+
+const DIAGRAM_TYPES = new Set([
+  'mermaid', 'plantuml', 'puml', 'dot', 'graphviz', 'ditaa',
+  'blockdiag', 'seqdiag', 'actdiag', 'nwdiag', 'packetdiag',
+  'wavedrom', 'bytefield-svg', 'pikchr', 'railroad', 'wireviz',
+  'vega', 'vega-lite'
+]);
+
+function renderFrontMatterBlock(meta, docMode) {
+  if (!meta || Object.keys(meta).length === 0) return '';
+
+  if (docMode === 'poster') {
+    let html = '<div class="pydoc-poster-header">\n';
+    if (meta.title) {
+      html += `  <h1 class="pydoc-poster-title">${escapeHtml(meta.title)}</h1>\n`;
+    }
+    if (meta.subtitle) {
+      html += `  <div class="pydoc-poster-subtitle">${escapeHtml(meta.subtitle)}</div>\n`;
+    }
+    if (meta.byline) {
+      html += `  <div class="pydoc-poster-byline">${escapeHtml(meta.byline)}</div>\n`;
+    }
+    html += '  <div class="pydoc-poster-meta">\n';
+    if (meta.paper) {
+      html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Paper:</span> ${escapeHtml(asText(meta.paper).toUpperCase())}</span>\n`;
+    }
+    if (meta.document_number) {
+      html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Doc #:</span> ${escapeHtml(meta.document_number)}</span>\n`;
+    }
+    if (meta.version) {
+      html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Version:</span> ${escapeHtml(meta.version)}</span>\n`;
+    }
+    html += '  </div>\n';
+    html += '</div>\n';
+    return html;
+  }
+
+  const isSlide = (docMode === 'slide');
+  let html = `<div class="pydoc-frontmatter ${isSlide ? 'pydoc-slide-title' : ''}">\n`;
+  if (meta.title) {
+    html += `  <h1 class="pydoc-doc-title">${escapeHtml(meta.title)}</h1>\n`;
+  }
+  if (meta.subtitle) {
+    html += `  <div class="pydoc-doc-subtitle">${escapeHtml(meta.subtitle)}</div>\n`;
+  }
+  html += '  <div class="pydoc-doc-meta">\n';
+  if (meta.document_number) {
+    html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Doc #:</span> ${escapeHtml(meta.document_number)}</span>\n`;
+  }
+  if (meta.version) {
+    html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Version:</span> ${escapeHtml(meta.version)}</span>\n`;
+  }
+  if (meta.status) {
+    const statusClass = asText(meta.status).toLowerCase() === 'draft' ? 'draft' : 'released';
+    html += `    <span class="pydoc-meta-item pydoc-status-${statusClass}"><span class="pydoc-meta-key">Status:</span> ${escapeHtml(meta.status)}</span>\n`;
+  }
+  if (meta.author) {
+    html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Author:</span> ${escapeHtml(meta.author)}</span>\n`;
+  }
+  if (meta.date) {
+    html += `    <span class="pydoc-meta-item"><span class="pydoc-meta-key">Date:</span> ${escapeHtml(meta.date)}</span>\n`;
+  }
+  html += '  </div>\n';
+  html += '</div>\n';
+  return html;
+}
+
+const PREVIEW_MODE = { poster: 'poster', slides: 'slide', docx: 'document' };
+
+function pyDocPlugin(md) {
+  // The front matter token carries the mode of its document in .info, so a nested md.renderInline call
+  // (made while processing captions and callouts) cannot change how the outer document's header renders
+  md.renderer.rules.pydoc_front_matter = (ts, idx) => renderFrontMatterBlock(ts[idx].meta, ts[idx].info || 'document');
+
+  // 1. Block rule to parse Front Matter at line 0
+  md.block.ruler.before('table', 'pydoc_front_matter', (state, startLine, endLine, silent) => {
+    if (startLine !== 0) return false;
+    const start = state.bMarks[startLine] + state.tShift[startLine];
+    const max = state.eMarks[startLine];
+    if (state.src.slice(start, max).trim() !== '---') return false;
+
+    let nextLine = startLine + 1;
+    let found = false;
+    while (nextLine < endLine) {
+      const s = state.bMarks[nextLine] + state.tShift[nextLine];
+      const m = state.eMarks[nextLine];
+      if (state.src.slice(s, m).trim() === '---') {
+        found = true;
+        break;
+      }
+      nextLine++;
+    }
+    if (!found) return false;
+    if (silent) return true;
+
+    const yamlContent = state.src.slice(state.eMarks[startLine] + 1, state.bMarks[nextLine]);
+    state.line = nextLine + 1;
+
+    const token = state.push('pydoc_front_matter', '', 0);
+    token.meta = parseFrontMatter(yamlContent);
+    return true;
+  });
+
+  // 2. Block rule for fenced divs (:::: columns, ::: column, ::: notes, ::: incremental)
+  md.block.ruler.before('fence', 'pydoc_fenced_div', (state, startLine, endLine, silent) => {
+    const start = state.bMarks[startLine] + state.tShift[startLine];
+    const max = state.eMarks[startLine];
+    const lineText = state.src.slice(start, max).trim();
+
+    const openMatch = lineText.match(/^(:{3,4})\s*(?:\{\.([\w-]+)\}|([\w-]+))?(?:\s+(.*))?$/);
+    if (!openMatch) return false;
+
+    const colons = openMatch[1];
+    const tag = (openMatch[2] || openMatch[3] || '').trim().toLowerCase();
+    const isClosing = !tag && lineText === colons;
+
+    if (isClosing) return false;
+    if (silent) return true;
+
+    let nextLine = startLine + 1;
+    let found = false;
+    let depth = 1;
+
+    while (nextLine < endLine) {
+      const s = state.bMarks[nextLine] + state.tShift[nextLine];
+      const m = state.eMarks[nextLine];
+      const cur = state.src.slice(s, m).trim();
+
+      if (cur.startsWith(colons)) {
+        const subMatch = cur.match(/^(:{3,4})\s*(?:\{\.([\w-]+)\}|([\w-]+))?/);
+        if (subMatch && subMatch[1] === colons) {
+          if (!subMatch[2] && !subMatch[3]) {
+            depth--;
+            if (depth === 0) {
+              found = true;
+              break;
+            }
+          } else {
+            depth++;
+          }
+        }
+      }
+      nextLine++;
+    }
+
+    if (!found) return false;
+
+    if (tag === 'pagebreak') {
+      const pbreak = state.push('html_block', '', 0);
+      pbreak.content = '<div class="pydoc-pagebreak"><span class="pydoc-pagebreak-line"></span><span class="pydoc-badge">PAGE BREAK</span><span class="pydoc-pagebreak-line"></span></div>\n';
+      state.line = nextLine + 1;
+      return true;
+    }
+
+    const tokenOpen = state.push('pydoc_div_open', 'div', 1);
+    tokenOpen.block = true;
+    tokenOpen.attrs = [['class', `pydoc-div pydoc-${tag}`]];
+    tokenOpen.info = tag;
+
+    if (tag === 'notes') {
+      const notesHeader = state.push('html_block', '', 0);
+      notesHeader.content = '<div class="pydoc-speaker-notes-header"><span class="pydoc-notes-icon">📝</span> Speaker Notes</div>\n';
+    } else if (tag === 'incremental') {
+      const incBadge = state.push('html_block', '', 0);
+      incBadge.content = '<div class="pydoc-incremental-header"><span class="pydoc-inc-icon">⚡</span> Click-by-click list (incremental)</div>\n';
+    }
+
+    state.line = startLine + 1;
+    const oldParentType = state.parentType;
+    state.parentType = 'div';
+    state.md.block.tokenize(state, startLine + 1, nextLine);
+    state.parentType = oldParentType;
+
+    const tokenClose = state.push('pydoc_div_close', 'div', -1);
+    tokenClose.block = true;
+
+    state.line = nextLine + 1;
+    return true;
+  });
+
+  // 3. Core rule for py-doc markers, numbered captions, callouts, slides, and posters
+  md.core.ruler.push('pydoc_core', (state) => {
+    const counters = {};
+    const tokens = state.tokens;
+    const frontMeta = (tokens.length > 0 && tokens[0].type === 'pydoc_front_matter' && tokens[0].meta) || null;
+    const docTitle = (frontMeta && asText(frontMeta.title)) || 'py-doc Document';
+    const docMode = PREVIEW_MODE[detectFormat(frontMeta, splitFrontMatter(state.src).body)];
+    if (frontMeta) tokens[0].info = docMode;
+
+    for (let i = 0; i < tokens.length; i++) {
+      const token = tokens[i];
+
+      // A. Process Image width attributes: ![](img.png){width=60%}
+      if (token.type === 'inline' && token.children) {
+        for (let c = 0; c < token.children.length; c++) {
+          if (token.children[c].type === 'image') {
+            const nextChild = token.children[c + 1];
+            if (nextChild && nextChild.type === 'text') {
+              const m = nextChild.content.match(/^\{width=([^}]+)\}/);
+              if (m) {
+                const widthVal = m[1].replace(/["']/g, '').trim();
+                token.children[c].attrs = token.children[c].attrs || [];
+                token.children[c].attrs.push(['style', `width: ${widthVal}; max-width: 100%;`]);
+                nextChild.content = nextChild.content.replace(/^\{width=([^}]+)\}\s*/, '');
+              }
+            }
+          }
+        }
+      }
+
+      // B. Process HTML comments for speaker notes: <!-- notes: ... -->
+      if (token.type === 'html_block') {
+        const commentNoteMatch = token.content.match(/<!--\s*notes:\s*([\s\S]*?)\s*-->/i);
+        if (commentNoteMatch) {
+          const noteText = commentNoteMatch[1].trim();
+          token.content = `<div class="pydoc-div pydoc-notes"><div class="pydoc-speaker-notes-header"><span class="pydoc-notes-icon">📝</span> Speaker Notes</div><p>${escapeHtml(noteText)}</p></div>\n`;
+          continue;
+        }
+      }
+
+      // C. Process Headings: {.stats}, {.abstract}, {.summary}, {.references}, and accent colons
+      if (token.type === 'heading_open') {
+        const next = tokens[i + 1];
+        if (next && next.type === 'inline' && next.content) {
+          let text = next.content;
+
+          const classMatch = text.match(/\s*\{([.#][\w\s.-]+)\}\s*$/);
+          let headingClass = '';
+          if (classMatch) {
+            headingClass = classMatch[1].replace(/^\./, '').trim();
+            text = text.replace(/\s*\{([.#][\w\s.-]+)\}\s*$/, '').trim();
+            token.attrs = token.attrs || [];
+            token.attrs.push(['class', `pydoc-heading-${headingClass}`]);
+          }
+
+          next.content = text;
+          if (classMatch) {
+            for (const c of next.children) {
+              if (c.type === 'text') {
+                c.content = c.content.replace(/\s*\{([.#][\w\s.-]+)\}\s*$/, '');
+              }
+            }
+          } else if (docMode === 'poster') {
+            // Poster headings: what follows the first colon is the accent. The inline tokens are split, not
+            // re-rendered, so code, bold and links after the colon keep their formatting
+            const children = next.children || [];
+            const k = children.findIndex((c) => c.type === 'text' && c.content.indexOf(':') > 0);
+            if (k !== -1) {
+              const colon = children[k].content.indexOf(':');
+              const rest = children[k].content.slice(colon + 1);
+              children[k].content = children[k].content.slice(0, colon + 1);
+              const open = new state.Token('html_inline', '', 0);
+              open.content = '<span class="pydoc-heading-accent">';
+              const restToken = new state.Token('text', '', 0);
+              restToken.content = rest;
+              const close = new state.Token('html_inline', '', 0);
+              close.content = '</span>';
+              children.splice(k + 1, 0, open, restToken);
+              children.push(close);
+            }
+          }
+
+          if (headingClass === 'stats') {
+            let tableOpenIdx = -1;
+            let tableCloseIdx = -1;
+            for (let j = i + 1; j < tokens.length; j++) {
+              if (tokens[j].type === 'table_open') tableOpenIdx = j;
+              if (tokens[j].type === 'table_close') {
+                tableCloseIdx = j;
+                break;
+              }
+              if (tokens[j].type === 'heading_open') break;
+            }
+
+            if (tableOpenIdx !== -1 && tableCloseIdx !== -1) {
+              const rows = [];
+              let curRow = null;
+              let inTbody = false;
+
+              for (let k = tableOpenIdx; k <= tableCloseIdx; k++) {
+                if (tokens[k].type === 'tbody_open') inTbody = true;
+                if (tokens[k].type === 'tbody_close') inTbody = false;
+                if (inTbody) {
+                  if (tokens[k].type === 'tr_open') curRow = [];
+                  if (tokens[k].type === 'tr_close' && curRow) {
+                    rows.push(curRow);
+                    curRow = null;
+                  }
+                  if (tokens[k].type === 'inline' && curRow) {
+                    curRow.push(tokens[k].content);
+                  }
+                }
+              }
+
+              let statsHtml = '<div class="pydoc-poster-stats">\n';
+              for (const r of rows) {
+                const val = r[0] || '';
+                const label = r[1] || '';
+                const change = r[2] || '';
+                const verdict = (r[3] || '').toLowerCase().trim();
+                const changeClass = verdict ? verdict : (change.startsWith('+') ? 'good' : (change.startsWith('-') ? 'bad' : ''));
+
+                statsHtml += '  <div class="pydoc-stat-card">\n';
+                statsHtml += `    <div class="pydoc-stat-value">${escapeHtml(val)}</div>\n`;
+                statsHtml += `    <div class="pydoc-stat-label">${escapeHtml(label)}</div>\n`;
+                if (change) {
+                  statsHtml += `    <div class="pydoc-stat-change ${changeClass}">${escapeHtml(change)}</div>\n`;
+                }
+                statsHtml += '  </div>\n';
+              }
+              statsHtml += '</div>\n';
+
+              const replacement = new state.Token('html_block', '', 0);
+              replacement.content = statsHtml;
+              tokens.splice(tableOpenIdx, (tableCloseIdx - tableOpenIdx + 1), replacement);
+            }
+          }
+        }
+      }
+
+      // D. Fenced Blocks: ```cards```, ```segments```, ```flow```, and diagram types
+      if (token.type === 'fence') {
+        const rawInfo = token.info.trim();
+        const mainTag = rawInfo.split(/\s+/)[0].toLowerCase();
+
+        // Cards: ```cards cols=3 style=top```
+        if (mainTag === 'cards') {
+          const lines = token.content.split('\n').filter(l => l.trim());
+          let cardsHtml = '<div class="pydoc-cards-grid">\n';
+          for (const line of lines) {
+            const parts = line.split('|').map(s => s.trim());
+            if (parts.length >= 2) {
+              const title = parts[0];
+              const desc = parts[1];
+              const color = parts[2] || 'blue';
+              cardsHtml += `  <div class="pydoc-card-item pydoc-card-${cssName(color)}">\n`;
+              cardsHtml += `    <div class="pydoc-card-title">${escapeHtml(title)}</div>\n`;
+              cardsHtml += `    <div class="pydoc-card-desc">${escapeHtml(desc)}</div>\n`;
+              cardsHtml += '  </div>\n';
+            }
+          }
+          cardsHtml += '</div>\n';
+          token.type = 'html_block';
+          token.content = cardsHtml;
+          continue;
+        }
+
+        // Segments: ```segments```
+        if (mainTag === 'segments') {
+          const lines = token.content.split('\n').filter(l => l.trim());
+          let segTitle = '';
+          const items = [];
+          for (const line of lines) {
+            if (line.toLowerCase().startsWith('title:')) {
+              segTitle = line.replace(/^title:\s*/i, '');
+            } else {
+              const parts = line.split('|').map(s => s.trim());
+              if (parts.length >= 2) {
+                items.push({
+                  weight: parts[0],
+                  label: parts[1],
+                  value: parts[2] || '',
+                  color: parts[3] || 'blue'
+                });
+              }
+            }
+          }
+
+          let segHtml = '<div class="pydoc-segments-box">\n';
+          if (segTitle) {
+            segHtml += `  <div class="pydoc-segments-title">${escapeHtml(segTitle)}</div>\n`;
+          }
+          segHtml += '  <div class="pydoc-segments-bar">\n';
+          for (const it of items) {
+            segHtml += `    <div class="pydoc-segment-slice pydoc-bg-${cssName(it.color)}" style="flex: ${Number.parseFloat(it.weight) || 1}" title="${escapeHtml(it.label)}: ${escapeHtml(it.value)}"><span class="pydoc-segment-text">${escapeHtml(it.label)}</span></div>\n`;
+          }
+          segHtml += '  </div>\n';
+          segHtml += '</div>\n';
+          token.type = 'html_block';
+          token.content = segHtml;
+          continue;
+        }
+
+        // Flow: ```flow```
+        if (mainTag === 'flow') {
+          const lines = token.content.split('\n').filter(l => l.trim());
+          let flowHtml = '<div class="pydoc-flow-diagram">\n';
+          for (const line of lines) {
+            const parts = line.split(/-(.*?)->/).map(s => s.trim());
+            flowHtml += '  <div class="pydoc-flow-step">\n';
+            for (let p = 0; p < parts.length; p++) {
+              const item = parts[p];
+              if (p % 2 === 0) {
+                const nodeMatch = item.match(/^\[(.*?)(?:\|(.*?))?\]$/);
+                const nodeText = nodeMatch ? nodeMatch[1] : item;
+                const nodeColor = (nodeMatch && nodeMatch[2]) ? nodeMatch[2] : 'blue';
+                flowHtml += `    <span class="pydoc-flow-node pydoc-bg-${cssName(nodeColor)}">${escapeHtml(nodeText)}</span>\n`;
+              } else {
+                flowHtml += `    <span class="pydoc-flow-arrow">➔ ${escapeHtml(item)}</span>\n`;
+              }
+            }
+            flowHtml += '  </div>\n';
+          }
+          flowHtml += '</div>\n';
+          token.type = 'html_block';
+          token.content = flowHtml;
+          continue;
+        }
+
+        // Other py-doc diagram types (plantuml, dot, ditaa, wavedrom, vega, bytefield, etc.)
+        if (DIAGRAM_TYPES.has(mainTag) && mainTag !== 'mermaid') {
+          const titleMatch = rawInfo.match(/(?:title|caption)=["']?([^"']+)["']?/i);
+          const diagTitle = titleMatch ? titleMatch[1] : '';
+          const escapedContent = md.utils.escapeHtml(token.content);
+
+          token.type = 'html_block';
+          token.content = `<div class="pydoc-diagram-box" data-diagram="${mainTag}">\n` +
+            `  <div class="pydoc-diagram-header"><span class="pydoc-diagram-badge">${mainTag.toUpperCase()}</span>${diagTitle ? ` <span class="pydoc-diagram-title">${escapeHtml(diagTitle)}</span>` : ''}</div>\n` +
+            `  <pre class="pydoc-diagram-code"><code>${escapedContent}</code></pre>\n` +
+            `</div>\n`;
+          continue;
+        }
+      }
+
+      // E. Process Paragraphs containing py-doc markers
+      if (token.type === 'paragraph_open') {
+        const next = tokens[i + 1];
+        if (next && next.type === 'inline' && next.content) {
+          const rawLines = next.content.split('\n');
+          let hasMarkers = false;
+
+          for (const line of rawLines) {
+            const trimmed = line.trim();
+            if (
+              trimmed === '[[PAGEBREAK]]' ||
+              trimmed === '::: {.pagebreak}' ||
+              /^\[\[(LANDSCAPE|PORTRAIT)\]\]$/i.test(trimmed) ||
+              /^\[\[CAPTION:[A-Za-z0-9 _-]+\]\]/i.test(trimmed) ||
+              /^\[\[STYLE:[A-Za-z0-9 _-]+\]\]/i.test(trimmed) ||
+              /^\[\[(INCLUDE|INCLUDE-CODE|IF|NOT|ENDIF)(?::.*)?\]\]$/i.test(trimmed)
+            ) {
+              hasMarkers = true;
+              break;
+            }
+          }
+
+          if (hasMarkers) {
+            let renderedHtml = '';
+            for (const line of rawLines) {
+              const trimmed = line.trim();
+              if (!trimmed) continue;
+
+              // Page Break
+              if (trimmed === '[[PAGEBREAK]]' || trimmed === '::: {.pagebreak}') {
+                renderedHtml += '<div class="pydoc-pagebreak"><span class="pydoc-pagebreak-line"></span><span class="pydoc-badge">PAGE BREAK</span><span class="pydoc-pagebreak-line"></span></div>\n';
+                continue;
+              }
+
+              // Orientation
+              const orientMatch = trimmed.match(/^\[\[(LANDSCAPE|PORTRAIT)\]\]$/i);
+              if (orientMatch) {
+                const orient = orientMatch[1].toUpperCase();
+                renderedHtml += `<div class="pydoc-orientation"><span class="pydoc-pagebreak-line"></span><span class="pydoc-badge">SECTION BREAK (${orient})</span><span class="pydoc-pagebreak-line"></span></div>\n`;
+                continue;
+              }
+
+              // Directives
+              const directiveMatch = trimmed.match(/^\[\[(INCLUDE|INCLUDE-CODE|IF|NOT|ENDIF)(?::\s*([^\]]+))?\]\]$/i);
+              if (directiveMatch) {
+                const dType = directiveMatch[1].toUpperCase();
+                const dArg = (directiveMatch[2] || '').trim();
+                renderedHtml += `<div class="pydoc-directive"><span class="pydoc-directive-badge">${escapeHtml(dType)}</span> <code class="pydoc-directive-arg">${escapeHtml(dArg)}</code></div>\n`;
+                continue;
+              }
+
+              // Numbered Caption
+              const capMatch = trimmed.match(/^\[\[CAPTION:([A-Za-z0-9 _-]+)\]\](?:\s*(.*))?$/);
+              if (capMatch) {
+                const label = capMatch[1].trim();
+                const text = (capMatch[2] || '').trim();
+                counters[label] = (counters[label] || 0) + 1;
+                const num = counters[label];
+                renderedHtml += `<div class="pydoc-caption"><span class="pydoc-caption-num">${escapeHtml(label)} ${num}:</span> <span class="pydoc-caption-text">${md.renderInline(text)}</span></div>\n`;
+                continue;
+              }
+
+              // Style
+              const styleMatch = trimmed.match(/^\[\[STYLE:([A-Za-z0-9 _-]+)\]\](?:\s*(.*))?$/);
+              if (styleMatch) {
+                const styleName = styleMatch[1].trim();
+                const text = (styleMatch[2] || '').trim();
+                renderedHtml += `<div class="pydoc-styled-block" data-word-style="${escapeHtml(styleName)}"><span class="pydoc-style-pill" title="Word Paragraph Style">${escapeHtml(styleName)}</span>${md.renderInline(text)}</div>\n`;
+                continue;
+              }
+
+              renderedHtml += `<p>${md.renderInline(line)}</p>\n`;
+            }
+
+            tokens[i] = new state.Token('html_block', '', 0);
+            tokens[i].content = renderedHtml;
+            tokens.splice(i + 1, 2);
+            continue;
+          }
+        }
+      }
+
+      // F. Process Blockquotes for Callouts / Admonitions
+      if (token.type === 'blockquote_open') {
+        let firstInlineIdx = -1;
+        for (let j = i + 1; j < tokens.length; j++) {
+          if (tokens[j].type === 'blockquote_close') break;
+          if (tokens[j].type === 'inline') {
+            firstInlineIdx = j;
+            break;
+          }
+        }
+
+        if (firstInlineIdx !== -1) {
+          const inlineToken = tokens[firstInlineIdx];
+          const rawContent = inlineToken.content.trim();
+          const ghMatch = rawContent.match(/^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]/i);
+          const boldMatch = rawContent.match(/^\*\*(Note|Tip|Important|Warning|Caution)\s*:\*\*/i)
+            || rawContent.match(/^\*\*(Note|Tip|Important|Warning|Caution)\*\*\s*:/i);
+
+          const kindRaw = ghMatch ? ghMatch[1] : (boldMatch ? boldMatch[1] : null);
+
+          if (kindRaw) {
+            const kindKey = kindRaw.toUpperCase();
+            const info = KINDS[kindKey] || { title: kindKey, icon: 'ℹ️', class: 'note' };
+
+            token.attrs = [['class', `pydoc-callout pydoc-callout-${info.class}`]];
+
+            let bodyText = rawContent;
+            if (ghMatch) {
+              bodyText = bodyText.replace(/^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*/i, '');
+            } else if (boldMatch) {
+              bodyText = bodyText.replace(/^\*\*(Note|Tip|Important|Warning|Caution)\s*:\*\*\s*/i, '')
+                                 .replace(/^\*\*(Note|Tip|Important|Warning|Caution)\*\*\s*:\s*/i, '');
+            }
+
+            const headerBlock = new state.Token('html_block', '', 0);
+            headerBlock.content = `<div class="pydoc-callout-header"><span class="pydoc-callout-icon">${info.icon}</span><span class="pydoc-callout-title">${info.title}</span></div>\n`;
+
+            const pOpenIdx = firstInlineIdx - 1;
+            tokens.splice(pOpenIdx, 0, headerBlock);
+            i++;
+
+            inlineToken.content = bodyText;
+            if (!bodyText) {
+              tokens.splice(pOpenIdx + 1, 3);
+            } else {
+              inlineToken.children = [new state.Token('html_inline', '', 0)];
+              inlineToken.children[0].content = md.renderInline(bodyText);
+            }
+          }
+        }
+      }
+    }
+
+    // G. If in Slide Deck mode, group tokens into presentation slide cards
+    if (docMode === 'slide') {
+      groupTokensIntoSlides(state, docTitle, Number.parseInt(asText(frontMeta && frontMeta.split_level), 10) || 2);
+    }
+
+    // H. If in Poster mode, append poster footer if defined
+    if (docMode === 'poster' && frontMeta && frontMeta.footer) {
+      const footer = frontMeta.footer;
+      let footerHtml = '<footer class="pydoc-poster-footer">\n';
+      footerHtml += `  <div class="pydoc-poster-footer-left">${escapeHtml(footer.left || '')}</div>\n`;
+      footerHtml += `  <div class="pydoc-poster-footer-right">${escapeHtml(footer.right || '')}</div>\n`;
+      if (footer.qr || footer['qr-label']) {
+        footerHtml += `  <div class="pydoc-poster-qr-badge">📱 ${escapeHtml(footer['qr-label'] || 'QR Code')}</div>\n`;
+      }
+      footerHtml += '</footer>\n';
+
+      const footToken = new state.Token('html_block', '', 0);
+      footToken.content = footerHtml;
+      tokens.push(footToken);
+    }
+  });
+}
+
+// A heading at splitLevel or above starts a slide, as pandoc's --slide-level does; one above it is a section slide
+function groupTokensIntoSlides(state, docTitle, splitLevel) {
+  const tokens = state.tokens;
+  const newTokens = [];
+  let currentSlideTokens = [];
+  let slideNum = 0;
+  let isCurrentSection = false;
+
+  function flushSlide(isSection) {
+    if (currentSlideTokens.length === 0) return;
+    slideNum++;
+    const cardOpen = new state.Token('html_block', '', 0);
+    const slideClass = isSection ? 'pydoc-slide pydoc-slide-section' : 'pydoc-slide pydoc-slide-content';
+    cardOpen.content = `<section class="${slideClass}"><div class="pydoc-slide-canvas">\n`;
+    newTokens.push(cardOpen);
+
+    for (const t of currentSlideTokens) {
+      newTokens.push(t);
+    }
+
+    const cardClose = new state.Token('html_block', '', 0);
+    cardClose.content = `</div><footer class="pydoc-slide-footer"><span class="pydoc-slide-deck-title">${escapeHtml(docTitle)}</span><span class="pydoc-slide-num">Slide ${slideNum}</span></footer></section>\n`;
+    newTokens.push(cardClose);
+    currentSlideTokens = [];
+  }
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+
+    if (token.type === 'pydoc_front_matter') {
+      newTokens.push(token);
+      continue;
+    }
+
+    if (token.type === 'heading_open') {
+      const level = parseInt(token.tag.slice(1), 10);
+      if (level <= splitLevel) {
+        flushSlide(isCurrentSection);
+        isCurrentSection = (level < splitLevel);
+      }
+    }
+
+    if (token.type === 'html_block' && token.content && token.content.includes('pydoc-pagebreak')) {
+      flushSlide(isCurrentSection);
+      isCurrentSection = false;
+      continue;
+    }
+
+    currentSlideTokens.push(token);
+  }
+
+  flushSlide(isCurrentSection);
+  state.tokens = newTokens;
+}
+
+module.exports = { pyDocPlugin };
diff --git a/editors/vscode/src/text.js b/editors/vscode/src/text.js
new file mode 100644
index 0000000..4215a9e
--- /dev/null
+++ b/editors/vscode/src/text.js
@@ -0,0 +1,25 @@
+'use strict';
+
+// Front matter values may be lists (author: [- Jane, - Joe]) or mappings, so anything is turned into text first
+function asText(val) {
+  if (val === null || val === undefined) return '';
+  if (Array.isArray(val)) return val.map(asText).join(', ');
+  if (typeof val === 'object') return Object.values(val).map(asText).join(', ');
+  return String(val);
+}
+
+// A colour name written in the Markdown, made safe to use as part of a class name
+function cssName(val) {
+  return asText(val).toLowerCase().replace(/[^a-z0-9_-]/g, '');
+}
+
+function escapeHtml(val) {
+  const str = asText(val);
+  if (!str) return '';
+  return str.replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;');
+}
+
+module.exports = { asText, cssName, escapeHtml };
diff --git a/editors/vscode/src/watch.js b/editors/vscode/src/watch.js
new file mode 100644
index 0000000..6af92c8
--- /dev/null
+++ b/editors/vscode/src/watch.js
@@ -0,0 +1,121 @@
+'use strict';
+
+// The live preview: runs `py-doc <command> FILE --watch --no-open` as a child process, shows what it prints
+// in an output channel, reads the address it serves from its "serving http://..." line, and opens that in
+// VS Code's Simple Browser. py-doc picks a free port unless the pydoc.watch.port setting names one, so two
+// windows never fight over a port. One preview runs at a time: starting another stops it first.
+
+const path = require('path');
+const { spawn, execFile } = require('child_process');
+
+const START_TIMEOUT = 180000;  // ms: a first build may have to start the tool container
+const STOP_TIMEOUT = 5000;
+const SERVING = /^serving (http:\/\/127\.0\.0\.1:\d+\/)/m;
+
+class LiveWatch {
+  /**
+   * @param vscode the vscode module
+   * @param options.command the program and its first arguments, in place of the pydoc.executable setting (tests)
+   */
+  constructor(vscode, options = {}) {
+    this.vscode = vscode;
+    this.command = options.command || null;
+    this.child = null;
+    this.output = vscode.window.createOutputChannel('py-doc live preview');
+  }
+
+  get running() {
+    return this.child !== null;
+  }
+
+  /** Start the preview of filePath with py-doc's `command` (docx, slides or poster). Resolves to its address, or null. */
+  async start(command, filePath, cwd) {
+    await this.stop();
+    const config = this.vscode.workspace.getConfiguration('pydoc');
+    const [program, ...first] = this.command || [config.get('executable', 'py-doc')];
+    const port = config.get('watch.port', 0);
+    const args = [...first, command, filePath, '--watch', '--no-open', ...(port ? ['--port', String(port)] : [])];
+
+    this.output.clear();
+    this.output.appendLine(`> ${program} ${args.join(' ')}`);
+    const child = spawn(program, args, {
+      cwd: cwd || path.dirname(filePath),
+      env: { ...process.env, PYTHONUNBUFFERED: '1', PYTHONIOENCODING: 'utf-8' },
+      windowsHide: true,
+    });
+    this.child = child;
+
+    const started = new Promise((resolve) => {
+      let seen = '';
+      const timer = setTimeout(() => resolve(null), START_TIMEOUT);
+      const done = (address) => {
+        clearTimeout(timer);
+        resolve(address);
+      };
+      child.stdout.on('data', (chunk) => {
+        const text = chunk.toString();
+        this.output.append(text);
+        if (seen !== null) {
+          seen += text;
+          const m = seen.match(SERVING);
+          if (m) {
+            seen = null;  // found: the rest of the output is only shown
+            done(m[1]);
+          }
+        }
+      });
+      child.stderr.on('data', (chunk) => this.output.append(chunk.toString()));
+      child.on('error', (err) => {
+        this.output.appendLine(`Cannot start ${program}: ${err.message}. Set pydoc.executable to the py-doc program.`);
+        done(null);
+      });
+      child.on('exit', (code, signal) => {
+        this.output.appendLine(`py-doc stopped (${signal || `exit status ${code}`})`);
+        if (this.child === child) this.child = null;
+        done(null);
+      });
+    });
+
+    const address = await this.vscode.window.withProgress(
+      { location: this.vscode.ProgressLocation.Window, title: `py-doc: building the ${command} preview` },
+      () => started
+    );
+    if (child.stoppedByUs) return null;  // stopped, or replaced by another preview, while it started
+    if (address) {
+      await this.vscode.commands.executeCommand('simpleBrowser.show', address);
+      return address;
+    }
+    await this.stop();
+    this.output.show(true);
+    this.vscode.window.showErrorMessage(`The py-doc ${command} preview did not start. See the "py-doc live preview" output.`);
+    return null;
+  }
+
+  /** Stop the running preview, and its whole process tree. Resolves to whether one was running. */
+  stop() {
+    const child = this.child;
+    this.child = null;
+    if (child) child.stoppedByUs = true;
+    if (!child || child.exitCode !== null || child.signalCode !== null) return Promise.resolve(false);
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => resolve(true), STOP_TIMEOUT);
+      child.once('exit', () => {
+        clearTimeout(timer);
+        resolve(true);
+      });
+      if (process.platform === 'win32') {
+        // py-doc.exe is a launcher that starts Python: /T ends the tree, not only the launcher
+        execFile('taskkill', ['/pid', String(child.pid), '/T', '/F'], () => {});
+      } else {
+        child.kill('SIGTERM');
+      }
+    });
+  }
+
+  dispose() {
+    this.stop();
+    this.output.dispose();
+  }
+}
+
+module.exports = { LiveWatch, SERVING };
diff --git a/editors/vscode/test/cases.test.js b/editors/vscode/test/cases.test.js
new file mode 100644
index 0000000..fb7e248
--- /dev/null
+++ b/editors/vscode/test/cases.test.js
@@ -0,0 +1,39 @@
+'use strict';
+
+// The shared preview cases of tests/fixtures/preview/cases.json, through the instant preview.
+// tests/test_preview_cases.py runs the same cases through the HTML twin that --watch builds, so the
+// instant preview cannot drift from the build without one of the two failing.
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const MarkdownIt = require('markdown-it');
+const { pyDocPlugin, detectDocumentFormat } = require('../extension');
+
+const CASES = path.join(__dirname, '..', '..', '..', 'tests', 'fixtures', 'preview', 'cases.json');
+const { cases } = JSON.parse(fs.readFileSync(CASES, 'utf8'));
+
+const count = (html, needle) => html.split(needle).length - 1;
+
+for (const c of cases) {
+  test(c.name, () => {
+    // The build takes the split level from the command line; the instant preview from the front matter
+    const markdown = c.split_level ? `---\nsplit_level: ${c.split_level}\n---\n\n${c.markdown}` : c.markdown;
+    assert.strictEqual(detectDocumentFormat(markdown), c.command, 'detected command');
+
+    const html = new MarkdownIt({ html: true }).use(pyDocPlugin).render(markdown);
+    const expect = c.expect;
+    for (const kind of expect.callouts || []) {
+      assert.ok(html.includes(`pydoc-callout-${kind}`), `callout ${kind}`);
+    }
+    assert.strictEqual(count(html, 'class="pydoc-pagebreak"'), expect.pagebreaks || 0, 'page breaks');
+    assert.strictEqual(count(html, '<section class="pydoc-slide '), expect.slides || 0, 'slides');
+    assert.strictEqual(count(html, 'pydoc-slide-section'), expect.parts || 0, 'part slides');
+    assert.strictEqual(count(html, 'pydoc-notes"'), expect.notes || 0, 'speaker notes');
+    assert.strictEqual(count(html, 'pydoc-columns"'), expect.columns || 0, 'columns');
+    for (const text of expect.text || []) {
+      assert.ok(html.includes(text), text);
+    }
+  });
+}
diff --git a/editors/vscode/test/watch.test.js b/editors/vscode/test/watch.test.js
new file mode 100644
index 0000000..ac15c84
--- /dev/null
+++ b/editors/vscode/test/watch.test.js
@@ -0,0 +1,98 @@
+'use strict';
+
+// The live preview against a fake py-doc (a Node script) and a fake vscode module.
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { LiveWatch, SERVING } = require('../src/watch');
+
+function fakeVscode(settings = {}) {
+  const calls = { browser: [], errors: [], output: [] };
+  const vscode = {
+    calls,
+    window: {
+      createOutputChannel: () => ({
+        append: (t) => calls.output.push(t),
+        appendLine: (t) => calls.output.push(t + '\n'),
+        clear: () => {},
+        show: () => {},
+        dispose: () => {},
+      }),
+      withProgress: (options, task) => task(),
+      showErrorMessage: (m) => calls.errors.push(m),
+    },
+    workspace: { getConfiguration: () => ({ get: (key, fallback) => (key in settings ? settings[key] : fallback) }) },
+    commands: { executeCommand: async (id, arg) => { if (id === 'simpleBrowser.show') calls.browser.push(arg); } },
+    ProgressLocation: { Window: 10 },
+  };
+  return vscode;
+}
+
+// A fake py-doc: prints what --watch prints, then keeps running (or fails, with FAIL set)
+const script = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'pydoc-watch-')), 'fake-py-doc.js');
+fs.writeFileSync(script, `
+const args = process.argv.slice(2);
+if (process.env.FAKE_FAIL) { console.error('Error: pandoc failed'); process.exit(1); }
+const port = args.includes('--port') ? args[args.indexOf('--port') + 1] : '54321';
+console.log('ARGS ' + JSON.stringify(args));
+console.log('wrote ' + args[1]);
+console.log('serving http://127.0.0.1:' + port + '/');
+setInterval(() => {}, 1000);
+`);
+
+test('the serving line gives the address', () => {
+  assert.strictEqual('built in 1.2 s\nserving http://127.0.0.1:61234/\n'.match(SERVING)[1], 'http://127.0.0.1:61234/');
+});
+
+test('a preview opens the address py-doc serves, and stops', async (t) => {
+  const vscode = fakeVscode();
+  const live = new LiveWatch(vscode, { command: [process.execPath, script] });
+  t.after(() => live.stop());
+  const address = await live.start('docx', path.join(os.tmpdir(), 'guide.md'));
+  assert.strictEqual(address, 'http://127.0.0.1:54321/');
+  assert.deepStrictEqual(vscode.calls.browser, ['http://127.0.0.1:54321/']);
+  assert.ok(live.running);
+  assert.strictEqual(await live.stop(), true);
+  assert.ok(!live.running);
+  assert.strictEqual(await live.stop(), false);
+});
+
+test('the port setting is passed on, and a new preview replaces the running one', async (t) => {
+  const vscode = fakeVscode({ 'watch.port': 8899 });
+  const live = new LiveWatch(vscode, { command: [process.execPath, script] });
+  t.after(() => live.stop());
+  await live.start('docx', path.join(os.tmpdir(), 'a.md'));
+  const first = live.child;
+  await live.start('poster', path.join(os.tmpdir(), 'b.md'));
+  assert.ok(first.exitCode !== null || first.signalCode !== null, 'the first preview was stopped');
+  assert.deepStrictEqual(vscode.calls.browser, ['http://127.0.0.1:8899/', 'http://127.0.0.1:8899/']);
+  const argsLine = vscode.calls.output.join('').split('\n').filter((l) => l.startsWith('ARGS ')).pop();
+  assert.deepStrictEqual(JSON.parse(argsLine.slice(5)), ['poster', path.join(os.tmpdir(), 'b.md'), '--watch', '--no-open', '--port', '8899']);
+  await live.stop();
+});
+
+test('a preview that fails says so, and opens nothing', async () => {
+  process.env.FAKE_FAIL = '1';
+  try {
+    const vscode = fakeVscode();
+    const live = new LiveWatch(vscode, { command: [process.execPath, script] });
+    assert.strictEqual(await live.start('slides', path.join(os.tmpdir(), 'deck.md')), null);
+    assert.deepStrictEqual(vscode.calls.browser, []);
+    assert.strictEqual(vscode.calls.errors.length, 1);
+    assert.ok(vscode.calls.output.join('').includes('pandoc failed'));
+    assert.ok(!live.running);
+  } finally {
+    delete process.env.FAKE_FAIL;
+  }
+});
+
+test('a program that cannot be started says so', async () => {
+  const vscode = fakeVscode({ executable: path.join(os.tmpdir(), 'no-such-py-doc') });
+  const live = new LiveWatch(vscode);
+  assert.strictEqual(await live.start('docx', path.join(os.tmpdir(), 'guide.md')), null);
+  assert.ok(vscode.calls.output.join('').includes('Cannot start'));
+  assert.strictEqual(vscode.calls.errors.length, 1);
+});
diff --git a/src/py_doc/_cli.py b/src/py_doc/_cli.py
index d2fa4d4..ef71f90 100644
--- a/src/py_doc/_cli.py
+++ b/src/py_doc/_cli.py
@@ -191,7 +191,7 @@ def build_all() -> tuple[dict[str, Path], set[Path]]:
             pages[name] = converter.convert_twin(src, base / PREVIEW_DIR / f"{name}.html").resolve()
         return pages, sources
 
-    from .poster_watch import watch
+    from .watch import watch
 
     return watch(
         build_all,
diff --git a/src/py_doc/convert.py b/src/py_doc/convert.py
index 8c6711b..8d03a7f 100644
--- a/src/py_doc/convert.py
+++ b/src/py_doc/convert.py
@@ -64,7 +64,8 @@ def convert_file(self, md_path: Path, output_path: Path) -> Path:
 
     def convert_twin(self, md_path: Path, output_path: Path) -> Path:
         """Write an HTML preview twin of the document or deck: the same Markdown, as a web page, for ``--watch``."""
-        return self._render(md_path, output_path, "html", None, {**self.options, "preview": True})
+        preview = "slides" if self.fmt == "pptx" else "document"
+        return self._render(md_path, output_path, "html", None, {**self.options, "preview": preview})
 
     def _render(self, md_path: Path, output_path: Path, fmt: str, template: Path | None, options: dict) -> Path:
         md_path = Path(md_path).resolve()
diff --git a/src/py_doc/pandoc/engine.py b/src/py_doc/pandoc/engine.py
index e8441e7..8dc6c7f 100644
--- a/src/py_doc/pandoc/engine.py
+++ b/src/py_doc/pandoc/engine.py
@@ -160,8 +160,11 @@ def _command(job: PandocJob, runtime: Runtime, work: Path, reference: Path | Non
     elif fmt == "html":
         argv += ["--to=html5", "--standalone", "--embed-resources", "--mathml"]
         argv += ["--css", job.template if job.template is not None else _required(RESOURCES / "html.css", "stylesheet")]
-        if options.get("preview", False):  # the HTML twin of a document or deck, for --watch
+        if options.get("preview"):  # the HTML twin of a document or deck, for --watch
             argv += ["--css", _required(RESOURCES / "preview.css", "stylesheet")]
+        if options.get("preview") == "slides":  # after pagebreak.lua, which the twin's slide breaks come from
+            argv += ["--lua-filter", _required(RESOURCES / "slides-preview.lua", "Lua filter")]
+            argv.append(f"--metadata=preview-slide-level:{options.get('split_level', 2)}")
         if options.get("toc", False):
             argv.append("--toc")
     else:  # pdf
diff --git a/src/py_doc/pandoc/resources/preview.css b/src/py_doc/pandoc/resources/preview.css
index 3c04df4..055f204 100644
--- a/src/py_doc/pandoc/resources/preview.css
+++ b/src/py_doc/pandoc/resources/preview.css
@@ -1,5 +1,5 @@
 /* Added after html.css for the HTML preview twin of `py-doc docx|slides --watch` only, so the twin shows
-   what a Word document or deck has that a web page does not: page breaks, speaker notes and columns. */
+   what a Word document or deck has that a web page does not: page breaks, speaker notes, columns and slides. */
 figure { margin: 1.5em 0; text-align: center; }
 figcaption { font-size: 0.9em; color: #4b5563; margin-top: 0.5em; font-style: italic; }
 caption { font-size: 0.9em; font-weight: 600; color: #003c64; padding-bottom: 0.5em; text-align: left; }
@@ -9,4 +9,10 @@ div.columns { display: flex; gap: 1.5em; margin: 1em 0; }
 div.column { flex: 1; min-width: 0; }
 div.pagebreak { border-top: 2px dashed #cbd5e1; margin: 2em 0; position: relative; }
 div.pagebreak::after { content: "Page break"; position: absolute; right: 0; top: -0.8em; background: #fff; padding: 0 0.5em; font-size: 0.75em; color: #94a3b8; text-transform: uppercase; letter-spacing: 0.05em; }
-@media print { div.pagebreak { border: none; margin: 0; } div.pagebreak::after { content: none; } }
+body:has(.slide) { max-width: 64em; counter-reset: slide; background: #e5e9ee; }
+.slide { counter-increment: slide; position: relative; aspect-ratio: 16 / 9; box-sizing: border-box; background: #fff; border-radius: 6px; box-shadow: 0 2px 8px rgba(15, 23, 42, 0.18); padding: 1.5em 2.5em 2.5em; margin: 0 0 2em; }
+.slide::after { content: "Slide " counter(slide); position: absolute; right: 1.2em; bottom: 0.8em; font-size: 0.75em; color: #94a3b8; }
+.slide.part { display: flex; flex-direction: column; justify-content: center; background: #003c64; }
+.slide.part h1, .slide.part h2 { color: #fff; font-size: 2.2em; }
+.slide div.notes { margin-top: 1.5em; }
+@media print { div.pagebreak { border: none; margin: 0; } div.pagebreak::after { content: none; } .slide { break-after: page; box-shadow: none; } }
diff --git a/src/py_doc/pandoc/resources/slides-preview.lua b/src/py_doc/pandoc/resources/slides-preview.lua
new file mode 100644
index 0000000..d8d85dc
--- /dev/null
+++ b/src/py_doc/pandoc/resources/slides-preview.lua
@@ -0,0 +1,39 @@
+-- slides-preview.lua
+-- The HTML twin of a deck (py-doc slides --watch): each slide's content goes in a <div class="slide">,
+-- starting at each heading up to the slide level and at each page break, as pandoc's PowerPoint writer
+-- splits them. A heading above the slide level makes a part divider ("part": pandoc keeps no class named "section"). Runs after pagebreak.lua.
+
+local function is_pagebreak(block)
+  return block.t == "RawBlock" and block.format == "html" and block.text:find('class="pagebreak"', 1, true) ~= nil
+end
+
+function Pandoc(doc)
+  local level = tonumber(pandoc.utils.stringify(doc.meta["preview-slide-level"] or "2")) or 2
+  local out = pandoc.Blocks({})
+  local current, kind = nil, nil
+
+  local function flush()
+    if current ~= nil and #current > 0 then
+      out:insert(pandoc.Div(current, pandoc.Attr("", { "slide", kind })))
+    end
+    current, kind = nil, nil
+  end
+
+  for _, block in ipairs(doc.blocks) do
+    if block.t == "Header" and block.level <= level then
+      flush()
+      current, kind = pandoc.Blocks({ block }), (block.level < level) and "part" or "content"
+    elseif is_pagebreak(block) then
+      flush()
+      current, kind = pandoc.Blocks({}), "content"
+    else
+      if current == nil then
+        current, kind = pandoc.Blocks({}), "content"
+      end
+      current:insert(block)
+    end
+  end
+  flush()
+  doc.blocks = out
+  return doc
+end
diff --git a/src/py_doc/poster_cli.py b/src/py_doc/poster_cli.py
index 44bf6cb..6cc8895 100644
--- a/src/py_doc/poster_cli.py
+++ b/src/py_doc/poster_cli.py
@@ -100,7 +100,7 @@ def build_all() -> tuple[dict[str, Path], set[Path]]:
 
     errors = (ConfigError, ConversionError, SettingsError)
     if args.watch:
-        from py_doc.poster_watch import watch
+        from py_doc.watch import watch
 
         return watch(build_all, errors, port=args.port, open_browser=not args.no_open)
     try:
diff --git a/src/py_doc/poster_watch.py b/src/py_doc/watch.py
similarity index 95%
rename from src/py_doc/poster_watch.py
rename to src/py_doc/watch.py
index 2ce143f..b7f459d 100644
--- a/src/py_doc/poster_watch.py
+++ b/src/py_doc/watch.py
@@ -1,4 +1,4 @@
-"""``py-doc poster --watch``: rebuild the posters on every save, and reload them in the browser.
+"""``--watch`` of ``py-doc poster``, ``docx`` and ``slides``: build again on every save, and reload in the browser.
 
 The pages are served on a local address, each with a small script that asks the server every 0.7 s
 whether a newer build is there, and reloads when it is. A build that fails keeps the last good page and
@@ -24,7 +24,7 @@
 
 INTERVAL = 0.5  # seconds between two looks at the files
 SKIPPED = {"node_modules", "__pycache__"}  # folders never watched, as are hidden ones
-# The kinds of file a poster is made from: its Markdown, includes, pictures, data, diagram sources and fonts.
+# The kinds of file a page is made from: its Markdown, includes, pictures, data, diagram sources and fonts.
 # Any other file in the folder, such as a log, is not watched, or writing it would build again without end.
 SOURCES = {".md", ".markdown", ".yml", ".yaml", ".json", ".csv", ".txt", ".py", ".svg", ".png", ".jpg", ".jpeg",
            ".gif", ".webp", ".puml", ".iuml", ".plantuml", ".dot", ".gv", ".mmd", ".dsl", ".woff2", ".woff", ".ttf", ".otf"}  # fmt: skip
@@ -40,7 +40,7 @@
 }).catch(function(){}).then(function(){setTimeout(poll,700);});}
 poll();})();</script>"""
 
-# What a build gives the watcher: the page of each poster, by name, and the files it was made from
+# What a build gives the watcher: the page of each poster or HTML twin, by name, and the files it was made from
 Build = Callable[[], tuple[dict[str, Path], set[Path]]]
 
 
diff --git a/tests/fixtures/preview/cases.json b/tests/fixtures/preview/cases.json
new file mode 100644
index 0000000..93e2dc3
--- /dev/null
+++ b/tests/fixtures/preview/cases.json
@@ -0,0 +1,30 @@
+{
+  "about": "Shared cases for the two previews of py-doc Markdown: the VS Code instant preview (editors/vscode/test/test.js) and the HTML twin that --watch builds with pandoc (tests/test_preview_cases.py). Both must find what each case expects, so the instant preview cannot drift from the build. 'command' is also what the VS Code extension must detect for the case.",
+  "cases": [
+    {
+      "name": "callouts in both spellings",
+      "command": "docx",
+      "markdown": "# Installing\n\n> [!WARNING]\n> Disconnect the battery first.\n\n> **Tip:** Keep the screws.\n\n> [!NOTE]\n> Firmware 2 or later.\n",
+      "expect": { "callouts": ["warning", "tip", "note"], "text": ["Disconnect the battery first.", "Keep the screws.", "Firmware 2 or later."] }
+    },
+    {
+      "name": "page breaks in a document",
+      "command": "docx",
+      "markdown": "---\ntitle: Breaks\nauthor:\n  - Jane\n  - Joe\n---\n\n# One\n\nFirst page.\n\n[[PAGEBREAK]]\n\nSecond page.\n\n::: {.pagebreak}\n:::\n\nThird page.\n",
+      "expect": { "pagebreaks": 2, "text": ["First page.", "Second page.", "Third page."] }
+    },
+    {
+      "name": "a deck at the default split level",
+      "command": "slides",
+      "markdown": "# Deck\n\n## First\n\n- one\n\n<!-- notes: Say hello -->\n\n## Second\n\n:::: columns\n::: column\nLeft side\n:::\n::: column\nRight side\n:::\n::::\n\n::: notes\nPause here\n:::\n",
+      "expect": { "slides": 3, "parts": 1, "notes": 2, "columns": 1, "text": ["Say hello", "Pause here", "Left side", "Right side"] }
+    },
+    {
+      "name": "a deck split at level 1",
+      "command": "slides",
+      "split_level": 1,
+      "markdown": "# One\n\n## Detail\n\ntext\n\n# Two\n\n::: notes\nLast words\n:::\n",
+      "expect": { "slides": 2, "parts": 0, "notes": 1, "text": ["Detail", "Last words"] }
+    }
+  ]
+}
diff --git a/tests/test_cli.py b/tests/test_cli.py
index f915f92..917a585 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -300,7 +300,7 @@ def test_compat_module_entry_point_runs(self, tmp_path):
 
     def test_docx_watch_mode(self, tmp_path, monkeypatch):
         from py_doc.cli import run_docx
-        from py_doc import poster_watch
+        from py_doc import watch as watcher
 
         src = tmp_path / "spec.md"
         src.write_text("# Spec\n\nText\n\n::: {.pagebreak}\n:::\n\nMore\n", encoding="utf-8")
@@ -313,7 +313,7 @@ def fake_watch(build, errors, port=0, open_browser=True, stop=None, interval=0.5
             called.append((pages, sources, port, open_browser, title))
             return 0
 
-        monkeypatch.setattr(poster_watch, "watch", fake_watch)
+        monkeypatch.setattr(watcher, "watch", fake_watch)
         code = run_docx([str(src), "--watch", "--port", "9876", "--no-open"])
         assert code == 0
         assert len(called) == 1
@@ -328,19 +328,20 @@ def fake_watch(build, errors, port=0, open_browser=True, stop=None, interval=0.5
         assert 'class="pagebreak"' in twin and "Page break" in twin  # preview.css is in the twin
 
     def test_docx_watch_keeps_files_of_the_same_name_apart(self, tmp_path, monkeypatch):
-        from py_doc import poster_watch
+        from py_doc import watch as watcher
         from py_doc.cli import run_docx
 
         for folder in ("a", "b"):
             (tmp_path / folder).mkdir()
             (tmp_path / folder / "readme.md").write_text(f"# {folder}\n", encoding="utf-8")
         called = []
-        monkeypatch.setattr(poster_watch, "watch", lambda build, errors, **kw: called.append(build()[0]) or 0)
+        monkeypatch.setattr(watcher, "watch", lambda build, errors, **kw: called.append(build()[0]) or 0)
         assert run_docx([str(tmp_path), "--watch", "--no-open"]) == 0
         assert sorted(called[0]) == ["a/readme", "b/readme"]
 
     def test_docx_watch_builds_the_twin_of_a_document_open_in_word(self, tmp_path, monkeypatch, capsys):
-        from py_doc import convert, poster_watch
+        from py_doc import convert
+        from py_doc import watch as watcher
         from py_doc.cli import run_docx
         from py_doc.errors import OutputLocked
 
@@ -352,7 +353,7 @@ def locked(self, md_path, output_path):
 
         monkeypatch.setattr(convert.DocxConverter, "convert_file", locked)
         called = []
-        monkeypatch.setattr(poster_watch, "watch", lambda build, errors, **kw: called.append(build()[0]) or 0)
+        monkeypatch.setattr(watcher, "watch", lambda build, errors, **kw: called.append(build()[0]) or 0)
         assert run_docx([str(src), "--watch", "--no-open"]) == 0
         assert called[0]["spec"].is_file()
         assert "is open in Word" in capsys.readouterr().err
diff --git a/tests/test_logging_policy.py b/tests/test_logging_policy.py
index 96b82cb..e863fe7 100644
--- a/tests/test_logging_policy.py
+++ b/tests/test_logging_policy.py
@@ -17,7 +17,7 @@
 # Modules that are command line front ends: they print results and errors for people and programs.
 FRONT_ENDS = {
     "app.py", "_cli.py", "cli.py", "slides_cli.py", "tools_cli.py", "template_cli.py", "import_cli.py", "__main__.py", "lint/cli.py", "c4/cli.py", "site/cli.py", "init.py", "new.py",
-    "analysis/cli.py", "generators/cli.py", "poster_cli.py", "poster_watch.py",
+    "analysis/cli.py", "generators/cli.py", "poster_cli.py", "watch.py",
 }  # fmt: skip
 
 
diff --git a/tests/test_poster.py b/tests/test_poster.py
index ceff16b..71a703e 100644
--- a/tests/test_poster.py
+++ b/tests/test_poster.py
@@ -1396,7 +1396,7 @@ def test_watch_serves_the_page_and_builds_again_on_a_save(tmp_path, monkeypatch,
     import time
     import urllib.request
 
-    from py_doc import poster_watch
+    from py_doc import watch as watcher
 
     source = write(tmp_path, "## A\n\nFirst.\n")
     (tmp_path / "page.html").write_text("<html><body>First</body></html>", encoding="utf-8")
@@ -1410,10 +1410,10 @@ def build():
         return {"wall": tmp_path / "page.html"}, {source}
 
     servers = []
-    serve = poster_watch.serve
-    monkeypatch.setattr(poster_watch, "serve", lambda state, port: servers.append(serve(state, port)) or servers[-1])
+    serve = watcher.serve
+    monkeypatch.setattr(watcher, "serve", lambda state, port: servers.append(serve(state, port)) or servers[-1])
     stop = threading.Event()
-    thread = threading.Thread(target=poster_watch.watch, args=(build, (ConfigError,)),
+    thread = threading.Thread(target=watcher.watch, args=(build, (ConfigError,)),
                               kwargs={"open_browser": False, "stop": stop, "interval": 0.05})  # fmt: skip
     thread.start()
     try:
@@ -1457,7 +1457,7 @@ def save(text):  # as an editor does: all at once, never a half-written file
 
 
 def test_watch_stops_at_once_when_the_first_build_fails(capsys):
-    from py_doc.poster_watch import watch
+    from py_doc.watch import watch
 
     def build():
         raise ConfigError("no posters")
@@ -1477,7 +1477,7 @@ def test_watch_takes_no_pdf_and_output_needs_one_poster(tmp_path, monkeypatch, c
 
 
 def test_watch_watches_the_folder_of_the_markdown_and_the_files_its_settings_name(tmp_path):
-    from py_doc.poster_watch import watched_files
+    from py_doc.watch import watched_files
 
     (tmp_path / "shared").mkdir()
     (tmp_path / ".git").mkdir()
diff --git a/tests/test_preview_cases.py b/tests/test_preview_cases.py
new file mode 100644
index 0000000..b32c7f0
--- /dev/null
+++ b/tests/test_preview_cases.py
@@ -0,0 +1,41 @@
+"""The shared preview cases of tests/fixtures/preview/cases.json, through the HTML twin that --watch builds.
+
+editors/vscode/test/test.js runs the same cases through the VS Code instant preview, so the two previews
+agree on what a document shows: callouts, page breaks, slides, speaker notes, columns and text.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from py_doc.convert import DocxConverter, SlidesConverter
+
+CASES = json.loads((Path(__file__).parent / "fixtures" / "preview" / "cases.json").read_text(encoding="utf-8"))["cases"]
+
+pytestmark = pytest.mark.usefixtures("pandoc_runtime")
+
+
+@pytest.mark.parametrize("case", CASES, ids=[case["name"] for case in CASES])
+def test_the_html_twin_shows_what_the_instant_preview_shows(case, tmp_path):
+    md = tmp_path / "case.md"
+    md.write_text(case["markdown"], encoding="utf-8")
+    if case["command"] == "slides":
+        converter = SlidesConverter(split_level=case.get("split_level", 2))
+    else:
+        converter = DocxConverter()
+    html = converter.convert_twin(md, tmp_path / "case.html").read_text(encoding="utf-8")
+    expect = case["expect"]
+
+    for kind in expect.get("callouts", []):
+        assert f'class="admonition {kind}"' in html, kind
+    assert html.count('class="pagebreak"') == expect.get("pagebreaks", 0)
+    content, parts = html.count('class="slide content"'), html.count('class="slide part"')
+    assert content + parts == expect.get("slides", 0)
+    assert parts == expect.get("parts", 0)
+    assert html.count('class="notes"') == expect.get("notes", 0)
+    assert html.count('class="columns"') == expect.get("columns", 0)
+    for text in expect.get("text", []):
+        assert text in html, text
diff --git a/tests/test_slides_cli.py b/tests/test_slides_cli.py
index c77044a..60797e5 100644
--- a/tests/test_slides_cli.py
+++ b/tests/test_slides_cli.py
@@ -105,7 +105,7 @@ def test_module_entry_point_prints_help():
 
 def test_slides_watch_mode(tmp_path, monkeypatch):
     from py_doc.slides_cli import run_slides
-    from py_doc import poster_watch
+    from py_doc import watch as watcher
 
     src = tmp_path / "deck.md"
     src.write_text("# Deck\n\n## S1\n\n- a\n\n<!-- notes: Say this -->\n", encoding="utf-8")
@@ -117,7 +117,7 @@ def fake_watch(build, errors, port=0, open_browser=True, stop=None, interval=0.5
         called.append((pages, sources, port, open_browser, title))
         return 0
 
-    monkeypatch.setattr(poster_watch, "watch", fake_watch)
+    monkeypatch.setattr(watcher, "watch", fake_watch)
     code = run_slides([str(src), "--watch", "--port", "9875", "--no-open"])
     assert code == 0
     assert len(called) == 1
@@ -129,3 +129,19 @@ def fake_watch(build, errors, port=0, open_browser=True, stop=None, interval=0.5
     assert "PowerPoint Preview" in title
     twin = pages["deck"].read_text(encoding="utf-8")
     assert 'class="notes"' in twin and "Say this" in twin
+    assert twin.count('class="slide part"') == 1  # # Deck, above the slide level
+    assert twin.count('class="slide content"') == 1  # ## S1, with its notes on the same slide
+
+
+def test_slides_watch_twin_follows_the_split_level(tmp_path, monkeypatch):
+    from py_doc import watch as watcher
+    from py_doc.slides_cli import run_slides
+
+    src = tmp_path / "deck.md"
+    src.write_text("# One\n\n## Sub\n\ntext\n\n# Two\n\n::: {.pagebreak}\n:::\n\nAfter the break\n", encoding="utf-8")
+    called = []
+    monkeypatch.setattr(watcher, "watch", lambda build, errors, **kw: called.append(build()[0]) or 0)
+    assert run_slides([str(src), "--watch", "--no-open", "--split-level", "1"]) == 0
+    twin = called[0]["deck"].read_text(encoding="utf-8")
+    assert 'class="slide part"' not in twin
+    assert twin.count('class="slide content"') == 3  # # One (with ## Sub), # Two, and the page break

From 3397cd98c04a00b9f646108301d03a0e00c8255d Mon Sep 17 00:00:00 2001
From: Mark Bacon <mark@bacon.me.uk>
Date: Wed, 21 Oct 2026 15:26:59 +0100
Subject: [PATCH 4/6] Format the Python code with ruff format, and check it in
 CI

line-length = 120, the width the code was already written to, so the
reformat changes layout only. examples/ and tests/fixtures/ are left out:
example files are included into documents and posters, wrapped to fit.
CI's lint job now runs `ruff format --check .`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml          |   1 +
 pyproject.toml                    |   5 +
 src/py_doc/analysis/cli.py        |  75 +++++-
 src/py_doc/analysis/diff.py       |   8 +-
 src/py_doc/app.py                 | 104 ++++++--
 src/py_doc/build.py               |  18 +-
 src/py_doc/c4/check.py            |   7 +-
 src/py_doc/c4/cli.py              |  41 ++-
 src/py_doc/c4/generate.py         |  57 +++-
 src/py_doc/c4/model.py            |  11 +-
 src/py_doc/c4/render.py           |  20 +-
 src/py_doc/c4/source.py           |  20 +-
 src/py_doc/c4/stack.py            |  11 +-
 src/py_doc/c4/structurizr.py      |  12 +-
 src/py_doc/config.py              | 142 ++++++++--
 src/py_doc/convert.py             |   8 +-
 src/py_doc/diagrams/registry.py   |  41 ++-
 src/py_doc/diagrams/render.py     |  14 +-
 src/py_doc/diagrams/scan.py       |   7 +-
 src/py_doc/directives.py          |   9 +-
 src/py_doc/docx_import.py         |  38 ++-
 src/py_doc/generators/apidocs.py  |   4 +-
 src/py_doc/generators/builtin.py  |  77 ++++--
 src/py_doc/generators/registry.py |  20 +-
 src/py_doc/import_cli.py          |  10 +-
 src/py_doc/init.py                |  35 ++-
 src/py_doc/lint/cli.py            |  28 +-
 src/py_doc/lint/config.py         |  22 +-
 src/py_doc/lint/formats.py        |  22 +-
 src/py_doc/lint/linter.py         |  22 +-
 src/py_doc/lint/rules.py          |  22 +-
 src/py_doc/lint/structure.py      |  16 +-
 src/py_doc/lint/vale.py           |  29 ++-
 src/py_doc/lint/vale_config.py    |   4 +-
 src/py_doc/markdown/parser.py     |   4 +-
 src/py_doc/migrate.py             |  13 +-
 src/py_doc/naming.py              |   8 +-
 src/py_doc/new.py                 |  69 ++++-
 src/py_doc/pandoc/docx_finish.py  |  10 +-
 src/py_doc/pandoc/docx_post.py    | 162 +++++++-----
 src/py_doc/pandoc/engine.py       |  21 +-
 src/py_doc/pandoc/pptx_finish.py  |   8 +-
 src/py_doc/pandoc/reference.py    |  12 +-
 src/py_doc/pandoc/source.py       |   5 +-
 src/py_doc/poster.py              | 143 +++++++---
 src/py_doc/poster_barcode.py      |  43 ++-
 src/py_doc/poster_blocks.py       | 140 +++++++---
 src/py_doc/poster_cli.py          |  54 +++-
 src/py_doc/poster_fonts.py        |   8 +-
 src/py_doc/poster_qr.py           |  38 ++-
 src/py_doc/poster_settings.py     |  10 +-
 src/py_doc/poster_themes.py       |  10 +-
 src/py_doc/pptx_import.py         |  12 +-
 src/py_doc/report.py              |   6 +-
 src/py_doc/runtime/engine.py      |  29 ++-
 src/py_doc/runtime/image.py       |   6 +-
 src/py_doc/runtime/setup.py       |   4 +-
 src/py_doc/site/cli.py            |  42 ++-
 src/py_doc/site/engines.py        |  33 ++-
 src/py_doc/site/pages.py          |  28 +-
 src/py_doc/template_check.py      |  37 ++-
 src/py_doc/template_cli.py        |  34 ++-
 src/py_doc/tools_cli.py           |   8 +-
 src/py_doc/watch.py               |  21 +-
 tests/fake_vale.py                |  26 +-
 tests/test_analysis.py            |  13 +-
 tests/test_app.py                 | 420 +++++++++++++++---------------
 tests/test_build.py               |  21 +-
 tests/test_c4.py                  |  51 +++-
 tests/test_compat.py              |  11 +-
 tests/test_config.py              |  51 +++-
 tests/test_convert.py             |  15 +-
 tests/test_diagrams.py            | 105 ++++++--
 tests/test_directives.py          |   7 +-
 tests/test_docx_import.py         |  12 +-
 tests/test_examples.py            |  64 ++++-
 tests/test_front_matter.py        |   4 +-
 tests/test_generators.py          |  43 ++-
 tests/test_heading_numbers.py     |   4 +-
 tests/test_lint.py                |  13 +-
 tests/test_lint_cli.py            |   5 +-
 tests/test_lint_rules.py          |  13 +-
 tests/test_logging_policy.py      |  30 ++-
 tests/test_markdownlint.py        |  35 ++-
 tests/test_migrate.py             |   9 +-
 tests/test_new.py                 |  38 ++-
 tests/test_pandoc.py              |  16 +-
 tests/test_poster.py              | 273 ++++++++++++++-----
 tests/test_poster_barcode.py      |  29 ++-
 tests/test_poster_browser.py      |  17 +-
 tests/test_poster_qr.py           |  40 ++-
 tests/test_pptx_import.py         |   4 +-
 tests/test_pptx_pandoc.py         |   9 +-
 tests/test_report.py              |   4 +-
 tests/test_runtime.py             |   4 +-
 tests/test_setup.py               |  18 +-
 tests/test_site.py                | 183 ++++++++++---
 tests/test_slides_cli.py          |   6 +-
 tests/test_structure.py           |  70 ++++-
 tests/test_template_check.py      |  10 +-
 tests/test_vale.py                |  38 ++-
 tests/test_word_control.py        |  22 +-
 tests/test_word_layout.py         |  15 +-
 103 files changed, 2784 insertions(+), 942 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b9efb7e..8130bd3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -24,6 +24,7 @@ jobs:
           python-version: "3.14"
       - run: python -m pip install ruff
       - run: ruff check .
+      - run: ruff format --check .
 
   test:
     name: Test (${{ matrix.os }}, Python ${{ matrix.python-version }})
diff --git a/pyproject.toml b/pyproject.toml
index 910e8ee..ef77bc0 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -75,6 +75,11 @@ timeout = 120
 [tool.ruff]
 src = ["src", "tests"]
 target-version = "py310"
+line-length = 120  # the width the code is written to
+
+[tool.ruff.format]
+# Example files are content: they are included into documents and posters, wrapped to fit them
+exclude = ["examples/**", "tests/fixtures/**"]
 
 [tool.ruff.lint]
 select = ["E4", "E7", "E9", "F"]
diff --git a/src/py_doc/analysis/cli.py b/src/py_doc/analysis/cli.py
index 864a42a..d0bd20a 100644
--- a/src/py_doc/analysis/cli.py
+++ b/src/py_doc/analysis/cli.py
@@ -63,7 +63,12 @@ def run_stats(argv: list[str]) -> int:
         prog="py-doc stats", description="Count the words, headings, code blocks, tables, pictures and links of documents or files",
         epilog=STATS_EXAMPLES, formatter_class=argparse.RawDescriptionHelpFormatter,
     )  # fmt: skip
-    parser.add_argument("targets", nargs="*", metavar="TARGET", help="Documents of py-doc.yml, or Markdown files and folders (default: every document)")
+    parser.add_argument(
+        "targets",
+        nargs="*",
+        metavar="TARGET",
+        help="Documents of py-doc.yml, or Markdown files and folders (default: every document)",
+    )
     parser.add_argument("-c", "--config", help="Configuration file (default: the nearest py-doc.yml)")
     parser.add_argument("--lint", action="store_true", help="Also count the lint issues of each")
     parser.add_argument("--format", choices=("text", "json"), default="text", help="text, a table (default), or json")
@@ -89,12 +94,18 @@ def run_stats(argv: list[str]) -> int:
             print(f"Error: {target} is not a document of py-doc.yml, a file or a folder", file=sys.stderr)
             return 2
     if not groups:
-        print("Error: nothing to count. Name files or folders, or run it beside a py-doc.yml with documents", file=sys.stderr)
+        print(
+            "Error: nothing to count. Name files or folders, or run it beside a py-doc.yml with documents",
+            file=sys.stderr,
+        )
         return 2
 
     issues: dict[Path, int] = {}
     if args.lint:
-        linter = DocLinter(config=project.lint if project else None, runtime=lambda: connect(project.runtime if project else RuntimeSettings()))
+        linter = DocLinter(
+            config=project.lint if project else None,
+            runtime=lambda: connect(project.runtime if project else RuntimeSettings()),
+        )
         try:
             report = linter.lint_paths(sorted({f for files in groups.values() for f in files if f.is_file()}))
         except (LintTargetError, ConversionError) as exc:
@@ -150,13 +161,19 @@ def check_project(project: ProjectConfig) -> list[str]:
             if template is not None and not template.exists() and not settings.options.get("allow_missing_template"):
                 problems.append(f"documents.{name}: the {fmt} template {_shown(template)} is not there")
     for fmt, settings in project.outputs.items():
-        if settings.template is not None and not settings.template.exists() and not settings.options.get("allow_missing_template"):
+        if (
+            settings.template is not None
+            and not settings.template.exists()
+            and not settings.options.get("allow_missing_template")
+        ):
             problems.append(f"outputs.{fmt}: the template {_shown(settings.template)} is not there")
     if project.site is not None:
         from py_doc.site import engine_for
 
         if not engine_for(project.site.engine, project.site.dir).exists():
-            problems.append(f"site: there is no {project.site.engine} site in {_shown(project.site.dir)}. Run `py-doc site init`")
+            problems.append(
+                f"site: there is no {project.site.engine} site in {_shown(project.site.dir)}. Run `py-doc site init`"
+            )
     return problems
 
 
@@ -168,8 +185,15 @@ def run_check(argv: list[str]) -> int:
     parser.add_argument("-c", "--config", help="Configuration file (default: the nearest py-doc.yml)")
     parser.add_argument("--strict", action="store_true", help="Fail on lint warnings too")
     parser.add_argument("--no-lint", action="store_true", help="Check only the project, not the writing")
-    parser.add_argument("--engine", choices=("auto", "builtin", "vale"), default="auto", help="Lint engine, as for py-doc lint")
-    parser.add_argument("--format", choices=("text", "json", "sarif", "github", "csv"), default="text", help="How lint issues are written")
+    parser.add_argument(
+        "--engine", choices=("auto", "builtin", "vale"), default="auto", help="Lint engine, as for py-doc lint"
+    )
+    parser.add_argument(
+        "--format",
+        choices=("text", "json", "sarif", "github", "csv"),
+        default="text",
+        help="How lint issues are written",
+    )
     parser.add_argument("--output", metavar="FILE", help="Write the lint issues to this file")
     _noise(parser)
     args = parser.parse_args(argv)
@@ -188,7 +212,9 @@ def run_check(argv: list[str]) -> int:
     status = 1 if problems else 0
     if not args.no_lint:
         generated = {spec.output.resolve() for spec in project.generators}  # written by tools, not people
-        files = sorted({f.resolve() for name in project.own_documents for f in _sources(project, name) if f.exists()} - generated)
+        files = sorted(
+            {f.resolve() for name in project.own_documents for f in _sources(project, name) if f.exists()} - generated
+        )
         if files:
             linter = DocLinter(config=project.lint, runtime=lambda: connect(project.runtime), engine=args.engine)
             try:
@@ -210,7 +236,10 @@ def run_check(argv: list[str]) -> int:
             lint_summary = "no sources to lint"
     else:
         lint_summary = "lint skipped"
-    print(f"\n[SUMMARY] {len(project.documents)} document(s), {len(problems)} project problem(s), {lint_summary}", file=sys.stderr)
+    print(
+        f"\n[SUMMARY] {len(project.documents)} document(s), {len(problems)} project problem(s), {lint_summary}",
+        file=sys.stderr,
+    )
     return status
 
 
@@ -235,10 +264,17 @@ def run_diff(argv: list[str]) -> int:
         prog="py-doc diff", description="Compare two versions of Markdown documents by section: added, removed, renamed, moved and changed",
         epilog=DIFF_EXAMPLES, formatter_class=argparse.RawDescriptionHelpFormatter,
     )  # fmt: skip
-    parser.add_argument("paths", nargs="*", metavar="PATH", help="OLD NEW files, or with --rev the files and folders to compare (default: the sources of py-doc.yml)")
+    parser.add_argument(
+        "paths",
+        nargs="*",
+        metavar="PATH",
+        help="OLD NEW files, or with --rev the files and folders to compare (default: the sources of py-doc.yml)",
+    )
     parser.add_argument("--rev", metavar="REVISION", help="Compare the working files with this Git revision")
     parser.add_argument("-c", "--config", help="Configuration file (default: the nearest py-doc.yml)")
-    parser.add_argument("--format", choices=("text", "json"), default="text", help="text, a list per file (default), or json")
+    parser.add_argument(
+        "--format", choices=("text", "json"), default="text", help="text, a list per file (default), or json"
+    )
     parser.add_argument("--exit-code", action="store_true", help="Exit with status 1 when anything changed")
     _noise(parser)
     args = parser.parse_args(argv)
@@ -264,7 +300,10 @@ def run_diff(argv: list[str]) -> int:
             print(name)
             for change in changes:
                 print(f"  {change.describe()}")
-        print(f"\n[SUMMARY] {len(pairs)} file(s) compared, {len(results)} changed, {sum(len(c) for _, c in results)} section change(s)", file=sys.stderr)
+        print(
+            f"\n[SUMMARY] {len(pairs)} file(s) compared, {len(results)} changed, {sum(len(c) for _, c in results)} section change(s)",
+            file=sys.stderr,
+        )
     return 1 if args.exit_code and results else 0
 
 
@@ -288,7 +327,17 @@ def _diff_pairs(args: argparse.Namespace) -> list[tuple[str, str, str]]:
         files = [f.resolve() for name in project.own_documents for f in _sources(project, name)]
         # Files the revision had that are gone now: the ones under the same folders, listed by git
         folders = sorted({f.parent for f in files})
-        listed = _git(["ls-tree", "-r", "--name-only", args.rev, "--", *[str(d.relative_to(top).as_posix()) for d in folders if d.is_relative_to(top)]], top)
+        listed = _git(
+            [
+                "ls-tree",
+                "-r",
+                "--name-only",
+                args.rev,
+                "--",
+                *[str(d.relative_to(top).as_posix()) for d in folders if d.is_relative_to(top)],
+            ],
+            top,
+        )
         files += [top / line for line in listed.splitlines() if line.lower().endswith((".md", ".markdown"))]
     pairs = []
     for file in dict.fromkeys(files):
diff --git a/src/py_doc/analysis/diff.py b/src/py_doc/analysis/diff.py
index 20b64ea..082eca9 100644
--- a/src/py_doc/analysis/diff.py
+++ b/src/py_doc/analysis/diff.py
@@ -59,7 +59,13 @@ def as_dict(self) -> dict:
         def side(section: Section | None):
             return None if section is None else {"section": section.title, "level": section.level, "line": section.line}
 
-        return {"kind": self.kind, "old": side(self.old), "new": side(self.new), "words_added": self.words_added, "words_removed": self.words_removed}
+        return {
+            "kind": self.kind,
+            "old": side(self.old),
+            "new": side(self.new),
+            "words_added": self.words_added,
+            "words_removed": self.words_removed,
+        }
 
 
 def sections(text: str) -> list[Section]:
diff --git a/src/py_doc/app.py b/src/py_doc/app.py
index 436180c..7930d63 100644
--- a/src/py_doc/app.py
+++ b/src/py_doc/app.py
@@ -105,26 +105,53 @@ def build_parser() -> argparse.ArgumentParser:
     build.add_argument("documents", nargs="*", metavar="DOCUMENT", help="Documents and posters to build (default: all)")
     source = build.add_mutually_exclusive_group()
     source.add_argument("-c", "--config", help="Configuration file (default: the nearest py-doc.yml)")
-    source.add_argument("--legacy", metavar="FILE", help="Build from a legacy createdocs build file instead of py-doc.yml")
+    source.add_argument(
+        "--legacy", metavar="FILE", help="Build from a legacy createdocs build file instead of py-doc.yml"
+    )
     build.add_argument(
         "-f", "--format", action="append", choices=[*sorted(FORMATS), "poster"],
         help="Build only this format; poster builds only the posters",
     )  # fmt: skip
-    build.add_argument("--var", action="append", default=[], metavar="NAME=VALUE", type=_assignment, help="Set a {{variable}}")
     build.add_argument(
-        "--condition", action="append", default=[], metavar="NAME=VALUE", type=_assignment, help="Set a [[IF:]] condition"
+        "--var", action="append", default=[], metavar="NAME=VALUE", type=_assignment, help="Set a {{variable}}"
+    )
+    build.add_argument(
+        "--condition",
+        action="append",
+        default=[],
+        metavar="NAME=VALUE",
+        type=_assignment,
+        help="Set a [[IF:]] condition",
+    )
+    build.add_argument(
+        "--report", metavar="FILE", help="Write a JSON report of the build (default: reports.path in py-doc.yml)"
     )
-    build.add_argument("--report", metavar="FILE", help="Write a JSON report of the build (default: reports.path in py-doc.yml)")
     build.add_argument("--timestamps", action="store_true", help="Put the time and the render times in the report")
     build.add_argument("--keep-going", action="store_true", help="Report every broken diagram, not just the first")
     lint = build.add_mutually_exclusive_group()
-    lint.add_argument("--lint", dest="lint", action="store_const", const="on", help="Lint the sources first: an error stops the build")
-    lint.add_argument("--strict", dest="lint", action="store_const", const="strict", help="Lint the sources first: a warning stops the build too")
-    lint.add_argument("--no-lint", dest="lint", action="store_const", const="off", help="Do not lint, whatever build.lint says")
-    build.add_argument("--lint-report", metavar="FILE", help="Also write the lint issues to FILE (.sarif, .json or .csv)")
+    lint.add_argument(
+        "--lint", dest="lint", action="store_const", const="on", help="Lint the sources first: an error stops the build"
+    )
+    lint.add_argument(
+        "--strict",
+        dest="lint",
+        action="store_const",
+        const="strict",
+        help="Lint the sources first: a warning stops the build too",
+    )
+    lint.add_argument(
+        "--no-lint", dest="lint", action="store_const", const="off", help="Do not lint, whatever build.lint says"
+    )
+    build.add_argument(
+        "--lint-report", metavar="FILE", help="Also write the lint issues to FILE (.sarif, .json or .csv)"
+    )
     site = build.add_mutually_exclusive_group()
-    site.add_argument("--site", dest="site", action="store_true", default=None, help="Build the site after the documents")
-    site.add_argument("--no-site", dest="site", action="store_false", help="Do not build the site, whatever build.site says")
+    site.add_argument(
+        "--site", dest="site", action="store_true", default=None, help="Build the site after the documents"
+    )
+    site.add_argument(
+        "--no-site", dest="site", action="store_false", help="Do not build the site, whatever build.site says"
+    )
     build.add_argument("--no-generate", action="store_true", help="Do not run content.generators first")
     noise = build.add_mutually_exclusive_group()
     noise.add_argument("-q", "--quiet", action="store_true", help="Only show warnings and errors")
@@ -140,7 +167,11 @@ def build_parser() -> argparse.ArgumentParser:
     move.add_argument("paths", nargs="*", default=["."], metavar="PATH", help="Build files or folders to search")
     move.add_argument("-o", "--output", default="py-doc.yml", help="Configuration file to write (default: py-doc.yml)")
     move.add_argument(
-        "--from", dest="source", choices=LEGACY_FORMATS, default=LEGACY_FORMATS[0], help="Legacy format (default: createdocs, the only one)"
+        "--from",
+        dest="source",
+        choices=LEGACY_FORMATS,
+        default=LEGACY_FORMATS[0],
+        help="Legacy format (default: createdocs, the only one)",
     )
     move.add_argument("--check", action="store_true", help="Only report what would be migrated")
     move.add_argument("--backup", action="store_true", help="Keep copies (.bak) of the legacy files and any old output")
@@ -207,7 +238,9 @@ def _build(args: argparse.Namespace) -> int:
     configure_logging(quiet=args.quiet, verbose=args.verbose)
     path = Path(args.legacy or args.config) if args.legacy or args.config else find_config(Path.cwd())
     if path is None:
-        _error("No py-doc.yml found here or in a parent folder. Use --config, --legacy, or `py-doc migrate` to create one")
+        _error(
+            "No py-doc.yml found here or in a parent folder. Use --config, --legacy, or `py-doc migrate` to create one"
+        )
         return 1
     try:
         config = _load_legacy(path) if args.legacy else load_config(path)
@@ -251,7 +284,9 @@ def runtime():
     return status
 
 
-def _pipeline(args: argparse.Namespace, config, names: list[str], runtime, report: BuildReport | None, posters=()) -> int:
+def _pipeline(
+    args: argparse.Namespace, config, names: list[str], runtime, report: BuildReport | None, posters=()
+) -> int:
     """Generate, lint, build the documents and bundles, the posters and the site, then check the outputs.
 
     A failed stage stops the ones after it, except that every document is tried. Returns the exit status.
@@ -291,10 +326,19 @@ def step(name: str, state: str, detail: str = "") -> None:
     written: list[Path] = []
     for name in names:
         try:
-            written += build_document(
-                config, config.documents[name], args.format, dict(args.var), _conditions(args.condition), runtime,
-                args.keep_going, report,
-            ) or []
+            written += (
+                build_document(
+                    config,
+                    config.documents[name],
+                    args.format,
+                    dict(args.var),
+                    _conditions(args.condition),
+                    runtime,
+                    args.keep_going,
+                    report,
+                )
+                or []
+            )
         except (FileNotFoundError, ConversionError) as exc:
             _error(f"{name}: {exc}")
             failed += 1
@@ -351,7 +395,9 @@ def step(name: str, state: str, detail: str = "") -> None:
     return 1 if missing else 0
 
 
-def _build_posters(args: argparse.Namespace, config, names: list[str], runtime, report: BuildReport | None) -> tuple[int, list[Path]]:
+def _build_posters(
+    args: argparse.Namespace, config, names: list[str], runtime, report: BuildReport | None
+) -> tuple[int, list[Path]]:
     """Build each poster, and its PDF when it asks for one. One failure does not stop the others.
 
     Returns the exit status (0 when every poster was built) and the files written.
@@ -359,12 +405,21 @@ def _build_posters(args: argparse.Namespace, config, names: list[str], runtime,
     from .poster import write_poster
     from .poster_settings import layer, merge
 
-    overrides = layer({"variables": dict(args.var), "conditions": _conditions(args.condition)}, Path.cwd(), "the command line")
+    overrides = layer(
+        {"variables": dict(args.var), "conditions": _conditions(args.condition)}, Path.cwd(), "the command line"
+    )
     status, written = 0, []
     for name in names:
         poster = config.posters[name]
         try:
-            ctx, files = write_poster(poster.source, poster.output, runtime, merge(poster.settings, overrides), config.poster, mermaid=config.mermaid)
+            ctx, files = write_poster(
+                poster.source,
+                poster.output,
+                runtime,
+                merge(poster.settings, overrides),
+                config.poster,
+                mermaid=config.mermaid,
+            )
         except (FileNotFoundError, ConversionError) as exc:
             _error(f"{name}: {exc}")
             status = max(status, exit_status(exc) if isinstance(exc, ConversionError) else 1)
@@ -372,7 +427,10 @@ def _build_posters(args: argparse.Namespace, config, names: list[str], runtime,
                 report.failed(name, exc)
             continue
         for file in files:
-            logger.info(f"Wrote {_shown(file)}" + (f" ({ctx.n} diagram(s), {ctx.failed} not drawn)" if file.suffix == ".html" and ctx.n else ""))
+            logger.info(
+                f"Wrote {_shown(file)}"
+                + (f" ({ctx.n} diagram(s), {ctx.failed} not drawn)" if file.suffix == ".html" and ctx.n else "")
+            )
             if report:
                 report.output(name, "pdf" if file.suffix == ".pdf" else "html", file)
         written += files
@@ -410,7 +468,9 @@ def _lint_sources(config, names: list[str], mode: str, output: Path | None, runt
         logger.info(f"Wrote the lint issues to {output}")
     for result in lint.errors:
         _error(f"{_shown(result.file)}: {result.error}")
-    logger.info(f"Lint: {len(lint.issues)} issue(s) in {lint.files_scanned} file(s), {lint.count('warning')} warning or error")
+    logger.info(
+        f"Lint: {len(lint.issues)} issue(s) in {lint.files_scanned} file(s), {lint.count('warning')} warning or error"
+    )
     return lint_status(lint, mode == "strict")
 
 
diff --git a/src/py_doc/build.py b/src/py_doc/build.py
index 01ad27e..8a08e0e 100644
--- a/src/py_doc/build.py
+++ b/src/py_doc/build.py
@@ -21,6 +21,7 @@
 
 logger = logging.getLogger(__name__)
 
+
 def _combine_metadata(doc: DocumentConfig, first: Metadata, heading: str | None, root: Path | None = None) -> Metadata:
     """Properties from the configuration, then the first source's front matter, then its first heading.
 
@@ -82,7 +83,18 @@ def build_document(
 
 
 def render_output(
-    fmt, joined, metadata, output, name, source_dirs, template, settings, runtime, keep_going=False, report=None, mermaid=None
+    fmt,
+    joined,
+    metadata,
+    output,
+    name,
+    source_dirs,
+    template,
+    settings,
+    runtime,
+    keep_going=False,
+    report=None,
+    mermaid=None,
 ) -> Path:
     """Draw the diagrams of ``joined`` and have pandoc write ``output``. ``name`` is used in messages."""
     if runtime is None:
@@ -112,7 +124,9 @@ def render_output(
     if _numbers_headings_itself(fmt, template, settings):
         stripped = strip_heading_numbers(markdown)
         if stripped != markdown:
-            logger.info(f"{name}.{fmt} numbers its headings itself, so the numbers written in the headings are left out")
+            logger.info(
+                f"{name}.{fmt} numbers its headings itself, so the numbers written in the headings are left out"
+            )
         markdown = stripped
     job = PandocJob(fmt, markdown, metadata, output, source_dirs, template, settings, drawn.pictures)
     return convert(runtime(), job)
diff --git a/src/py_doc/c4/check.py b/src/py_doc/c4/check.py
index 6615d93..e60c236 100644
--- a/src/py_doc/c4/check.py
+++ b/src/py_doc/c4/check.py
@@ -51,5 +51,10 @@ def issue(rule: str, message: str) -> ModelIssue | None:
             found.append(issue("C4004", f"{element.kind} '{element.name}' has no relationships"))
     for rel in ws.relationships:
         if rel.linked_id is None and not rel.description:
-            found.append(issue("C4003", f"the relationship from '{ws.name_of(rel.source_id)}' to '{ws.name_of(rel.destination_id)}' has no description"))
+            found.append(
+                issue(
+                    "C4003",
+                    f"the relationship from '{ws.name_of(rel.source_id)}' to '{ws.name_of(rel.destination_id)}' has no description",
+                )
+            )
     return sorted((i for i in found if i), key=lambda i: (i.rule, i.message))
diff --git a/src/py_doc/c4/cli.py b/src/py_doc/c4/cli.py
index 5c0fe59..b10b197 100644
--- a/src/py_doc/c4/cli.py
+++ b/src/py_doc/c4/cli.py
@@ -35,7 +35,12 @@ def build_parser() -> argparse.ArgumentParser:
     actions = parser.add_subparsers(dest="action", metavar="action", required=True)
 
     def common(sub: argparse.ArgumentParser, many: bool = True) -> None:
-        sub.add_argument("workspace", nargs="?", default=".", help="A .dsl or workspace.json file, or a folder to search (default: .)")
+        sub.add_argument(
+            "workspace",
+            nargs="?",
+            default=".",
+            help="A .dsl or workspace.json file, or a folder to search (default: .)",
+        )
         sub.add_argument("-c", "--config", help="py-doc.yml to read (default: the nearest one)")
         noise = sub.add_mutually_exclusive_group()
         noise.add_argument("-q", "--quiet", action="store_true", help="Only show warnings and errors")
@@ -48,10 +53,14 @@ def common(sub: argparse.ArgumentParser, many: bool = True) -> None:
     export = actions.add_parser("export", help="Write diagrams, diagram source or Markdown for workspaces")
     common(export)
     export.add_argument("-o", "--output", default="c4_exports", help="Output folder (default: c4_exports)")
-    export.add_argument("-f", "--formats", nargs="+", choices=FORMATS, default=["svg", "plantuml", "mermaid"], help="Formats to write")
+    export.add_argument(
+        "-f", "--formats", nargs="+", choices=FORMATS, default=["svg", "plantuml", "mermaid"], help="Formats to write"
+    )
     export.add_argument("--views", nargs="+", metavar="KEY", help="Draw only these views")
     export.add_argument("--levels", nargs="+", choices=LEVELS, help="Levels of Markdown to write (default: all)")
-    export.add_argument("--url", help="A Structurizr Local or server that is already running, as the tool container can reach it")
+    export.add_argument(
+        "--url", help="A Structurizr Local or server that is already running, as the tool container can reach it"
+    )
     export.add_argument("--dry-run", action="store_true", help="List what would be written and write nothing")
 
     lock = actions.add_parser("lock", help="Pin the Structurizr Local image by digest in c4-images.lock")
@@ -120,7 +129,12 @@ def _stack(args: argparse.Namespace, files: list[Path], runtime, c4: C4Settings,
     if len(files) != 1:
         raise ConversionError(f"{len(files)} workspaces found. Name one: {', '.join(str(f) for f in files)}")
     stack = Stack(
-        runtime(), files[0], image=resolve_image(c4.image, root), port=c4.port or SERVER_PORT, live=True, state=root / ".py-doc"
+        runtime(),
+        files[0],
+        image=resolve_image(c4.image, root),
+        port=c4.port or SERVER_PORT,
+        live=True,
+        state=root / ".py-doc",
     )
     if args.action == "status":
         print(stack.status())
@@ -195,7 +209,9 @@ def _export(args: argparse.Namespace, files: list[Path], runtime, c4: C4Settings
     return 0
 
 
-def _export_one(args: argparse.Namespace, file: Path, out: Path, runtime, c4: C4Settings, cache: Path, root: Path) -> None:
+def _export_one(
+    args: argparse.Namespace, file: Path, out: Path, runtime, c4: C4Settings, cache: Path, root: Path
+) -> None:
     formats = list(dict.fromkeys(args.formats))
     cli = StructurizrCli(runtime, c4.cli)
     ws = load_workspace(workspace_json(file, cache, runtime, c4.cli))
@@ -204,13 +220,20 @@ def _export_one(args: argparse.Namespace, file: Path, out: Path, runtime, c4: C4
     if args.dry_run:
         names = [f"{out}/{p.name}" for fmt in formats if fmt in DRAWN for p in plan(ws, out, (fmt,), args.views).files]
         names += [f"{out}/{fmt}/" for fmt in formats if fmt in TEXT_FORMATS]
-        names += [f"{out}/markdown/{page}" for page in (generate(ws, file.name, levels=args.levels) if "markdown" in formats else {})]
+        names += [
+            f"{out}/markdown/{page}"
+            for page in (generate(ws, file.name, levels=args.levels) if "markdown" in formats else {})
+        ]
         print("\n".join(sorted(names)) or "Nothing to write")
         return
     drawn = tuple(f for f in formats if f in DRAWN)
     pictures: dict[str, str] = {}
     if drawn:
-        stack = ExternalStack(args.url) if args.url else Stack(runtime(), file, image=resolve_image(c4.image, root), port=c4.port or SERVER_PORT)
+        stack = (
+            ExternalStack(args.url)
+            if args.url
+            else Stack(runtime(), file, image=resolve_image(c4.image, root), port=c4.port or SERVER_PORT)
+        )
         files = render_views(ws, file, out, runtime(), formats=drawn, keys=args.views, stack=stack)
         pictures = {p.stem: p.name for p in files if p.suffix == f".{drawn[0]}"}
     for fmt in (f for f in formats if f in TEXT_FORMATS):
@@ -220,6 +243,8 @@ def _export_one(args: argparse.Namespace, file: Path, out: Path, runtime, c4: C4
     if "markdown" in formats:
         folder = out / "markdown"
         folder.mkdir(parents=True, exist_ok=True)
-        for name, text in generate(ws, file.name, levels=args.levels, images={k: f"../{v}" for k, v in pictures.items()}).items():
+        for name, text in generate(
+            ws, file.name, levels=args.levels, images={k: f"../{v}" for k, v in pictures.items()}
+        ).items():
             (folder / name).write_text(text, encoding="utf-8")
     print(f"Exported '{ws.name}' to {out}")
diff --git a/src/py_doc/c4/generate.py b/src/py_doc/c4/generate.py
index 1f24112..d2db65f 100644
--- a/src/py_doc/c4/generate.py
+++ b/src/py_doc/c4/generate.py
@@ -9,7 +9,17 @@
 
 import yaml
 
-from .model import Component, Container, DeploymentNode, Element, InfrastructureNode, Person, SoftwareSystem, View, Workspace
+from .model import (
+    Component,
+    Container,
+    DeploymentNode,
+    Element,
+    InfrastructureNode,
+    Person,
+    SoftwareSystem,
+    View,
+    Workspace,
+)
 
 LEVELS = ("context", "containers", "components", "relationships", "deployment", "dynamic", "catalogue", "documentation")
 PAGE_NAMES = {
@@ -48,7 +58,9 @@ def _table(headers: list[str], rows: list[list[str]]) -> list[str]:
 
 
 def _tags(element: Element) -> str:
-    return ", ".join(t for t in element.tags if t not in ("Element", "Person", "Software System", "Container", "Component"))
+    return ", ".join(
+        t for t in element.tags if t not in ("Element", "Person", "Software System", "Container", "Component")
+    )
 
 
 def _by_name(items: list[Element]) -> list[Element]:
@@ -57,7 +69,12 @@ def _by_name(items: list[Element]) -> list[Element]:
 
 class _Writer:
     def __init__(
-        self, ws: Workspace, source: str, images: dict[str, str], templates: dict[str, str], systems: list[str] | None,
+        self,
+        ws: Workspace,
+        source: str,
+        images: dict[str, str],
+        templates: dict[str, str],
+        systems: list[str] | None,
         sources: dict[str, tuple[str, str]],
     ):
         self.ws, self.source, self.images, self.templates = ws, source, images, {**TEMPLATES, **templates}
@@ -98,7 +115,14 @@ def figure(self, view: View) -> list[str]:
             out += [f"[[CAPTION:Figure]] {view.heading}", f"![{view.heading}]({image})", ""]
         elif view.key in self.sources:
             language, text = self.sources[view.key]
-            out += [f"Diagram source ({language}) of the view '{view.heading}':", "", f"```{language}", text.rstrip(), "```", ""]
+            out += [
+                f"Diagram source ({language}) of the view '{view.heading}':",
+                "",
+                f"```{language}",
+                text.rstrip(),
+                "```",
+                "",
+            ]
         return out
 
     # -- the pages ------------------------------------------------------------------------------
@@ -162,14 +186,21 @@ def walk(node: Element, depth: int) -> list[str]:
                         lines += walk(child, depth + 1)
                 return lines
 
-            for node in _by_name([n for n in self.ws.of_kind(DeploymentNode) if n.parent_id is None and n.environment == environment]):
+            for node in _by_name(
+                [n for n in self.ws.of_kind(DeploymentNode) if n.parent_id is None and n.environment == environment]
+            ):
                 body += walk(node, 0)
             body += [""]
             body += [line.replace("## View:", "### View:") for line in self.dep_views(environment)]
         return self.page("deployment", body)
 
     def dep_views(self, environment: str) -> list[str]:
-        return [line for v in self.ws.views if v.kind == "deployment" and v.environment == environment for line in self.figure(v)]
+        return [
+            line
+            for v in self.ws.views
+            if v.kind == "deployment" and v.environment == environment
+            for line in self.figure(v)
+        ]
 
     def dynamic(self) -> str:
         body = ["# Dynamic behaviour", "", self.say("dynamic"), ""]
@@ -192,10 +223,20 @@ def perspectives(self, elements: list[Element]) -> list[str]:
     def catalogue(self) -> str:
         ws = self.ws
         body = ["# Element catalogue", "", self.say("catalogue"), ""]
-        rows = [[e.name, e.kind, e.technology, e.description] for e in _by_name([e for e in ws.elements.values() if not e.kind.endswith("Instance")])]
+        rows = [
+            [e.name, e.kind, e.technology, e.description]
+            for e in _by_name([e for e in ws.elements.values() if not e.kind.endswith("Instance")])
+        ]
         body += _table(["Name", "Type", "Technology", "Description"], rows)
         body += ["## Glossary", ""]
-        terms = sorted({(e.name, e.description) for e in ws.elements.values() if e.description and not e.kind.endswith("Instance")}, key=lambda t: t[0].lower())
+        terms = sorted(
+            {
+                (e.name, e.description)
+                for e in ws.elements.values()
+                if e.description and not e.kind.endswith("Instance")
+            },
+            key=lambda t: t[0].lower(),
+        )
         body += _table(["Term", "Meaning"], [[n, d] for n, d in terms])
         return self.page("catalogue", body)
 
diff --git a/src/py_doc/c4/model.py b/src/py_doc/c4/model.py
index 7e6996b..016dae6 100644
--- a/src/py_doc/c4/model.py
+++ b/src/py_doc/c4/model.py
@@ -167,7 +167,12 @@ def _props(value: Any) -> dict[str, str]:
 
 def _sections(items: Any) -> list[Section]:
     return [
-        Section(str(s.get("title") or ""), str(s.get("content") or ""), str(s.get("format") or "Markdown"), int(s.get("order") or 0))
+        Section(
+            str(s.get("title") or ""),
+            str(s.get("content") or ""),
+            str(s.get("format") or "Markdown"),
+            int(s.get("order") or 0),
+        )
         for s in sorted(items or [], key=lambda s: int(s.get("order") or 0))
     ]
 
@@ -234,7 +239,9 @@ def workspace_from_dict(data: dict) -> Workspace:
         for m, c in enumerate(raw.get("containers") or []):
             container = _element(c, "container", f"model.softwareSystems[{n}].containers[{m}]", system, ws)
             for k, comp in enumerate(c.get("components") or []):
-                _element(comp, "component", f"model.softwareSystems[{n}].containers[{m}].components[{k}]", container, ws)
+                _element(
+                    comp, "component", f"model.softwareSystems[{n}].containers[{m}].components[{k}]", container, ws
+                )
 
     def deployment(raw: dict, where: str, parent: Element | None) -> None:
         node = _element(raw, "deploymentNode", where, parent, ws)
diff --git a/src/py_doc/c4/render.py b/src/py_doc/c4/render.py
index 9413065..ae96441 100644
--- a/src/py_doc/c4/render.py
+++ b/src/py_doc/c4/render.py
@@ -39,7 +39,9 @@ def plan(ws: Workspace, out_dir: Path, formats: tuple[str, ...], keys: list[str]
     chosen = [v for v in ws.views if keys is None or v.key in keys]
     missing = sorted(set(keys or []) - {v.key for v in chosen})
     if missing:
-        raise RenderError(f"The workspace has no view '{missing[0]}'. Views: {', '.join(v.key for v in ws.views) or 'none'}")
+        raise RenderError(
+            f"The workspace has no view '{missing[0]}'. Views: {', '.join(v.key for v in ws.views) or 'none'}"
+        )
     empty = [v.key for v in chosen if not v.element_ids and v.kind not in ("filtered", "image")]
     if empty:
         raise RenderError(f"These views are empty, so they cannot be drawn: {', '.join(empty)}")
@@ -68,7 +70,9 @@ def render_views(
     out_dir.mkdir(parents=True, exist_ok=True)
     for old in planned.files:
         old.unlink(missing_ok=True)  # a leftover from an earlier run must not pass for a new picture
-    stack = stack or Stack(runtime, workspace_file, **({"image": image} if image else {}), **({"port": port} if port else {}))
+    stack = stack or Stack(
+        runtime, workspace_file, **({"image": image} if image else {}), **({"port": port} if port else {})
+    )
     started = stack.up()
     failures: dict[str, str] = {}
     try:
@@ -76,11 +80,19 @@ def render_views(
             argv = ["node", SCRIPT, stack.url, fmt, "--output", out_dir.resolve()]
             if keys and len(keys) == 1:
                 argv += ["--view", keys[0]]
-            result = runtime.run(argv, mounts=[Mount(out_dir.resolve(), writable=True)], network=stack.network, timeout=TIMEOUT, check=False)
+            result = runtime.run(
+                argv,
+                mounts=[Mount(out_dir.resolve(), writable=True)],
+                network=stack.network,
+                timeout=TIMEOUT,
+                check=False,
+            )
             output = f"{result.stdout}\n{result.stderr}"
             named = _FAILED.search(output)
             if result.returncode == 1 or (result.returncode not in (0, 2)):
-                raise RenderError(f"Exporting {fmt} pictures failed (exit status {result.returncode}):\n{output.strip()}")
+                raise RenderError(
+                    f"Exporting {fmt} pictures failed (exit status {result.returncode}):\n{output.strip()}"
+                )
             if named:
                 for key in (k.strip() for k in named.group(1).split(",")):
                     failures[f"{key}.{fmt}"] = "the browser could not draw it"
diff --git a/src/py_doc/c4/source.py b/src/py_doc/c4/source.py
index a1bea42..19fc37d 100644
--- a/src/py_doc/c4/source.py
+++ b/src/py_doc/c4/source.py
@@ -53,7 +53,16 @@ def build_pages(
         raise ConversionError(f"The Structurizr workspace '{dsl}' does not exist")
     image = resolve_image(settings.image, cache.parent.parent)
     key = hashlib.sha256(
-        json.dumps([workspace_hash(dsl) if dsl.suffix == ".dsl" else dsl.read_text("utf-8"), spec.levels, spec.systems, spec.engine, spec.format, image]).encode()
+        json.dumps(
+            [
+                workspace_hash(dsl) if dsl.suffix == ".dsl" else dsl.read_text("utf-8"),
+                spec.levels,
+                spec.systems,
+                spec.engine,
+                spec.format,
+                image,
+            ]
+        ).encode()
     ).hexdigest()[:16]
     marker = out / ".hash"
     listed = sorted(out.glob("*.md")) if out.is_dir() else []
@@ -79,7 +88,9 @@ def build_pages(
 
     for old in out.glob("*.md"):
         old.unlink()
-    pages = generate(ws, dsl.name, levels=spec.levels or None, systems=spec.systems or None, images=images, sources=sources)
+    pages = generate(
+        ws, dsl.name, levels=spec.levels or None, systems=spec.systems or None, images=images, sources=sources
+    )
     written = []
     for name, text in pages.items():
         (out / name).write_text(text, encoding="utf-8")
@@ -102,7 +113,10 @@ def expand(
         for index, page in enumerate(pages):
             expanded.append(
                 replace(
-                    source, file=page, structurizr=None, title=source.title if index == 0 else None,
+                    source,
+                    file=page,
+                    structurizr=None,
+                    title=source.title if index == 0 else None,
                     page_break=source.page_break and index == 0,
                 )
             )
diff --git a/src/py_doc/c4/stack.py b/src/py_doc/c4/stack.py
index 7a7905e..796e1cc 100644
--- a/src/py_doc/c4/stack.py
+++ b/src/py_doc/c4/stack.py
@@ -162,7 +162,10 @@ def _wait(self) -> None:
             elapsed = time.monotonic() - started
             if self.status() != "running":
                 self._fail("Structurizr Local stopped while starting.")
-            if self.runtime.run(["node", "-e", PROBE, url], network=self.network, check=False, timeout=60).returncode == 0:
+            if (
+                self.runtime.run(["node", "-e", PROBE, url], network=self.network, check=False, timeout=60).returncode
+                == 0
+            ):
                 logger.info("Structurizr Local is ready after %d seconds", elapsed)
                 return
             if elapsed >= READY_SECONDS:
@@ -203,7 +206,11 @@ def _end_wsl_process(pid: int) -> None:
     """Stop process ``pid`` if it is still a ``wsl.exe``: a recorded number may since belong to another program."""
     try:
         listing = subprocess.run(
-            ["tasklist", "/FI", f"PID eq {pid}", "/FO", "CSV", "/NH"], capture_output=True, text=True, timeout=30, check=False
+            ["tasklist", "/FI", f"PID eq {pid}", "/FO", "CSV", "/NH"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            check=False,
         ).stdout
     except (OSError, subprocess.SubprocessError):
         return
diff --git a/src/py_doc/c4/structurizr.py b/src/py_doc/c4/structurizr.py
index fae0b4d..a055436 100644
--- a/src/py_doc/c4/structurizr.py
+++ b/src/py_doc/c4/structurizr.py
@@ -99,7 +99,9 @@ def _run(self, args: list, folder: Path, out: Path | None) -> tuple[str, str]:
         if self.cli:
             command = [self.cli, *[str(a) for a in args]]
             try:
-                done = subprocess.run(command, capture_output=True, text=True, encoding="utf-8", timeout=TIMEOUT, check=False)
+                done = subprocess.run(
+                    command, capture_output=True, text=True, encoding="utf-8", timeout=TIMEOUT, check=False
+                )
             except FileNotFoundError as exc:
                 raise EnvironmentProblem(
                     f"c4.cli '{self.cli}' was not found. It needs Java 17 or newer and structurizr-cli from "
@@ -119,7 +121,9 @@ def version(self) -> str:
         match = re.search(r"\d{4}\.\d+\.\d+", out + err)
         found = match.group(0) if match else "unknown"
         if found not in TESTED_VERSIONS:
-            logger.warning("structurizr-cli %s was not tested with py-doc. Tested: %s", found, ", ".join(TESTED_VERSIONS))
+            logger.warning(
+                "structurizr-cli %s was not tested with py-doc. Tested: %s", found, ", ".join(TESTED_VERSIONS)
+            )
         return found
 
     def export(self, dsl: Path, fmt: str, output: Path) -> list[Path]:
@@ -151,7 +155,9 @@ def workspace_json(
         return cached
     StructurizrCli(runtime, cli).version()
     with tempfile.TemporaryDirectory(prefix="py-doc-c4-") as tmp:
-        (made,) = [p for p in StructurizrCli(runtime, cli).export(workspace, "json", Path(tmp)) if p.suffix == ".json"][:1] or [None]
+        (made,) = [p for p in StructurizrCli(runtime, cli).export(workspace, "json", Path(tmp)) if p.suffix == ".json"][
+            :1
+        ] or [None]
         if made is None:
             raise ConversionError(f"structurizr-cli wrote no JSON for '{workspace}'")
         cache.mkdir(parents=True, exist_ok=True)
diff --git a/src/py_doc/config.py b/src/py_doc/config.py
index 03365ac..c196b34 100644
--- a/src/py_doc/config.py
+++ b/src/py_doc/config.py
@@ -115,7 +115,11 @@ class DocumentConfig:
     def metadata(self) -> Metadata:
         """The document properties set in the configuration. Unset ones stay None."""
         meta = self.meta
-        extra = {k: v for k, v in meta.items() if k not in ("title", "subtitle", "author", "date", "version", "status", "document_number", "keywords")}
+        extra = {
+            k: v
+            for k, v in meta.items()
+            if k not in ("title", "subtitle", "author", "date", "version", "status", "document_number", "keywords")
+        }
         return Metadata(
             title=_text(meta.get("title")),
             subtitle=_text(meta.get("subtitle")),
@@ -146,10 +150,18 @@ class SiteConfig:
     dir: Path
     title: str | None = None
     documents: list[str] = field(default_factory=list)  # empty: every document, in the order they are defined
-    downloads: list[str] = field(default_factory=list)  # built outputs (pdf, docx, ...) linked from each document's pages
-    targets: dict[str, str] = field(default_factory=dict)  # MkDocs: a site per config file in site.dir, sharing the pages
-    pages: dict[str, str] = field(default_factory=dict)  # hand-written pages for the navigation, after the documents: title -> path
-    groups: dict[str, list[str]] = field(default_factory=dict)  # a navigation section of several documents: title -> documents
+    downloads: list[str] = field(
+        default_factory=list
+    )  # built outputs (pdf, docx, ...) linked from each document's pages
+    targets: dict[str, str] = field(
+        default_factory=dict
+    )  # MkDocs: a site per config file in site.dir, sharing the pages
+    pages: dict[str, str] = field(
+        default_factory=dict
+    )  # hand-written pages for the navigation, after the documents: title -> path
+    groups: dict[str, list[str]] = field(
+        default_factory=dict
+    )  # a navigation section of several documents: title -> documents
     posters: list[str] = field(default_factory=list)  # posters of py-doc.yml on the site, linked from a Posters page
 
 
@@ -294,7 +306,28 @@ def _path(root: Path, value: Any, where: str) -> Path:
 
 def parse_config(data: Any, root: Path) -> ProjectConfig:
     top = _mapping(data, "the configuration")
-    _only(top, ("project", "documents", "outputs", "lint", "build", "runtime", "reports", "c4", "site", "collections", "bundles", "content", "poster", "posters", "diagrams", *RESERVED_SECTIONS), "the top level")
+    _only(
+        top,
+        (
+            "project",
+            "documents",
+            "outputs",
+            "lint",
+            "build",
+            "runtime",
+            "reports",
+            "c4",
+            "site",
+            "collections",
+            "bundles",
+            "content",
+            "poster",
+            "posters",
+            "diagrams",
+            *RESERVED_SECTIONS,
+        ),
+        "the top level",
+    )
     config = ProjectConfig(root=root)
 
     project = _mapping(top.get("project", {}), "project")
@@ -344,9 +377,13 @@ def parse_config(data: Any, root: Path) -> ProjectConfig:
         raise ConfigError(str(exc)) from None
     for name in config.site.posters if config.site else ():
         if name not in config.posters:
-            raise ConfigError(f"site.posters names '{name}', which is not under posters. Defined: {', '.join(config.posters) or 'none'}")
+            raise ConfigError(
+                f"site.posters names '{name}', which is not under posters. Defined: {', '.join(config.posters) or 'none'}"
+            )
     if config.site and config.site.posters and POSTERS_FOLDER in (config.site.documents or config.own_documents):
-        raise ConfigError(f"site.posters puts the posters in a '{POSTERS_FOLDER}' folder, and a document of the site has that name. Rename the document")
+        raise ConfigError(
+            f"site.posters puts the posters in a '{POSTERS_FOLDER}' folder, and a document of the site has that name. Rename the document"
+        )
 
     for name in RESERVED_SECTIONS:
         if name in top:
@@ -361,14 +398,20 @@ def _parse_poster(name: str, raw: Any, root: Path) -> PosterConfig:
     if "source" not in data:
         raise ConfigError(f"{where} needs a source: the Markdown file of the poster")
     source = _path(root, data["source"], f"{where}.source")
-    output = _path(root, data["output"], f"{where}.output") if "output" in data else root / DEFAULT_OUTPUT_DIR / f"{name}.html"
+    output = (
+        _path(root, data["output"], f"{where}.output")
+        if "output" in data
+        else root / DEFAULT_OUTPUT_DIR / f"{name}.html"
+    )
     rest = {key: value for key, value in data.items() if key not in poster_settings.ENTRY_KEYS}
     return PosterConfig(name, source, output, poster_settings.layer(rest, root, where))
 
 
 def _parse_build(data: dict, root: Path) -> BuildSettings:
     _only(data, ("generate", "lint", "lint_report", "site"), "build")
-    settings = BuildSettings(generate=_typed(data, "generate", bool, "build", True), site=_typed(data, "site", bool, "build", False))
+    settings = BuildSettings(
+        generate=_typed(data, "generate", bool, "build", True), site=_typed(data, "site", bool, "build", False)
+    )
     lint = data.get("lint", "off")
     lint = {False: "off", True: "on"}.get(lint, lint)  # YAML reads a bare off or on as a boolean
     if lint not in LINT_IN_BUILD:
@@ -421,7 +464,9 @@ def _parse_site(data: dict, root: Path, config: ProjectConfig) -> SiteConfig:
     documents = [str(name) for name in _typed(data, "documents", list, "site", [])]
     for name in documents:
         if name not in config.documents:
-            raise ConfigError(f"site.documents names '{name}', which is not under documents. Defined: {', '.join(config.documents)}")
+            raise ConfigError(
+                f"site.documents names '{name}', which is not under documents. Defined: {', '.join(config.documents)}"
+            )
     downloads = [str(fmt) for fmt in _typed(data, "downloads", list, "site", [])]
     for fmt in downloads:
         if fmt not in FORMATS:
@@ -534,9 +579,13 @@ def _parse_bundle(name: str, raw: Any, root: Path, config: ProjectConfig) -> Doc
     for doc_name in bundle.bundle:
         doc = config.documents.get(doc_name)
         if doc is None or doc.bundle:
-            raise ConfigError(f"{where}.documents names '{doc_name}', which is not under documents. Defined: {', '.join(config.own_documents)}")
+            raise ConfigError(
+                f"{where}.documents names '{doc_name}', which is not under documents. Defined: {', '.join(config.own_documents)}"
+            )
         for index, source in enumerate(doc.sources):
-            bundle.sources.append(replace(source, page_break=source.page_break or (index == 0 and bool(bundle.sources))))
+            bundle.sources.append(
+                replace(source, page_break=source.page_break or (index == 0 and bool(bundle.sources)))
+            )
         bundle.variables.update(doc.variables)
         bundle.conditions.update(doc.conditions)
     bundle.variables.update(_mapping(data.get("variables", {}), f"{where}.variables"))
@@ -545,7 +594,9 @@ def _parse_bundle(name: str, raw: Any, root: Path, config: ProjectConfig) -> Doc
     return bundle
 
 
-def _parse_document(doc_id: str, raw: Any, root: Path, collections: dict[str, list[Path]] | None = None) -> DocumentConfig:
+def _parse_document(
+    doc_id: str, raw: Any, root: Path, collections: dict[str, list[Path]] | None = None
+) -> DocumentConfig:
     where = f"documents.{doc_id}"
     data = _mapping(raw, where)
     _only(data, (*_META_KEYS, "sources", "outputs", "variables", "conditions"), where)
@@ -567,10 +618,27 @@ def _parse_document(doc_id: str, raw: Any, root: Path, collections: dict[str, li
             continue
         spec = None
         if "structurizr" in entry:
-            _only(entry, ("structurizr", "levels", "systems", "diagrams", "heading_offset", "title", "page_break"), place)
+            _only(
+                entry, ("structurizr", "levels", "systems", "diagrams", "heading_offset", "title", "page_break"), place
+            )
             spec = _parse_structurizr(entry, place)
             entry = {**entry, "file": entry["structurizr"]}
-        _only(entry, ("file", "structurizr", "levels", "systems", "diagrams", "heading_offset", "title", "page_break", "include", "site_path"), place)
+        _only(
+            entry,
+            (
+                "file",
+                "structurizr",
+                "levels",
+                "systems",
+                "diagrams",
+                "heading_offset",
+                "title",
+                "page_break",
+                "include",
+                "site_path",
+            ),
+            place,
+        )
         if "file" not in entry:
             raise ConfigError(f"{place} needs a 'file' or a 'structurizr' workspace")
         doc.sources.append(
@@ -595,10 +663,15 @@ def _collection_sources(entry: dict, place: str, collections: dict[str, list[Pat
     _only(entry, ("collection", "heading_offset", "page_break"), place)
     name = entry["collection"]
     if name not in collections:
-        raise ConfigError(f"{place}.collection names '{name}', which is not under collections. Defined: {', '.join(collections) or 'none'}")
+        raise ConfigError(
+            f"{place}.collection names '{name}', which is not under collections. Defined: {', '.join(collections) or 'none'}"
+        )
     offset = _typed(entry, "heading_offset", int, place, 0)
     page_break = _typed(entry, "page_break", bool, place, False)
-    return [Source(file=file, heading_offset=offset, page_break=page_break and i == 0) for i, file in enumerate(collections[name])]
+    return [
+        Source(file=file, heading_offset=offset, page_break=page_break and i == 0)
+        for i, file in enumerate(collections[name])
+    ]
 
 
 def _site_path(entry: dict, place: str) -> str | None:
@@ -652,7 +725,22 @@ def _parse_markdownlint(data: dict, root: Path) -> MarkdownlintSettings:
 
 
 def _parse_lint(data: dict, root: Path) -> LintConfig:
-    _only(data, ("exclude", "rules", "glossary", "phrases", "acronyms", "limits", "required_sections", "structure", "markdownlint", "vale"), "lint")
+    _only(
+        data,
+        (
+            "exclude",
+            "rules",
+            "glossary",
+            "phrases",
+            "acronyms",
+            "limits",
+            "required_sections",
+            "structure",
+            "markdownlint",
+            "vale",
+        ),
+        "lint",
+    )
     config = LintConfig()
 
     if "exclude" in data:
@@ -677,7 +765,9 @@ def _parse_lint(data: dict, root: Path) -> LintConfig:
     if "structure" in data:
         raw = data["structure"]
         try:
-            config.structure = load_rules(_path(root, raw, "lint.structure")) if isinstance(raw, str) else parse_rules(raw)
+            config.structure = (
+                load_rules(_path(root, raw, "lint.structure")) if isinstance(raw, str) else parse_rules(raw)
+            )
         except StructureRuleError as exc:
             raise ConfigError(str(exc)) from None
     config.root = root
@@ -699,9 +789,13 @@ def _parse_lint(data: dict, root: Path) -> LintConfig:
         for term, variants in config.glossary.items():
             for variant in variants:
                 if variant in config.glossary and variant != term:
-                    raise ConfigError(f"lint.glossary lists '{variant}' as a wrong spelling of '{term}', but it is a term of its own")
+                    raise ConfigError(
+                        f"lint.glossary lists '{variant}' as a wrong spelling of '{term}', but it is a term of its own"
+                    )
                 if owner.setdefault(variant, term) != term:
-                    raise ConfigError(f"lint.glossary lists '{variant}' as a wrong spelling of both '{owner[variant]}' and '{term}'")
+                    raise ConfigError(
+                        f"lint.glossary lists '{variant}' as a wrong spelling of both '{owner[variant]}' and '{term}'"
+                    )
     if "phrases" in data:
         for phrase, suggestion in _mapping(data["phrases"], "lint.phrases").items():
             config.redundant_phrases[str(phrase)] = "" if suggestion is None else str(suggestion)
@@ -723,7 +817,9 @@ def _parse_lint(data: dict, root: Path) -> LintConfig:
     config.acronym_require_definition = _typed(acronyms, "require_definition", bool, "lint.acronyms", True)
     config.acronym_scope = _typed(acronyms, "scope", str, "lint.acronyms", "file")
     if config.acronym_scope not in ACRONYM_SCOPES:
-        raise ConfigError(f"lint.acronyms.scope must be one of {', '.join(ACRONYM_SCOPES)}, not {config.acronym_scope!r}")
+        raise ConfigError(
+            f"lint.acronyms.scope must be one of {', '.join(ACRONYM_SCOPES)}, not {config.acronym_scope!r}"
+        )
     if "suggestion" in acronyms:
         config.acronym_suggestion = "" if acronyms["suggestion"] is None else str(acronyms["suggestion"])
     if "min_length" in acronyms:
diff --git a/src/py_doc/convert.py b/src/py_doc/convert.py
index 8d03a7f..b2ba7ff 100644
--- a/src/py_doc/convert.py
+++ b/src/py_doc/convert.py
@@ -55,9 +55,13 @@ def validate_template(self) -> None:
                 return
             raise FileNotFoundError(f"{self.kind} template not found: {path}")
         if path.suffix.lower() in self.template_suffixes and not zipfile.is_zipfile(path):
-            raise ConversionError(f"Cannot read {self.kind} template '{path}': it is not a valid {' or '.join(self.template_suffixes)} file")
+            raise ConversionError(
+                f"Cannot read {self.kind} template '{path}': it is not a valid {' or '.join(self.template_suffixes)} file"
+            )
         if path.suffix.lower() not in self.template_suffixes:
-            raise ConversionError(f"The {self.kind} template must be one of {', '.join(self.template_suffixes)}: {path}")
+            raise ConversionError(
+                f"The {self.kind} template must be one of {', '.join(self.template_suffixes)}: {path}"
+            )
 
     def convert_file(self, md_path: Path, output_path: Path) -> Path:
         return self._render(md_path, output_path, self.fmt, self.template_path, self.options)
diff --git a/src/py_doc/diagrams/registry.py b/src/py_doc/diagrams/registry.py
index c9c630d..a1696e2 100644
--- a/src/py_doc/diagrams/registry.py
+++ b/src/py_doc/diagrams/registry.py
@@ -34,9 +34,9 @@ class Job:
 # which is also in the tool image, draws it instead and says so.
 _SVG_TO_PNG = (
     'inkscape "$1" --export-type=png --export-filename="$2" --export-dpi=' + str(DPI) + " --export-background=white"
-    ' --export-background-opacity=1 --export-area-drawing;'
+    " --export-background-opacity=1 --export-area-drawing;"
     ' test -s "$2" || { echo "inkscape wrote no picture, so librsvg draws it" >&2;'
-    ' rsvg-convert --dpi-x=' + str(DPI) + " --dpi-y=" + str(DPI) + ' --background-color=white -o "$2" "$1"; }'
+    " rsvg-convert --dpi-x=" + str(DPI) + " --dpi-y=" + str(DPI) + ' --background-color=white -o "$2" "$1"; }'
 )
 
 
@@ -58,7 +58,9 @@ class Renderer:
     def commands(self, job: Job) -> list[Command]:
         """The commands for ``job``. An SVG-only tool is followed by Inkscape when the document needs PNG."""
         native = job.kind if job.kind in self.kinds else self.kinds[0]
-        commands = self.steps(Job(job.source, job.output.with_suffix(f".{native}"), native, job.landscape, job.source_dir))
+        commands = self.steps(
+            Job(job.source, job.output.with_suffix(f".{native}"), native, job.landscape, job.source_dir)
+        )
         if native == "svg" and job.kind == "png":
             commands.append(_svg_to_png(job))
         return commands
@@ -96,7 +98,12 @@ def _vega(tool: str) -> Callable[[Job], list[Command]]:
 RENDERERS: tuple[Renderer, ...] = (
     Renderer("mermaid", ("mermaid",), ".mmd", ("png", "svg"), _mermaid),
     Renderer(
-        "plantuml", ("plantuml", "puml"), ".puml", ("png", "svg"), _plantuml, needs_source_dir=True,
+        "plantuml",
+        ("plantuml", "puml"),
+        ".puml",
+        ("png", "svg"),
+        _plantuml,
+        needs_source_dir=True,
         environment=lambda folder: {"JAVA_TOOL_OPTIONS": f"-Dplantuml.include.path={folder}"},
         cacheable=lambda text: "!include" not in text,  # an included file can change without the diagram changing
     ),  # fmt: skip
@@ -106,14 +113,32 @@ def _vega(tool: str) -> Callable[[Job], list[Command]]:
         Renderer(tool, (tool,), ".diag", ("png",), _blockdiag(tool))
         for tool in ("blockdiag", "seqdiag", "actdiag", "nwdiag", "packetdiag")
     ),
-    Renderer("wavedrom", ("wavedrom",), ".json", ("svg",), lambda j: [["wavedrom-cli", "--input", j.source, "--svg", j.output]]),
     Renderer(
-        "bytefield-svg", ("bytefield-svg",), ".edn", ("svg",),
+        "wavedrom",
+        ("wavedrom",),
+        ".json",
+        ("svg",),
+        lambda j: [["wavedrom-cli", "--input", j.source, "--svg", j.output]],
+    ),
+    Renderer(
+        "bytefield-svg",
+        ("bytefield-svg",),
+        ".edn",
+        ("svg",),
         lambda j: [["bytefield-svg", "--source", j.source, "--output", j.output]],
     ),  # fmt: skip
-    Renderer("pikchr", ("pikchr",), ".pikchr", ("svg",), lambda j: [["python3", TOOLS / "pikchr_render.py", j.source, j.output]]),
     Renderer(
-        "railroad", ("railroad",), ".railroad", ("svg",),
+        "pikchr",
+        ("pikchr",),
+        ".pikchr",
+        ("svg",),
+        lambda j: [["python3", TOOLS / "pikchr_render.py", j.source, j.output]],
+    ),
+    Renderer(
+        "railroad",
+        ("railroad",),
+        ".railroad",
+        ("svg",),
         lambda j: [["python3", TOOLS / "railroad_render.py", j.source, j.output]],
     ),  # fmt: skip
     Renderer("wireviz", ("wireviz",), ".yml", ("svg",), lambda j: [["wireviz", "-f", "s", j.source]]),
diff --git a/src/py_doc/diagrams/render.py b/src/py_doc/diagrams/render.py
index 3584262..a46d695 100644
--- a/src/py_doc/diagrams/render.py
+++ b/src/py_doc/diagrams/render.py
@@ -103,7 +103,13 @@ def _draw(runtime: Runtime, renderer: Renderer, job_text: str, kind: str, landsc
 
 
 def draw_cached(
-    runtime: Runtime, renderer: Renderer, text: str, kind: str, landscape: bool, source_dir: Path, info: dict | None = None
+    runtime: Runtime,
+    renderer: Renderer,
+    text: str,
+    kind: str,
+    landscape: bool,
+    source_dir: Path,
+    info: dict | None = None,
 ) -> Path:
     """The picture for a diagram: from the cache when the same one was drawn before. ``info`` gets ``cached``."""
     key = _key(runtime, renderer, Job(Path(), Path(), kind, landscape), text)
@@ -219,7 +225,9 @@ def render_parts(
                     events.append(event)
             except (ToolFailed, DiagramError) as exc:
                 message = f"{file}:{block.line}: {block.fence} diagram failed: {_reason(exc)}"
-                event.update(status="failed", cached=False, seconds=round(time.monotonic() - started, 3), error=_reason(exc))
+                event.update(
+                    status="failed", cached=False, seconds=round(time.monotonic() - started, 3), error=_reason(exc)
+                )
                 if events is not None:
                     events.append(event)
                 if not keep_going:
@@ -233,7 +241,7 @@ def render_parts(
             width = block.options.get("width")
             if width:
                 if not _WIDTH.match(width):
-                    raise DiagramError(f"{file}:{block.line}: width=\"{width}\" is not a size such as 100%, 12cm or 4in")
+                    raise DiagramError(f'{file}:{block.line}: width="{width}" is not a size such as 100%, 12cm or 4in')
                 picture_line += f"{{width={width}}}"
             if fmt == "docx" and _captioned(lines, block):
                 picture_line += "\\ "  # a no-break space: not alone in its paragraph, so pandoc adds no caption
diff --git a/src/py_doc/diagrams/scan.py b/src/py_doc/diagrams/scan.py
index a68b57f..be97f76 100644
--- a/src/py_doc/diagrams/scan.py
+++ b/src/py_doc/diagrams/scan.py
@@ -45,7 +45,12 @@ def find_blocks(text: str) -> list[Block]:
                 end = index + 1
                 while end < len(lines):
                     closing = _OPEN.match(lines[end])
-                    if closing and closing["fence"][0] == marker[0] and len(closing["fence"]) >= len(marker) and not closing["info"]:
+                    if (
+                        closing
+                        and closing["fence"][0] == marker[0]
+                        and len(closing["fence"]) >= len(marker)
+                        and not closing["info"]
+                    ):
                         break
                     end += 1
                 body = "\n".join(lines[index + 1 : min(end, len(lines))])
diff --git a/src/py_doc/directives.py b/src/py_doc/directives.py
index 9a11f4f..5af5d3d 100644
--- a/src/py_doc/directives.py
+++ b/src/py_doc/directives.py
@@ -42,7 +42,14 @@
 _FENCE = re.compile(r"^ {0,3}(?P<fence>`{3,}|~{3,})")
 _INLINE_CODE = re.compile(r"(?P<ticks>`+)(?P<body>.+?)(?P=ticks)")
 
-_LANGUAGES = {".yml": "yaml", ".md": "markdown", ".sh": "bash", ".py": "python", ".js": "javascript", ".ts": "typescript"}
+_LANGUAGES = {
+    ".yml": "yaml",
+    ".md": "markdown",
+    ".sh": "bash",
+    ".py": "python",
+    ".js": "javascript",
+    ".ts": "typescript",
+}
 
 
 @dataclass(frozen=True)
diff --git a/src/py_doc/docx_import.py b/src/py_doc/docx_import.py
index 08853e8..8c07940 100644
--- a/src/py_doc/docx_import.py
+++ b/src/py_doc/docx_import.py
@@ -29,7 +29,16 @@
 logger = logging.getLogger(__name__)
 
 MAX_LIST_NESTING = 6
-MONOSPACE = {"consolas", "courier new", "courier", "lucida console", "menlo", "monaco", "source code pro", "cascadia code"}
+MONOSPACE = {
+    "consolas",
+    "courier new",
+    "courier",
+    "lucida console",
+    "menlo",
+    "monaco",
+    "source code pro",
+    "cascadia code",
+}
 CALLOUTS = {"note", "tip", "important", "warning", "caution"}
 QUOTE_STYLES = {"quote", "block text", "intense quote"}
 BITMAP_TYPES = {"image/jpeg", "image/jpg", "image/gif", "image/bmp", "image/tiff", "image/webp", "image/x-ms-bmp"}
@@ -165,7 +174,9 @@ def _blocks(self, parent) -> None:
             elif child.tag == W_SDT:
                 gallery = child.find(f"{qn('w:sdtPr')}/{qn('w:docPartObj')}/{qn('w:docPartGallery')}")
                 content = child.find(qn("w:sdtContent"))
-                if content is not None and not (gallery is not None and "table of contents" in gallery.get(W_VAL, "").lower()):
+                if content is not None and not (
+                    gallery is not None and "table of contents" in gallery.get(W_VAL, "").lower()
+                ):
                     self._blocks(content)
             elif child.tag == W_INS:
                 self._blocks(child)
@@ -188,7 +199,9 @@ def _paragraph(self, p, following) -> None:
         text = self._plain(tokens).strip()
         if self._is_toc(p, lower):
             return
-        only_images = tokens and all(isinstance(t, _Image) or (isinstance(t, _Piece) and not t.text.strip()) for t in tokens)
+        only_images = tokens and all(
+            isinstance(t, _Image) or (isinstance(t, _Piece) and not t.text.strip()) for t in tokens
+        )
         if lower in ("title", "subtitle", "author", "date") and text:
             setattr(self, lower, text)
             return
@@ -247,7 +260,7 @@ def _caption(self, text: str, following) -> None:
         self._close_list()
         match = re.match(r"(?i)^(figure|table)\s+\d+\s*[:.\-–—]?\s*", text)
         label = match.group(1).capitalize() if match else ""
-        text = text[match.end():] if match else text
+        text = text[match.end() :] if match else text
         previous = self.blocks[-1].kind if self.blocks else ""
         if not label:
             label = "Table" if (following is not None and following.tag == W_TBL) or previous == "table" else "Figure"
@@ -305,12 +318,18 @@ def _number_format(self, num_id: str, depth: int) -> str:
         abstract = self._numbering.xpath(f"w:num[@w:numId='{num_id}']/w:abstractNumId/@w:val")
         if not abstract:
             return "decimal"
-        fmt = self._numbering.xpath(f"w:abstractNum[@w:abstractNumId='{abstract[0]}']/w:lvl[@w:ilvl='{depth}']/w:numFmt/@w:val")
+        fmt = self._numbering.xpath(
+            f"w:abstractNum[@w:abstractNumId='{abstract[0]}']/w:lvl[@w:ilvl='{depth}']/w:numFmt/@w:val"
+        )
         return fmt[0] if fmt else "decimal"
 
     def _list_item(self, depth: int, marker: str, text: str) -> None:
         depth = min(depth, len(self._list_stack), MAX_LIST_NESTING)  # no deeper than one below the item above
-        same_list = bool(self.blocks) and self.blocks[-1].kind == "list" and not (depth == 0 and self._list_stack[:1] not in ([], [marker]))
+        same_list = (
+            bool(self.blocks)
+            and self.blocks[-1].kind == "list"
+            and not (depth == 0 and self._list_stack[:1] not in ([], [marker]))
+        )
         del self._list_stack[depth:]
         indent = "".join(" " * (len(m) + 1) for m in self._list_stack)
         self._list_stack.append(marker)
@@ -345,6 +364,7 @@ def _table(self, tbl) -> None:
             return
         columns = max(len(r) for r in rows)
         rows = [r + [""] * (columns - len(r)) for r in rows]
+
         def line(cells: list[str]) -> str:
             return "|" + "|".join(f" {c} " if c else " " for c in cells) + "|"
 
@@ -453,7 +473,9 @@ def _plain(self, tokens) -> str:
         return "".join(out)
 
     def _raw(self, tokens) -> str:
-        return "".join("\n" if isinstance(t, _Break) else t.text if isinstance(t, _Piece) else "" for t in tokens).rstrip()
+        return "".join(
+            "\n" if isinstance(t, _Break) else t.text if isinstance(t, _Piece) else "" for t in tokens
+        ).rstrip()
 
     def _monospace(self, tokens) -> bool:
         pieces = [t for t in tokens if isinstance(t, _Piece) and t.text.strip()]
@@ -486,7 +508,7 @@ def _piece(self, piece: _Piece) -> str:
         core = text.strip()
         if not core:
             return text
-        lead, trail = text[: len(text) - len(text.lstrip())], text[len(text.rstrip()):]
+        lead, trail = text[: len(text) - len(text.lstrip())], text[len(text.rstrip()) :]
         if piece.code:
             ticks = "``" if "`" in core else "`"
             pad = " " if "`" in core else ""
diff --git a/src/py_doc/generators/apidocs.py b/src/py_doc/generators/apidocs.py
index 03c8daa..03afd68 100644
--- a/src/py_doc/generators/apidocs.py
+++ b/src/py_doc/generators/apidocs.py
@@ -55,7 +55,9 @@ def clean_markdown(text: str, heading_offset: int = 0, title: str | None = None,
     title. Then the headings move by ``heading_offset``, and ``title`` replaces the first top heading. Code
     blocks are left as they are.
     """
-    text = _HTML_HEADING.sub(lambda m: f"{'#' * int(m.group(1))} {html.unescape(_TAG.sub('', m.group(2))).strip()}", text)
+    text = _HTML_HEADING.sub(
+        lambda m: f"{'#' * int(m.group(1))} {html.unescape(_TAG.sub('', m.group(2))).strip()}", text
+    )
     text = _ASIDE.sub(lambda m: _callout(m.group(1), m.group(2)), text)
     text = _ANCHOR.sub(lambda m: f"[]{{#{m.group(1)}}}", text)
     text = _LINK.sub(lambda m: f"[{html.unescape(_TAG.sub('', m.group(2))).strip()}]({m.group(1)})", text)
diff --git a/src/py_doc/generators/builtin.py b/src/py_doc/generators/builtin.py
index 90ad384..ffefc70 100644
--- a/src/py_doc/generators/builtin.py
+++ b/src/py_doc/generators/builtin.py
@@ -38,7 +38,15 @@
     "command": ("*run", "timeout"),
     "python": ("*callable",),
 }
-DIAGRAM_LANGUAGES = {".mmd": "mermaid", ".mermaid": "mermaid", ".puml": "plantuml", ".plantuml": "plantuml", ".dot": "dot", ".gv": "dot", ".d2": "d2"}
+DIAGRAM_LANGUAGES = {
+    ".mmd": "mermaid",
+    ".mermaid": "mermaid",
+    ".puml": "plantuml",
+    ".plantuml": "plantuml",
+    ".dot": "dot",
+    ".gv": "dot",
+    ".d2": "d2",
+}
 
 
 # --- helpers -------------------------------------------------------------------------------------
@@ -126,7 +134,10 @@ def glossary(spec: GeneratorSpec, project: ProjectConfig) -> str:
             raise GeneratorError(f"{spec.options['source']} must map each term to its definition")
         rows = [[term, definition] for term, definition in sorted(data.items(), key=lambda item: str(item[0]).lower())]
         return _heading(spec, "Glossary") + _table(["Term", "Definition"], rows)
-    rows = [[term, ", ".join(variants)] for term, variants in sorted(project.lint.glossary.items(), key=lambda item: item[0].lower())]
+    rows = [
+        [term, ", ".join(variants)]
+        for term, variants in sorted(project.lint.glossary.items(), key=lambda item: item[0].lower())
+    ]
     return _heading(spec, "Glossary") + _table(["Term", "Not written as"], rows)
 
 
@@ -145,7 +156,9 @@ def documents(spec: GeneratorSpec, project: ProjectConfig) -> str:
         doc = project.documents[name]
         first = next((s.file for s in doc.sources if s.include and s.structurizr is None), None)
         tree = _parsed(first) if first is not None and first.is_file() else None
-        meta = _combine_metadata(doc, read_metadata(tree) if tree else Metadata(), _first_heading(tree) if tree else None, project.root)
+        meta = _combine_metadata(
+            doc, read_metadata(tree) if tree else Metadata(), _first_heading(tree) if tree else None, project.root
+        )
         target = first if link == "source" else project.output_path(doc, link, meta.version)
         title = f"[{_cell(meta.title)}]({_link(spec, target)})" if target is not None else _cell(meta.title)
         rows.append([title, meta.document_id or "", meta.version or "", meta.status or ""])
@@ -183,7 +196,11 @@ def adr_index(spec: GeneratorSpec, project: ProjectConfig) -> str:
     if not folder.is_dir():
         raise GeneratorError(f"{folder} is not a folder")
     rows = []
-    for file in sorted(p for p in folder.iterdir() if p.suffix.lower() in (".md", ".markdown") and p.stem.lower() not in ("readme", "index")):
+    for file in sorted(
+        p
+        for p in folder.iterdir()
+        if p.suffix.lower() in (".md", ".markdown") and p.stem.lower() not in ("readme", "index")
+    ):
         text = file.read_text(encoding="utf-8-sig")
         tree = parse(text)
         meta = read_metadata(tree)
@@ -193,7 +210,9 @@ def adr_index(spec: GeneratorSpec, project: ProjectConfig) -> str:
             status = found.group(1) if found else _under_heading(tree, "status")
         number = re.match(r"^(\d+)", file.stem)
         title = meta.title or _first_heading(tree) or file.stem
-        rows.append([number.group(1) if number else "", f"[{_cell(title)}]({_link(spec, file)})", status or "", meta.date or ""])
+        rows.append(
+            [number.group(1) if number else "", f"[{_cell(title)}]({_link(spec, file)})", status or "", meta.date or ""]
+        )
     return _heading(spec, "Architecture decisions") + _table(["Number", "Decision", "Status", "Date"], rows)
 
 
@@ -300,12 +319,15 @@ def openapi_summary(spec: GeneratorSpec, project: ProjectConfig) -> str:
         for method in _METHODS:
             operation = (item or {}).get(method)
             if isinstance(operation, dict):
-                rows.append([f"`{method.upper()}`", f"`{path}`", operation.get("summary") or operation.get("operationId") or ""])
+                rows.append(
+                    [f"`{method.upper()}`", f"`{path}`", operation.get("summary") or operation.get("operationId") or ""]
+                )
     out += "## Operations\n\n" + (_table(["Method", "Path", "Summary"], rows) if rows else "None.")
-    schemas = ((api.get("components") or {}).get("schemas") or api.get("definitions") or {})
+    schemas = (api.get("components") or {}).get("schemas") or api.get("definitions") or {}
     if schemas:
         out += "\n\n## Schemas\n\n" + "\n".join(
-            f"- `{name}`" + (f": {_cell((body or {}).get('description'))}" if (body or {}).get("description") else "") for name, body in schemas.items()
+            f"- `{name}`" + (f": {_cell((body or {}).get('description'))}" if (body or {}).get("description") else "")
+            for name, body in schemas.items()
         )
     return out
 
@@ -323,10 +345,19 @@ def asyncapi_summary(spec: GeneratorSpec, project: ProjectConfig) -> str:
     for name, channel in (api.get("channels") or {}).items():
         channel = channel or {}
         address = channel.get("address") or name
-        operations = [(kind, channel[kind]) for kind in ("publish", "subscribe") if isinstance(channel.get(kind), dict)]  # version 2
+        operations = [
+            (kind, channel[kind]) for kind in ("publish", "subscribe") if isinstance(channel.get(kind), dict)
+        ]  # version 2
         for kind, operation in operations:
-            message = (operation.get("message") or {})
-            rows.append([f"`{address}`", kind, message.get("name") or message.get("title") or _ref(message), operation.get("summary") or channel.get("description") or ""])
+            message = operation.get("message") or {}
+            rows.append(
+                [
+                    f"`{address}`",
+                    kind,
+                    message.get("name") or message.get("title") or _ref(message),
+                    operation.get("summary") or channel.get("description") or "",
+                ]
+            )
         if not operations:
             messages = ", ".join(str(m) for m in (channel.get("messages") or {}))
             rows.append([f"`{address}`", "", messages, channel.get("description") or channel.get("summary") or ""])
@@ -353,7 +384,9 @@ def python_api(spec: GeneratorSpec, project: ProjectConfig) -> str:
     out = _heading(spec, f"{source.stem} reference")
     for file in files:
         module = ".".join(file.relative_to(base).with_suffix("").parts).removesuffix(".__init__")
-        if not private and any(part.startswith("_") and part != "__init__" for part in file.relative_to(base).with_suffix("").parts):
+        if not private and any(
+            part.startswith("_") and part != "__init__" for part in file.relative_to(base).with_suffix("").parts
+        ):
             continue
         try:
             tree = ast.parse(file.read_text(encoding="utf-8-sig"), str(file))
@@ -361,7 +394,9 @@ def python_api(spec: GeneratorSpec, project: ProjectConfig) -> str:
             raise GeneratorError(f"{file} is not valid Python: {exc}") from exc
         body = []
         for node in tree.body:
-            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)) and (private or not node.name.startswith("_")):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)) and (
+                private or not node.name.startswith("_")
+            ):
                 body.append(_describe(node, 3, private))
         doc = _summary(ast.get_docstring(tree))
         if body or doc:
@@ -380,7 +415,8 @@ def _describe(node: ast.AST, level: int, private: bool) -> str:
         methods = [
             _describe(child, level + 1, private)
             for child in node.body
-            if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)) and (private or not child.name.startswith("_") or child.name == "__init__")
+            if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef))
+            and (private or not child.name.startswith("_") or child.name == "__init__")
         ]
         return "\n\n".join([text, *methods])
     prefix = "async " if isinstance(node, ast.AsyncFunctionDef) else ""
@@ -413,13 +449,22 @@ def command(spec: GeneratorSpec, project: ProjectConfig) -> str:
     if not argv:
         raise GeneratorError(f"The generator {spec.name}: run must be a list, such as [python, tools/make_table.py]")
     try:
-        result = subprocess.run(argv, cwd=project.root, capture_output=True, encoding="utf-8", errors="replace", timeout=int(spec.options.get("timeout", 300)))
+        result = subprocess.run(
+            argv,
+            cwd=project.root,
+            capture_output=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=int(spec.options.get("timeout", 300)),
+        )
     except FileNotFoundError as exc:
         raise GeneratorError(f"The generator {spec.name}: {argv[0]} is not found") from exc
     except subprocess.TimeoutExpired as exc:
         raise GeneratorError(f"The generator {spec.name}: {argv[0]} took longer than {exc.timeout} s") from exc
     if result.returncode != 0:
-        raise GeneratorError(f"The generator {spec.name}: {argv[0]} exited with status {result.returncode}: {result.stderr.strip()}")
+        raise GeneratorError(
+            f"The generator {spec.name}: {argv[0]} exited with status {result.returncode}: {result.stderr.strip()}"
+        )
     return result.stdout
 
 
diff --git a/src/py_doc/generators/registry.py b/src/py_doc/generators/registry.py
index a13d0c0..7e3b111 100644
--- a/src/py_doc/generators/registry.py
+++ b/src/py_doc/generators/registry.py
@@ -88,7 +88,9 @@ def for_documents(project: ProjectConfig, documents: list[str]) -> list[str]:
     return [spec.name for spec in project.generators if spec.output.resolve() in sources]
 
 
-def run_generators(project: ProjectConfig, names: list[str] | None = None, runtime: Callable | None = None) -> list[Path]:
+def run_generators(
+    project: ProjectConfig, names: list[str] | None = None, runtime: Callable | None = None
+) -> list[Path]:
     """Run the generators of ``project`` (or the ones named), in order. Returns the files that changed.
 
     ``runtime`` returns the tool container, for the generators that run a tool. Without it, one is connected
@@ -106,23 +108,31 @@ def _run_all(project: ProjectConfig, names: list[str] | None) -> list[Path]:
     if names:
         unknown = [name for name in names if name not in {spec.name for spec in specs}]
         if unknown:
-            raise GeneratorError(f"Unknown generator(s): {', '.join(unknown)}. Defined: {', '.join(s.name for s in specs) or 'none'}")
+            raise GeneratorError(
+                f"Unknown generator(s): {', '.join(unknown)}. Defined: {', '.join(s.name for s in specs) or 'none'}"
+            )
         specs = [spec for spec in specs if spec.name in names]
     registry = available()
     changed: list[Path] = []
     for spec in specs:
         generate = load_callable(spec.options["callable"]) if spec.type == "python" else registry.get(spec.type)
         if generate is None:
-            raise GeneratorError(f"content.generators: '{spec.name}' has the unknown type '{spec.type}'. Types: {', '.join(sorted(registry))}")
+            raise GeneratorError(
+                f"content.generators: '{spec.name}' has the unknown type '{spec.type}'. Types: {', '.join(sorted(registry))}"
+            )
         logger.info(f"Generating {spec.name} ({spec.type})")
         try:
             text = generate(spec, project)
         except GeneratorError:
             raise
         except Exception as exc:  # a generator of someone else's must not hide where it failed
-            raise GeneratorError(f"The generator {spec.name} ({spec.type}) failed: {type(exc).__name__}: {exc}") from exc
+            raise GeneratorError(
+                f"The generator {spec.name} ({spec.type}) failed: {type(exc).__name__}: {exc}"
+            ) from exc
         if not isinstance(text, str):
-            raise GeneratorError(f"The generator {spec.name} ({spec.type}) returned {type(text).__name__}, not Markdown text")
+            raise GeneratorError(
+                f"The generator {spec.name} ({spec.type}) returned {type(text).__name__}, not Markdown text"
+            )
         text = text.rstrip() + "\n"
         old = spec.output.read_text(encoding="utf-8") if spec.output.is_file() else None
         if old != text:
diff --git a/src/py_doc/import_cli.py b/src/py_doc/import_cli.py
index 800f865..5a98ed1 100644
--- a/src/py_doc/import_cli.py
+++ b/src/py_doc/import_cli.py
@@ -18,9 +18,15 @@ def build_parser() -> argparse.ArgumentParser:
         prog="py-doc import", description="Convert a Word document (.docx) or a PowerPoint deck (.pptx) to Markdown"
     )
     parser.add_argument("input", type=Path, help="The .docx or .pptx file")
-    parser.add_argument("-o", "--output", type=Path, help="Folder for the .md file and its media folder (default: next to the input)")
+    parser.add_argument(
+        "-o", "--output", type=Path, help="Folder for the .md file and its media folder (default: next to the input)"
+    )
     parser.add_argument("--force", action="store_true", help="Replace an existing .md file")
-    parser.add_argument("--no-defloat-images", action="store_true", help="Word: leave floating pictures out instead of placing them inline")
+    parser.add_argument(
+        "--no-defloat-images",
+        action="store_true",
+        help="Word: leave floating pictures out instead of placing them inline",
+    )
     parser.add_argument("--print-output-paths", action="store_true", help="Print where the Markdown and the media went")
     noise = parser.add_mutually_exclusive_group()
     noise.add_argument("-q", "--quiet", action="store_true", help="Only show warnings and errors")
diff --git a/src/py_doc/init.py b/src/py_doc/init.py
index aa56043..2760802 100644
--- a/src/py_doc/init.py
+++ b/src/py_doc/init.py
@@ -38,12 +38,21 @@ class Choices:
 
 
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="py-doc init", description="Start a documentation project: py-doc.yml, a first document and more")
+    parser = argparse.ArgumentParser(
+        prog="py-doc init", description="Start a documentation project: py-doc.yml, a first document and more"
+    )
     parser.add_argument("folder", nargs="?", default=".", type=Path, help="Where to make it (default: here)")
     parser.add_argument("--name", help="The project name (default: the folder name)")
     parser.add_argument("--site", choices=(*SITE_ENGINES, "none"), help="Also make a web site project")
-    parser.add_argument("--c4", action="store_true", default=None, help="Also make a Structurizr C4 model and a document from it")
-    parser.add_argument("--templates", action="store_true", default=None, help="Also write Word and PowerPoint templates (needs the tool container)")
+    parser.add_argument(
+        "--c4", action="store_true", default=None, help="Also make a Structurizr C4 model and a document from it"
+    )
+    parser.add_argument(
+        "--templates",
+        action="store_true",
+        default=None,
+        help="Also write Word and PowerPoint templates (needs the tool container)",
+    )
     parser.add_argument("-y", "--yes", action="store_true", help="Ask nothing: take the defaults for what is not given")
     noise = parser.add_mutually_exclusive_group()
     noise.add_argument("-q", "--quiet", action="store_true", help="Only show warnings and errors")
@@ -69,7 +78,11 @@ def choose(args: argparse.Namespace, folder: Path, ask: Callable[[str], str] | N
         while site not in (*SITE_ENGINES, "none"):
             site = _ask(f"Web site: {', '.join(SITE_ENGINES)} or none", "none", ask).lower()
     c4 = args.c4 if args.c4 is not None else (_yes("A C4 architecture model (Structurizr)?", ask) if ask else False)
-    templates = args.templates if args.templates is not None else (_yes("Word and PowerPoint templates?", ask) if ask else False)
+    templates = (
+        args.templates
+        if args.templates is not None
+        else (_yes("Word and PowerPoint templates?", ask) if ask else False)
+    )
     return Choices(name, None if site in (None, "none") else site, c4, templates)
 
 
@@ -88,7 +101,9 @@ def config_text(choices: Choices) -> str:
         text = text.replace("    # template: templates/reference.docx", "    template: templates/reference.docx")
         text = text.replace("    # template: templates/reference.pptx", "    template: templates/reference.pptx")
     if choices.c4:
-        text = text.replace("\n# A JSON report", "\n" + ARCHITECTURE_DOC.replace("{name}", choices.name) + "# A JSON report", 1)
+        text = text.replace(
+            "\n# A JSON report", "\n" + ARCHITECTURE_DOC.replace("{name}", choices.name) + "# A JSON report", 1
+        )
     if choices.site:
         text += SITE.format(engine=choices.site)
     return text
@@ -99,7 +114,9 @@ def make_project(folder: Path, choices: Choices, runtime=connect) -> list[Path]:
     folder = Path(folder)
     for name in CONFIG_NAMES:
         if (folder / name).exists():
-            raise ConversionError(f"{folder / name} is already there: this folder is a py-doc project. Nothing was changed")
+            raise ConversionError(
+                f"{folder / name} is already there: this folder is a py-doc project. Nothing was changed"
+            )
     files = project_files(choices)
     try:  # a configuration that would not load is a bug: say so before anything is written
         parse_config(yaml.safe_load(files["py-doc.yml"]), folder.resolve())
@@ -161,7 +178,11 @@ def _templates(folder: Path, runtime) -> list[Path]:
             written.append(wanted[0])
         if not wanted[1].exists():
             made = work / "reference.pptx"
-            box.run(["pandoc", "-o", made, "--print-default-data-file", "reference.pptx"], mounts=[Mount(work, writable=True)], workdir=work)
+            box.run(
+                ["pandoc", "-o", made, "--print-default-data-file", "reference.pptx"],
+                mounts=[Mount(work, writable=True)],
+                workdir=work,
+            )
             wanted[1].write_bytes(made.read_bytes())
             written.append(wanted[1])
     return written
diff --git a/src/py_doc/lint/cli.py b/src/py_doc/lint/cli.py
index f4f3abd..2a4e66a 100644
--- a/src/py_doc/lint/cli.py
+++ b/src/py_doc/lint/cli.py
@@ -64,7 +64,9 @@ def run(argv: list[str] | None = None, legacy: bool = False) -> int:
     parser.add_argument(
         "--exclude", action="append", default=[], metavar="DIR", help="Also skip directories with this name"
     )
-    parser.add_argument("--config", metavar="FILE", help="py-doc.yml to read (default: the nearest one above the first target)")
+    parser.add_argument(
+        "--config", metavar="FILE", help="py-doc.yml to read (default: the nearest one above the first target)"
+    )
     parser.add_argument(
         "--engine", choices=("auto", "builtin", "vale"), default="auto",
         help="auto runs the built-in rules and Vale when it is installed, builtin skips Vale, vale uses Vale for the text rules",
@@ -74,9 +76,15 @@ def run(argv: list[str] | None = None, legacy: bool = False) -> int:
         help="text (default), csv for a spreadsheet, github for workflow annotations, json, or sarif for code scanning",
     )  # fmt: skip
     parser.add_argument("--output", metavar="FILE", help="Write the report to this file instead of standard output")
-    parser.add_argument("--show-vale-config", action="store_true", help="Print the Vale configuration py-doc would use and exit")
-    parser.add_argument("--check-engines", action="store_true", help="Report whether Vale is found, its version and its folder")
-    parser.add_argument("--sync", action="store_true", help="Download the Vale packages in lint.vale.packages (vale sync)")
+    parser.add_argument(
+        "--show-vale-config", action="store_true", help="Print the Vale configuration py-doc would use and exit"
+    )
+    parser.add_argument(
+        "--check-engines", action="store_true", help="Report whether Vale is found, its version and its folder"
+    )
+    parser.add_argument(
+        "--sync", action="store_true", help="Download the Vale packages in lint.vale.packages (vale sync)"
+    )
     parser.add_argument(
         "--print-example-rules", action="store_true", help="Print an example set of structure rules and exit"
     )
@@ -98,7 +106,10 @@ def run(argv: list[str] | None = None, legacy: bool = False) -> int:
         return 2
     config.exclude_dirs = config.exclude_dirs | frozenset(args.exclude)
     linter = DocLinter(
-        config=config, runtime=lambda: connect(settings), engine=args.engine, extra_checks=_model_checks(args, config, settings)
+        config=config,
+        runtime=lambda: connect(settings),
+        engine=args.engine,
+        extra_checks=_model_checks(args, config, settings),
     )
     try:
         if args.show_vale_config or args.check_engines or args.sync:
@@ -135,12 +146,15 @@ def runtime():
 
         for file in files:
             try:
-                ws = load_workspace(workspace_json(file, project.root / ".py-doc" / "c4" / "json", runtime, project.c4.cli))
+                ws = load_workspace(
+                    workspace_json(file, project.root / ".py-doc" / "c4" / "json", runtime, project.c4.cli)
+                )
             except EnvironmentProblem as exc:
                 logger.warning("The model rules for %s were skipped: %s", file.name, exc)
                 continue
             found += [
-                LintIssue(file.resolve(), 1, i.rule, "C4 model", i.message, i.severity) for i in check_model(ws, file, config)
+                LintIssue(file.resolve(), 1, i.rule, "C4 model", i.message, i.severity)
+                for i in check_model(ws, file, config)
             ]
         return found
 
diff --git a/src/py_doc/lint/config.py b/src/py_doc/lint/config.py
index 505f908..10b95fe 100644
--- a/src/py_doc/lint/config.py
+++ b/src/py_doc/lint/config.py
@@ -82,10 +82,20 @@ class LintConfig:
     disabled_rules: frozenset[str] = frozenset()
     severities: dict[str, str] = field(
         default_factory=lambda: {
-            RULE_GLOSSARY: "warning", RULE_REDUNDANT: "warning", RULE_ACRONYM: "info", RULE_DIRECTIVE: "error",
-            RULE_HEADING_JUMP: "warning", RULE_BROKEN_LINK: "warning", RULE_IMAGE_ALT: "warning",
-            RULE_SENTENCE_LENGTH: "info", RULE_HEADING_LENGTH: "info", RULE_DUPLICATE_HEADING: "info",
-            RULE_UNCLOSED_FENCE: "error", RULE_REQUIRED_SECTION: "warning", RULE_TERMINOLOGY: "info", **C4_RULES,
+            RULE_GLOSSARY: "warning",
+            RULE_REDUNDANT: "warning",
+            RULE_ACRONYM: "info",
+            RULE_DIRECTIVE: "error",
+            RULE_HEADING_JUMP: "warning",
+            RULE_BROKEN_LINK: "warning",
+            RULE_IMAGE_ALT: "warning",
+            RULE_SENTENCE_LENGTH: "info",
+            RULE_HEADING_LENGTH: "info",
+            RULE_DUPLICATE_HEADING: "info",
+            RULE_UNCLOSED_FENCE: "error",
+            RULE_REQUIRED_SECTION: "warning",
+            RULE_TERMINOLOGY: "info",
+            **C4_RULES,
         }  # fmt: skip
     )
     structure: list = field(default_factory=list)  # StructureRule entries, see lint.structure
@@ -94,4 +104,6 @@ class LintConfig:
     root: Path = field(default_factory=Path.cwd)  # the project folder: where the managed Vale folder lives
     documents: dict[str, list[Path]] = field(default_factory=dict)  # document id -> its source files, in order
     generated: frozenset[Path] = frozenset()  # files content generators write: not missing before they run
-    posters: frozenset[Path] = frozenset()  # poster sources: their prose is linted, but not by the document structure rules
+    posters: frozenset[Path] = (
+        frozenset()
+    )  # poster sources: their prose is linted, but not by the document structure rules
diff --git a/src/py_doc/lint/formats.py b/src/py_doc/lint/formats.py
index dac69b8..545baf6 100644
--- a/src/py_doc/lint/formats.py
+++ b/src/py_doc/lint/formats.py
@@ -38,7 +38,12 @@ def summary(report: LintReport) -> dict:
     counts = {severity: 0 for severity in ("error", "warning", "info")}
     for issue in report.issues:
         counts[issue.severity] = counts.get(issue.severity, 0) + 1
-    return {"files_scanned": report.files_scanned, "issues": len(report.issues), **counts, "files_failed": len(report.errors)}
+    return {
+        "files_scanned": report.files_scanned,
+        "issues": len(report.issues),
+        **counts,
+        "files_failed": len(report.errors),
+    }
 
 
 def to_json(report: LintReport, issues: list[LintIssue], errors: list[FileResult]) -> str:
@@ -75,13 +80,24 @@ def to_sarif(issues: list[LintIssue], errors: list[FileResult]) -> str:
             }
         )
     run = {
-        "tool": {"driver": {"name": "py-doc", "version": __version__, "informationUri": "https://github.com/markbac/py-doc", "rules": list(rules.values())}},
+        "tool": {
+            "driver": {
+                "name": "py-doc",
+                "version": __version__,
+                "informationUri": "https://github.com/markbac/py-doc",
+                "rules": list(rules.values()),
+            }
+        },
         "results": results,
         "invocations": [
             {
                 "executionSuccessful": not errors,
                 "toolExecutionNotifications": [
-                    {"level": "error", "message": {"text": result.error}, "locations": [{"physicalLocation": {"artifactLocation": {"uri": _path(result.file)}}}]}
+                    {
+                        "level": "error",
+                        "message": {"text": result.error},
+                        "locations": [{"physicalLocation": {"artifactLocation": {"uri": _path(result.file)}}}],
+                    }
                     for result in errors
                 ],
             }
diff --git a/src/py_doc/lint/linter.py b/src/py_doc/lint/linter.py
index 9ea7cf4..e2062f0 100644
--- a/src/py_doc/lint/linter.py
+++ b/src/py_doc/lint/linter.py
@@ -71,7 +71,9 @@ def __init__(
         """
         self.runtime = runtime
         self.engine = engine
-        self.extra_checks = list(extra_checks or [])  # checks of things other than Markdown, such as a Structurizr model
+        self.extra_checks = list(
+            extra_checks or []
+        )  # checks of things other than Markdown, such as a Structurizr model
         self.config = config or LintConfig()
         if glossary is not None:
             self.config.glossary = glossary
@@ -128,7 +130,9 @@ def _required_sections(self, report: LintReport) -> None:
             files = [s.resolve() for s in sources if s.exists()]
             if not files or not scanned.intersection(files):
                 continue
-            titles = [title for file in files if (tree := self._parsed(file)) is not None for title in rules.headings(tree)]
+            titles = [
+                title for file in files if (tree := self._parsed(file)) is not None for title in rules.headings(tree)
+            ]
             found += rules.required_sections(doc_id, files, titles, self.config)
         report.add([self._graded(issue) for issue in found])
 
@@ -136,7 +140,11 @@ def _terminology(self, report: LintReport) -> None:
         """One spelling of each hyphenated word over every file linted together."""
         if RULE_TERMINOLOGY in self.config.disabled_rules:
             return
-        prose = [(r.file, segments(tree)) for r in report.results if r.error is None and (tree := self._parsed(r.file)) is not None]
+        prose = [
+            (r.file, segments(tree))
+            for r in report.results
+            if r.error is None and (tree := self._parsed(r.file)) is not None
+        ]
         report.add([self._graded(issue) for issue in rules.terminology(prose, self.config)])
 
     def _document_acronyms(self, report: LintReport) -> None:
@@ -241,13 +249,17 @@ def _vale(self, report: LintReport, target: Path) -> None:
         files = [result.file for result in report.results if result.error is None]
         try:
             if settings.config is not None:
-                logger.info("Using %s as it is: lint.vale rules, terms and avoid patterns are not applied", settings.config)
+                logger.info(
+                    "Using %s as it is: lint.vale rules, terms and avoid patterns are not applied", settings.config
+                )
                 ini = settings.config
             else:
                 ini = vale.build_workspace(settings, self.config, self.vale_folder()).ini
                 absent = vale.missing_packages(settings, self.vale_folder())
                 if absent:
-                    raise ConversionError(f"Vale packages not downloaded: {', '.join(absent)}. Run `py-doc lint --sync`.")
+                    raise ConversionError(
+                        f"Vale packages not downloaded: {', '.join(absent)}. Run `py-doc lint --sync`."
+                    )
             found = vale.run_vale(files, runner, ini, settings, Path.cwd())
         except vale.ValeError as exc:  # a broken run is an error on every file, never a clean result
             for result in report.results:
diff --git a/src/py_doc/lint/rules.py b/src/py_doc/lint/rules.py
index 9498b8c..04c5fbb 100644
--- a/src/py_doc/lint/rules.py
+++ b/src/py_doc/lint/rules.py
@@ -89,7 +89,9 @@ def _expands(words: list[str], acronym: str) -> bool:
     letters = iter(acronym.lower())
     if words[0][0].lower() != acronym[0].lower():
         return False
-    return all(any(letter == word[0].lower() for letter in letters) for word in words if word.lower() not in _STOP_WORDS)
+    return all(
+        any(letter == word[0].lower() for letter in letters) for word in words if word.lower() not in _STOP_WORDS
+    )
 
 
 def _definitions(text: str) -> list[tuple[str, int]]:
@@ -206,7 +208,11 @@ def image_alt(file: Path, document: n.Document, config: LintConfig) -> list[Lint
     """A picture without alt text, which a screen reader cannot describe and a caption cannot come from."""
     return [
         LintIssue(
-            file, node.line, RULE_IMAGE_ALT, "Accessibility", f"Picture '{node.url}' has no alt text.",
+            file,
+            node.line,
+            RULE_IMAGE_ALT,
+            "Accessibility",
+            f"Picture '{node.url}' has no alt text.",
             suggestion="Describe the picture between the brackets: ![What it shows](file.png)",
         )  # fmt: skip
         for node in n.walk(document)
@@ -280,7 +286,11 @@ def unclosed_fences(file: Path, document: n.Document, config: LintConfig) -> lis
     """A code fence that is never closed, so the rest of the file becomes code."""
     return [
         LintIssue(
-            file, node.line, RULE_UNCLOSED_FENCE, "Structure", "Code fence is never closed: the rest of the file is code.",
+            file,
+            node.line,
+            RULE_UNCLOSED_FENCE,
+            "Structure",
+            "Code fence is never closed: the rest of the file is code.",
             suggestion="Close it with the same fence (``` or ~~~) on a line of its own",
         )  # fmt: skip
         for node in n.walk(document)
@@ -299,7 +309,11 @@ def required_sections(doc_id: str, files: list[Path], found: list[str], config:
     have = {_bare(text) for text in found}
     return [
         LintIssue(
-            files[0], 1, RULE_REQUIRED_SECTION, "Structure", f"Document '{doc_id}' has no '{section}' section.",
+            files[0],
+            1,
+            RULE_REQUIRED_SECTION,
+            "Structure",
+            f"Document '{doc_id}' has no '{section}' section.",
             suggestion=f"Add a heading '{section}'",
         )  # fmt: skip
         for section in wanted
diff --git a/src/py_doc/lint/structure.py b/src/py_doc/lint/structure.py
index 0c73b54..a410af0 100644
--- a/src/py_doc/lint/structure.py
+++ b/src/py_doc/lint/structure.py
@@ -280,15 +280,21 @@ def _balanced(file: Path, lines: list[str], rule: StructureRule) -> list[LintIss
     issues: list[LintIssue] = []
     for number, line in live_lines(lines):
         spans = _spans(line)
-        events = [(m.start(), "open", m.group(0)) for m in rule.open_pattern.finditer(line) if not _inside(m.start(), spans)]
-        events += [(m.start(), "close", m.group(0)) for m in rule.close_pattern.finditer(line) if not _inside(m.start(), spans)]
+        events = [
+            (m.start(), "open", m.group(0)) for m in rule.open_pattern.finditer(line) if not _inside(m.start(), spans)
+        ]
+        events += [
+            (m.start(), "close", m.group(0)) for m in rule.close_pattern.finditer(line) if not _inside(m.start(), spans)
+        ]
         for _, kind, marker in sorted(events):
             if kind == "open":
                 stack.append((number, marker))
             elif stack:
                 stack.pop()
             else:
-                issues.append(_issue(rule, file, number, (rule.unmatched_close_message or rule.message).format(marker=marker)))
+                issues.append(
+                    _issue(rule, file, number, (rule.unmatched_close_message or rule.message).format(marker=marker))
+                )
     for number, marker in stack:
         issues.append(_issue(rule, file, number, (rule.unmatched_open_message or rule.message).format(marker=marker)))
     return issues
@@ -323,7 +329,9 @@ def captioned(after: int, rule: StructureRule, first: int | None = None) -> bool
         if code := _CODE.match(line):
             marker, language = code.group(1), code.group(2).lower()
             end = i + 1
-            while end < count and not (lines[end].lstrip().startswith(marker[0] * len(marker)) and not lines[end].strip(marker[0])):
+            while end < count and not (
+                lines[end].lstrip().startswith(marker[0] * len(marker)) and not lines[end].strip(marker[0])
+            ):
                 end += 1
             wanted = fenced is not None and (not fenced.languages or language in fenced.languages)
             if wanted and not captioned(end + 1, fenced, i):
diff --git a/src/py_doc/lint/vale.py b/src/py_doc/lint/vale.py
index c8ee7bf..d007ffc 100644
--- a/src/py_doc/lint/vale.py
+++ b/src/py_doc/lint/vale.py
@@ -71,7 +71,9 @@ def __init__(self, binary: str, folder: Path, base: Path) -> None:
     def run(self, argv, *, writable=False, network=False):
         command = [self.binary, *[str(a) for a in argv]]
         try:
-            done = subprocess.run(command, capture_output=True, text=True, encoding="utf-8", timeout=TIMEOUT, check=False)
+            done = subprocess.run(
+                command, capture_output=True, text=True, encoding="utf-8", timeout=TIMEOUT, check=False
+            )
         except FileNotFoundError as exc:
             raise EnvironmentProblem(f"Vale was not found at '{self.binary}'. {INSTALL_HELP}") from exc
         except subprocess.TimeoutExpired as exc:
@@ -116,7 +118,11 @@ class Workspace:
 
 
 def _rule_levels(settings: ValeSettings) -> dict[str, str]:
-    return {rule_id: ("NO" if rule.off else rule.level) for rule_id, rule in settings.rules.items() if rule.off or rule.level}
+    return {
+        rule_id: ("NO" if rule.off else rule.level)
+        for rule_id, rule in settings.rules.items()
+        if rule.off or rule.level
+    }
 
 
 def build_workspace(settings: ValeSettings, config: LintConfig, folder: Path) -> Workspace:
@@ -137,7 +143,12 @@ def put(name: str, data: dict | str) -> None:
     # DOC001 to DOC003 turned off in py-doc.yml also turn off their Vale rules.
     off = {
         stem
-        for stem, rule in (("Terms", RULE_GLOSSARY), ("Wordy", RULE_REDUNDANT), ("Redundant", RULE_REDUNDANT), ("Acronyms", RULE_ACRONYM))
+        for stem, rule in (
+            ("Terms", RULE_GLOSSARY),
+            ("Wordy", RULE_REDUNDANT),
+            ("Redundant", RULE_REDUNDANT),
+            ("Acronyms", RULE_ACRONYM),
+        )
         if rule in config.disabled_rules
     }
     for name, text in _bundled():
@@ -249,7 +260,9 @@ def check_version(runner: Runner) -> tuple[int, ...]:
         raise ValeError(f"Vale did not report its version: {(out + err).strip() or 'no output'}")
     if version < MIN_VERSION:
         needed = ".".join(map(str, MIN_VERSION))
-        raise EnvironmentProblem(f"Vale {'.'.join(map(str, version))} is too old. py-doc needs {needed} or newer. {INSTALL_HELP}")
+        raise EnvironmentProblem(
+            f"Vale {'.'.join(map(str, version))} is too old. py-doc needs {needed} or newer. {INSTALL_HELP}"
+        )
     return version
 
 
@@ -291,15 +304,11 @@ def parse_output(text: str, files: list[Path]) -> list[LintIssue]:
             suggestion = str(params[0]) if action.get("Name") == "replace" and params else None
             span = alert.get("Span") or []
             column = int(span[0]) if span else None
-            issues.append(
-                LintIssue(path, line, check, check.split(".")[0], message, severity, suggestion, column)
-            )
+            issues.append(LintIssue(path, line, check, check.split(".")[0], message, severity, suggestion, column))
     return issues
 
 
-def run_vale(
-    files: list[Path], runner: Runner, ini: Path, settings: ValeSettings, base: Path
-) -> list[LintIssue]:
+def run_vale(files: list[Path], runner: Runner, ini: Path, settings: ValeSettings, base: Path) -> list[LintIssue]:
     """Run Vale on ``files``. Raises :class:`ValeError` when it fails, so a broken run is never a clean one."""
     files = selected([f.resolve() for f in files], settings, base)
     if not files:
diff --git a/src/py_doc/lint/vale_config.py b/src/py_doc/lint/vale_config.py
index 9412d44..651fd2d 100644
--- a/src/py_doc/lint/vale_config.py
+++ b/src/py_doc/lint/vale_config.py
@@ -148,7 +148,9 @@ def _merge(settings: ValeSettings, data: dict, where: str, root: Path, depth: in
         settings.min_alert_level = _level(data["min_alert_level"], f"{where}.min_alert_level")
     if "packages" in data:
         packages = data["packages"]
-        if not isinstance(packages, list) or not all(isinstance(p, str) and re.fullmatch(r"[\w.-]+", p) for p in packages):
+        if not isinstance(packages, list) or not all(
+            isinstance(p, str) and re.fullmatch(r"[\w.-]+", p) for p in packages
+        ):
             raise ValeConfigError(f"{where}.packages must be a list of package names")
         settings.packages = list(dict.fromkeys([*settings.packages, *packages]))
     if "spelling" in data:
diff --git a/src/py_doc/markdown/parser.py b/src/py_doc/markdown/parser.py
index 9432639..ef9fe84 100644
--- a/src/py_doc/markdown/parser.py
+++ b/src/py_doc/markdown/parser.py
@@ -218,7 +218,9 @@ def _inline_run(
                 alt_nodes, _ = self._inline_run(token.children or [], 0, None, [line])
                 title = token.attrs.get("title")
                 nodes.append(
-                    n.Image(line, str(token.attrs.get("src", "")), str(title) if title else None, n.plain_text(alt_nodes))
+                    n.Image(
+                        line, str(token.attrs.get("src", "")), str(title) if title else None, n.plain_text(alt_nodes)
+                    )
                 )
             else:
                 raise ParseError(f"Unsupported inline Markdown '{kind}' at line {line}")
diff --git a/src/py_doc/migrate.py b/src/py_doc/migrate.py
index b67bef0..b18dfbb 100644
--- a/src/py_doc/migrate.py
+++ b/src/py_doc/migrate.py
@@ -178,9 +178,18 @@ def rel(path: Path) -> str:
         for key, reason in _UNUSED_CLI.items():
             if cli.get(key):
                 result.note("warning", yaml_path, f"cli.{key} was left out: {reason}")
-        built = {"docx": flags["emit-docx"], "pptx": flags["emit-pptx"], "pdf": flags["emit-pdf"], "html": flags["emit-html"]}
+        built = {
+            "docx": flags["emit-docx"],
+            "pptx": flags["emit-pptx"],
+            "pdf": flags["emit-pdf"],
+            "html": flags["emit-html"],
+        }
         if not any(built.values()):
-            result.note("warning", yaml_path, "createdocs built no Word, PowerPoint, PDF or HTML file for this document. py-doc builds a Word file")
+            result.note(
+                "warning",
+                yaml_path,
+                "createdocs built no Word, PowerPoint, PDF or HTML file for this document. py-doc builds a Word file",
+            )
             built["docx"] = True
         outputs: dict[str, Any] = {}
         for fmt, wanted in built.items():
diff --git a/src/py_doc/naming.py b/src/py_doc/naming.py
index 0eaaf21..c27728e 100644
--- a/src/py_doc/naming.py
+++ b/src/py_doc/naming.py
@@ -53,7 +53,9 @@ def status_template(base: Path | None, status: str | None) -> Path | None:
         if candidate.is_file():
             logger.info(f"Using the template for status '{status}': {candidate}")
             return candidate
-    logger.info(f"No template for status '{status}' (looked for {', '.join(c.name for c in candidates)}), so {base} is used")
+    logger.info(
+        f"No template for status '{status}' (looked for {', '.join(c.name for c in candidates)}), so {base} is used"
+    )
     return base
 
 
@@ -68,7 +70,9 @@ def check_name_pattern(pattern: str, where: str) -> None:
     """Raise ValueError for a pattern with an unknown field or a stray brace."""
     unknown = [field for field in _FIELD.findall(pattern) if field not in FIELDS]
     if unknown:
-        raise ValueError(f"{where} uses unknown field {{{unknown[0]}}}. Fields: {', '.join('{' + f + '}' for f in FIELDS)}")
+        raise ValueError(
+            f"{where} uses unknown field {{{unknown[0]}}}. Fields: {', '.join('{' + f + '}' for f in FIELDS)}"
+        )
     if "{" in _FIELD.sub("", pattern) or "}" in _FIELD.sub("", pattern):
         raise ValueError(f"{where} has a brace that is not part of a field")
 
diff --git a/src/py_doc/new.py b/src/py_doc/new.py
index 8a00deb..b8f50a7 100644
--- a/src/py_doc/new.py
+++ b/src/py_doc/new.py
@@ -45,7 +45,11 @@
 FORMATS = {"docx": "Word", "pptx": "PowerPoint"}
 _SEQUENCE = re.compile(r"(\d+)$")
 _CODE = re.compile(r"^[A-Za-z0-9]*$")
-LISTS = {"prefixes": "G460, G470", "types": "TN, OV, SP", "classifications": "Confidential, Internal"}  # with an example
+LISTS = {
+    "prefixes": "G460, G470",
+    "types": "TN, OV, SP",
+    "classifications": "Confidential, Internal",
+}  # with an example
 
 
 class NewError(Exception):
@@ -165,7 +169,15 @@ def build_file(meta: dict[str, str], output: str, fmt: str, source: str) -> str:
     lines += ["", "cli:"]
     if fmt == "docx":
         lines.append("  emit-docx: true")
-    lines += [f"  output: {output}", f"  # template: path/to/Template.{fmt}", "", "entries:", f"  - file: {source}", "    heading_offset: 0", ""]
+    lines += [
+        f"  output: {output}",
+        f"  # template: path/to/Template.{fmt}",
+        "",
+        "entries:",
+        f"  - file: {source}",
+        "    heading_offset: 0",
+        "",
+    ]
     return "\n".join(lines)
 
 
@@ -190,19 +202,37 @@ def build_parser() -> argparse.ArgumentParser:
         "markdown", nargs="?", type=Path, metavar="FILE.md",
         help="An existing Markdown file to number: its build file is written beside it, and the file is not changed",
     )  # fmt: skip
-    parser.add_argument("--title", help="The document title (needed; default for FILE.md: its front matter title or first heading)")
-    parser.add_argument("--type", dest="kind", help="The type code in the number, such as TN: one of the register's types when it lists them, else anything or empty")
+    parser.add_argument(
+        "--title", help="The document title (needed; default for FILE.md: its front matter title or first heading)"
+    )
+    parser.add_argument(
+        "--type",
+        dest="kind",
+        help="The type code in the number, such as TN: one of the register's types when it lists them, else anything or empty",
+    )
     parser.add_argument("--format", choices=sorted(FORMATS), help="Word (docx) or PowerPoint (pptx). Default: docx")
     parser.add_argument("--author", help="Default: git config user.name")
-    parser.add_argument("--classification", help="Such as Confidential: one of the register's classifications when it lists them, else anything")
+    parser.add_argument(
+        "--classification",
+        help="Such as Confidential: one of the register's classifications when it lists them, else anything",
+    )
     parser.add_argument("--description", help="One sentence on what the document covers")
     parser.add_argument(
         "--prefix",
         help="The number prefix, such as G460 (default: the register's prefix). One of its prefixes when it lists them. "
         "When the register is made, it becomes its default",
     )
-    parser.add_argument("--scan", action="store_true", help="Add the legacy build files not in the register yet (clashes included), and make no document")
-    parser.add_argument("--start", type=int, metavar="N", help="New numbers begin at N, skipping any taken (kept in the register), and make no document")
+    parser.add_argument(
+        "--scan",
+        action="store_true",
+        help="Add the legacy build files not in the register yet (clashes included), and make no document",
+    )
+    parser.add_argument(
+        "--start",
+        type=int,
+        metavar="N",
+        help="New numbers begin at N, skipping any taken (kept in the register), and make no document",
+    )
     parser.add_argument("-y", "--yes", action="store_true", help="Ask nothing: take the defaults for what is not given")
     noise = parser.add_mutually_exclusive_group()
     noise.add_argument("-q", "--quiet", action="store_true", help="Only show warnings and errors")
@@ -279,7 +309,12 @@ def extra(key: str) -> str:
         return str(meta.extra.get(key) or "").strip()
 
     return ExistingMarkdown(
-        path, meta.title or first_heading(body) or "", meta.author or "", meta.version or "", extra("classification"), extra("description")
+        path,
+        meta.title or first_heading(body) or "",
+        meta.author or "",
+        meta.version or "",
+        extra("classification"),
+        extra("description"),
     )
 
 
@@ -292,7 +327,9 @@ def _not_registered(markdown: Path, register: Register, root: Path) -> None:
                 raise NewError(f"{markdown.name} is already a source of {entry.file}, number {entry.number}")
 
 
-def make(folder: Path, args: argparse.Namespace, ask: Callable[[str], str] | None, today: datetime.date) -> tuple[list[Path], Register, bool]:
+def make(
+    folder: Path, args: argparse.Namespace, ask: Callable[[str], str] | None, today: datetime.date
+) -> tuple[list[Path], Register, bool]:
     """Write the build file and its Markdown in ``folder`` and record the number. Returns what was written.
 
     With ``args.markdown``, the build file goes beside that file and names it; the Markdown is not written.
@@ -330,7 +367,11 @@ def make(folder: Path, args: argparse.Namespace, ask: Callable[[str], str] | Non
         raise NewError(f"'{fmt}' is not docx or pptx")
     author = value("Author", args.author, (existing.author if existing else "") or _git_name()).strip()
     classification = pick(
-        "Classification", args.classification, existing.classification if existing else "", allowed.get("classifications"), "--classification"
+        "Classification",
+        args.classification,
+        existing.classification if existing else "",
+        allowed.get("classifications"),
+        "--classification",
     )
     description = value("Description", args.description, existing.description if existing else "").strip()
 
@@ -399,7 +440,9 @@ def run_new(argv: Sequence[str] | None = None) -> int:
         for entry in added:
             print(f"added     {entry.number}  {entry.file}")
         _report_clashes(register)
-        print(f"register  {os.path.relpath(register.path)}: {len(register.entries or [])} number(s), the next ends in {register.next_number('').rsplit('-', 1)[-1]}")
+        print(
+            f"register  {os.path.relpath(register.path)}: {len(register.entries or [])} number(s), the next ends in {register.next_number('').rsplit('-', 1)[-1]}"
+        )
         return 0
     try:
         written, register, created = make(Path.cwd(), args, ask, datetime.date.today())
@@ -416,5 +459,7 @@ def run_new(argv: Sequence[str] | None = None) -> int:
     for path in written:
         print(f"written   {Path(os.path.relpath(path))}")
     print(f"number    {register.entries[-1].number}, recorded in {shown}")
-    print(f"\nNext: commit {REGISTER} with the new files, then `py-doc build --legacy {Path(os.path.relpath(written[0]))}`")
+    print(
+        f"\nNext: commit {REGISTER} with the new files, then `py-doc build --legacy {Path(os.path.relpath(written[0]))}`"
+    )
     return 0
diff --git a/src/py_doc/pandoc/docx_finish.py b/src/py_doc/pandoc/docx_finish.py
index e85d1ab..be7da02 100644
--- a/src/py_doc/pandoc/docx_finish.py
+++ b/src/py_doc/pandoc/docx_finish.py
@@ -66,7 +66,9 @@ def finish_docx(body_path: Path, template: Path | None, metadata: Metadata, opti
             value = text(read(metadata))
             replacements[prefix + name] = value
             if not value and prefix + name in present:
-                logger.warning(f"The template has {prefix + name}, but the document has no {name.lower().replace('-', ' ')}")
+                logger.warning(
+                    f"The template has {prefix + name}, but the document has no {name.lower().replace('-', ' ')}"
+                )
         post.replace_placeholders(base, replacements)
         index = post.find_and_remove_marker(base, options.get("marker", DEFAULT_MARKER))
         body = Document(str(body_path))
@@ -78,7 +80,11 @@ def finish_docx(body_path: Path, template: Path | None, metadata: Metadata, opti
             marker = options.get("marker", DEFAULT_MARKER)
             kept = [p.text.strip() for p in base.paragraphs if p.text.strip()]
             if kept or base.tables:  # template text in a deliverable must never pass unnoticed (#60)
-                shown = f"'{kept[0][:60]}'" + (f" and {len(kept) - 1} more paragraph(s)" if len(kept) > 1 else "") if kept else "a table"
+                shown = (
+                    f"'{kept[0][:60]}'" + (f" and {len(kept) - 1} more paragraph(s)" if len(kept) > 1 else "")
+                    if kept
+                    else "a table"
+                )
                 logger.warning(
                     f"The template {template.name} has text in its body ({shown}) and no {marker} line, so that text "
                     f"comes before the document. Put {marker} where the document goes, or remove the text"
diff --git a/src/py_doc/pandoc/docx_post.py b/src/py_doc/pandoc/docx_post.py
index 921ee0f..3fd88cc 100644
--- a/src/py_doc/pandoc/docx_post.py
+++ b/src/py_doc/pandoc/docx_post.py
@@ -13,6 +13,7 @@
 * Core property update.
 * TOC update flag.
 """
+
 from __future__ import annotations
 
 import copy
@@ -39,18 +40,19 @@ def snippet(text: str, n: int = 80) -> str:
     """A single-line preview of text for messages."""
     return (text or "").replace("\n", " ").replace("\r", " ")[:n]
 
+
 # ---------------------------------------------------------------------------
 # Orientation markers
 # ---------------------------------------------------------------------------
 
 MARKERS_LANDSCAPE = {"[[LANDSCAPE]]", "__LANDSCAPE__", "__LANDSCAPE_START__"}
-MARKERS_PORTRAIT  = {"[[PORTRAIT]]",  "__PORTRAIT__",  "__LANDSCAPE_END__"}
+MARKERS_PORTRAIT = {"[[PORTRAIT]]", "__PORTRAIT__", "__LANDSCAPE_END__"}
 
 # ---------------------------------------------------------------------------
 # Style / caption marker patterns
 # ---------------------------------------------------------------------------
 
-STYLE_PATTERN   = re.compile(r"\[\[STYLE:(?P<style>[A-Za-z0-9 _-]+)\]\]")
+STYLE_PATTERN = re.compile(r"\[\[STYLE:(?P<style>[A-Za-z0-9 _-]+)\]\]")
 CAPTION_PATTERN = re.compile(r"\[\[CAPTION:(?P<label>[A-Za-z0-9 _-]+)\]\]")
 
 # ---------------------------------------------------------------------------
@@ -77,8 +79,8 @@ def find_and_remove_marker(doc: Document, marker: str = CONTENT_MARKER) -> int |
         raise ValueError(f"Marker {marker!r} found {len(hits)} times — expected exactly one")
 
     marker_para = hits[0]
-    body        = doc._element.body
-    index       = body.index(marker_para._p)
+    body = doc._element.body
+    index = body.index(marker_para._p)
     body.remove(marker_para._p)
     return index
 
@@ -87,8 +89,9 @@ def find_and_remove_marker(doc: Document, marker: str = CONTENT_MARKER) -> int |
 # Internal XML helpers
 # ---------------------------------------------------------------------------
 
+
 def _get_or_add_body_sectPr(doc: Document):
-    body   = doc._element.body
+    body = doc._element.body
     sectPr = body.sectPr
     if sectPr is None:
         sectPr = OxmlElement("w:sectPr")
@@ -119,16 +122,16 @@ def _insert_seq_field(paragraph, label: str, number: int) -> None:
     paragraph.style = "Caption"
     paragraph.add_run(f"{label} ")
     run = paragraph.add_run()
-    fld_begin             = OxmlElement("w:fldChar")
+    fld_begin = OxmlElement("w:fldChar")
     fld_begin.set(qn("w:fldCharType"), "begin")
-    instr                 = OxmlElement("w:instrText")
-    instr.text            = f"SEQ {label} \\* ARABIC"
-    fld_sep               = OxmlElement("w:fldChar")
+    instr = OxmlElement("w:instrText")
+    instr.text = f"SEQ {label} \\* ARABIC"
+    fld_sep = OxmlElement("w:fldChar")
     fld_sep.set(qn("w:fldCharType"), "separate")
-    fld_end               = OxmlElement("w:fldChar")
+    fld_end = OxmlElement("w:fldChar")
     fld_end.set(qn("w:fldCharType"), "end")
-    shown                 = OxmlElement("w:t")
-    shown.text            = str(number)
+    shown = OxmlElement("w:t")
+    shown.text = str(number)
     run._r.extend([fld_begin, instr, fld_sep, shown, fld_end])
     paragraph.add_run(": ")
 
@@ -137,6 +140,7 @@ def _insert_seq_field(paragraph, label: str, number: int) -> None:
 # Section break injection
 # ---------------------------------------------------------------------------
 
+
 def insert_section_break_at(paragraph, orientation: str, doc: Document) -> None:
     """
     Inject a ``nextPage`` section break at *paragraph* and set the page size
@@ -150,7 +154,7 @@ def insert_section_break_at(paragraph, orientation: str, doc: Document) -> None:
     """
     body_sectPr = _get_or_add_body_sectPr(doc)
 
-    pPr        = paragraph._p.get_or_add_pPr()
+    pPr = paragraph._p.get_or_add_pPr()
     para_sectPr = copy.deepcopy(body_sectPr)
 
     type_elem = para_sectPr.find(qn("w:type"))
@@ -184,6 +188,7 @@ def insert_section_break_at(paragraph, orientation: str, doc: Document) -> None:
 # Orientation marker pass
 # ---------------------------------------------------------------------------
 
+
 def apply_orientation_markers(doc: Document) -> None:
     """
     Find orientation marker paragraphs and replace each with a Word section
@@ -193,7 +198,7 @@ def apply_orientation_markers(doc: Document) -> None:
 
     paragraphs = list(doc.paragraphs)
     landscape_hits = [i for i, p in enumerate(paragraphs) if (p.text or "").strip() in MARKERS_LANDSCAPE]
-    portrait_hits  = [i for i, p in enumerate(paragraphs) if (p.text or "").strip() in MARKERS_PORTRAIT]
+    portrait_hits = [i for i, p in enumerate(paragraphs) if (p.text or "").strip() in MARKERS_PORTRAIT]
 
     log.debug("Landscape markers at: %s", landscape_hits)
     log.debug("Portrait markers at:  %s", portrait_hits)
@@ -214,8 +219,7 @@ def apply_orientation_markers(doc: Document) -> None:
             log.debug("Applied PORTRAIT break")
 
     remaining = [
-        i for i, p in enumerate(doc.paragraphs)
-        if (p.text or "").strip() in (MARKERS_LANDSCAPE | MARKERS_PORTRAIT)
+        i for i, p in enumerate(doc.paragraphs) if (p.text or "").strip() in (MARKERS_LANDSCAPE | MARKERS_PORTRAIT)
     ]
     if remaining:
         log.warning("Orientation markers still present after processing at: %s", remaining)
@@ -227,6 +231,7 @@ def apply_orientation_markers(doc: Document) -> None:
 # Landscape image rescaling
 # ---------------------------------------------------------------------------
 
+
 def rescale_landscape_images(doc: Document) -> None:
     """
     Expand images inside landscape sections to full landscape text width.
@@ -272,32 +277,28 @@ def rescale_landscape_images(doc: Document) -> None:
         if section.orientation != WD_ORIENT.LANDSCAPE:
             continue  # portrait section — leave this image alone
 
-        usable_width = (
-            section.page_width - section.left_margin - section.right_margin
-        )
+        usable_width = section.page_width - section.left_margin - section.right_margin
         if shape.width < usable_width:
             ratio = usable_width / float(shape.width)
             shape.height = int(shape.height * ratio)
-            shape.width  = usable_width
+            shape.width = usable_width
 
         # Centre the paragraph
-        para_obj = next(
-            (p for p in doc.paragraphs if p._p is containing_p), None
-        )
+        para_obj = next((p for p in doc.paragraphs if p._p is containing_p), None)
         if para_obj is not None:
             para_obj.alignment = WD_ALIGN_PARAGRAPH.CENTER
 
         rescaled += 1
 
     if rescaled:
-        log.info("rescale_landscape_images: %d image(s) expanded to landscape width",
-                 rescaled)
+        log.info("rescale_landscape_images: %d image(s) expanded to landscape width", rescaled)
 
 
 # ---------------------------------------------------------------------------
 # Placeholder replacement
 # ---------------------------------------------------------------------------
 
+
 def replace_placeholders(doc: Document, replacements: dict[str, str]) -> None:
     """
     Replace template placeholder strings throughout the document.
@@ -345,10 +346,10 @@ def _replace_table(table):
 
     # --- header / footer XML walk ---------------------------------------
 
-    _W_P        = qn("w:p")
-    _W_R        = qn("w:r")
-    _W_T        = qn("w:t")
-    _XML_SPACE  = "{http://www.w3.org/XML/1998/namespace}space"
+    _W_P = qn("w:p")
+    _W_R = qn("w:r")
+    _W_T = qn("w:t")
+    _XML_SPACE = "{http://www.w3.org/XML/1998/namespace}space"
 
     def _replace_hf(hf_element):
         # Break-like elements split a paragraph into independent visual
@@ -360,8 +361,15 @@ def _replace_hf(hf_element):
         # several runs within a segment (e.g. spell-check), which is why
         # each segment is still concatenated before replacing, rather than
         # replacing node-by-node.
-        _BREAK_TAGS = {qn("w:tab"), qn("w:br"), qn("w:cr"), qn("w:drawing"),
-                       qn("w:object"), qn("w:pict"), qn("w:noBreakHyphen")}
+        _BREAK_TAGS = {
+            qn("w:tab"),
+            qn("w:br"),
+            qn("w:cr"),
+            qn("w:drawing"),
+            qn("w:object"),
+            qn("w:pict"),
+            qn("w:noBreakHyphen"),
+        }
 
         def _replace_segment(segment):
             if not segment:
@@ -416,6 +424,7 @@ def find_placeholders(doc: Document, prefix: str) -> set[str]:
 # Explicit style / caption markers
 # ---------------------------------------------------------------------------
 
+
 def _starts_with_marker(p) -> bool:
     """The paragraph begins with a marker in plain text. One shown as inline code (`[[STYLE:Name]]`, in pandoc's
     ``Verbatim Char`` style) or mentioned within a sentence is text, and is left as it is."""
@@ -450,10 +459,10 @@ def apply_explicit_styles(doc: Document) -> None:
 
         cap_m = CAPTION_PATTERN.search(raw)
         if cap_m:
-            label   = cap_m.group("label").strip()
+            label = cap_m.group("label").strip()
             cleaned = CAPTION_PATTERN.sub("", raw).strip()
             counts[label] = counts.get(label, 0) + 1
-            p.text  = ""
+            p.text = ""
             _insert_seq_field(p, label, counts[label])
             if cleaned:
                 p.add_run(cleaned)
@@ -463,7 +472,7 @@ def apply_explicit_styles(doc: Document) -> None:
         sty_m = STYLE_PATTERN.search(raw)
         if sty_m:
             style_name = sty_m.group("style").strip()
-            p.text     = STYLE_PATTERN.sub("", raw).strip()
+            p.text = STYLE_PATTERN.sub("", raw).strip()
             try:
                 p.style = style_name
                 log.debug("Style '%s' applied", style_name)
@@ -471,8 +480,11 @@ def apply_explicit_styles(doc: Document) -> None:
                 missing[style_name] = missing.get(style_name, 0) + 1
 
     if missing:
-        log.warning("The document has no style %s, so %s left as Normal", ", ".join(f"'{n}'" for n in missing),
-                    "those paragraphs are" if sum(missing.values()) > 1 else "that paragraph is")
+        log.warning(
+            "The document has no style %s, so %s left as Normal",
+            ", ".join(f"'{n}'" for n in missing),
+            "those paragraphs are" if sum(missing.values()) > 1 else "that paragraph is",
+        )
     log.debug("apply_explicit_styles: done")
 
 
@@ -480,12 +492,13 @@ def apply_explicit_styles(doc: Document) -> None:
 # Table formatting
 # ---------------------------------------------------------------------------
 
+
 def format_all_tables(
     doc: Document,
-    style_name: str       = "Table Grid",
-    repeat_header: bool   = True,
+    style_name: str = "Table Grid",
+    repeat_header: bool = True,
     prevent_row_split: bool = True,
-    autofit: bool         = True,
+    autofit: bool = True,
 ) -> None:
     """
     Apply a consistent appearance to every table in *doc*.
@@ -516,7 +529,7 @@ def format_all_tables(
 
         tbl.alignment = WD_TABLE_ALIGNMENT.CENTER
         tblPr = tbl._tbl.tblPr
-        tblW  = tblPr.find(qn("w:tblW"))
+        tblW = tblPr.find(qn("w:tblW"))
         if tblW is None:
             tblW = OxmlElement("w:tblW")
             tblPr.append(tblW)
@@ -531,19 +544,19 @@ def format_all_tables(
             for row in tbl.rows:
                 for cell in row.cells:
                     tcPr = cell._tc.get_or_add_tcPr()
-                    tcW  = tcPr.find(qn("w:tcW"))
+                    tcW = tcPr.find(qn("w:tcW"))
                     if tcW is not None:
                         tcPr.remove(tcW)
 
         if repeat_header and tbl.rows:
-            hdr  = tbl.rows[0]
+            hdr = tbl.rows[0]
             trPr = hdr._tr.get_or_add_trPr()
             if trPr.find(qn("w:tblHeader")) is None:
                 trPr.append(OxmlElement("w:tblHeader"))
             for cell in hdr.cells:
                 for p in cell.paragraphs:
                     p.paragraph_format.keep_with_next = True
-                    p.paragraph_format.keep_together  = True
+                    p.paragraph_format.keep_together = True
                     # Direct run formatting, not reliance on the table
                     # style's conditional "first row" formatting alone:
                     # whatever paragraph style Pandoc assigned to this cell
@@ -569,6 +582,7 @@ def format_all_tables(
 # Layout fixes
 # ---------------------------------------------------------------------------
 
+
 def _text_width_for_shape(shape, doc: Document) -> int:
     """
     Return the text-area width (EMU) of the section containing *shape*.
@@ -617,8 +631,8 @@ def apply_layout_fixes(doc: Document, max_image_height_cm: float = 20.0) -> None
     - Keep images with their captions.
     """
     log.debug("apply_layout_fixes: start")
-    max_h   = Cm(max_image_height_cm)
-    scaled  = 0
+    max_h = Cm(max_image_height_cm)
+    scaled = 0
     clamped = 0
 
     for shape in doc.inline_shapes:
@@ -631,26 +645,25 @@ def apply_layout_fixes(doc: Document, max_image_height_cm: float = 20.0) -> None
             # 1. Scale width to text area if needed
             text_w = _text_width_for_shape(shape, doc)
             if w > text_w:
-                ratio        = text_w / float(w)
-                shape.width  = text_w
+                ratio = text_w / float(w)
+                shape.width = text_w
                 shape.height = int(h * ratio)
-                w, h         = shape.width, shape.height
-                scaled      += 1
+                w, h = shape.width, shape.height
+                scaled += 1
 
             # 2. Clamp height
             if shape.height > max_h:
-                ratio        = max_h / float(shape.height)
-                shape.width  = int(shape.width * ratio)
+                ratio = max_h / float(shape.height)
+                shape.width = int(shape.width * ratio)
                 shape.height = int(max_h)
-                clamped     += 1
+                clamped += 1
 
         except Exception as exc:
             log.debug("Image resize skipped: %s", exc)
             continue
 
     if scaled or clamped:
-        log.info("apply_layout_fixes: %d image(s) width-scaled, %d height-clamped",
-                 scaled, clamped)
+        log.info("apply_layout_fixes: %d image(s) width-scaled, %d height-clamped", scaled, clamped)
 
     def _has_drawing(para) -> bool:
         return any(r._element.xpath(".//w:drawing") for r in para.runs)
@@ -659,10 +672,10 @@ def _has_drawing(para) -> bool:
         name = (p.style.name or "").lower()
         if name.startswith("heading"):
             p.paragraph_format.keep_with_next = True
-            p.paragraph_format.keep_together  = True
+            p.paragraph_format.keep_together = True
         if _has_drawing(p):
             p.paragraph_format.keep_with_next = True
-            p.paragraph_format.keep_together  = True
+            p.paragraph_format.keep_together = True
             p.alignment = WD_ALIGN_PARAGRAPH.CENTER
         if name == "caption" or (p.text or "").strip().lower().startswith(("figure ", "fig. ")):
             p.paragraph_format.keep_together = True
@@ -776,21 +789,22 @@ def _purge_mismatched_core_props(doc: Document, local_names: tuple[str, ...]) ->
         if qname.localname in local_names and qname.namespace != _CORE_PROPS_NS:
             log.warning(
                 "Removing malformed <%s> core property (wrong namespace: %s)",
-                qname.localname, qname.namespace,
+                qname.localname,
+                qname.namespace,
             )
             root.remove(child)
 
 
 def update_core_properties(
     doc: Document,
-    title:           str,
-    author:          str,
-    description:     str,
-    version:         str,
+    title: str,
+    author: str,
+    description: str,
+    version: str,
     document_number: str,
-    subject:         str = "",
-    keywords:        str = "",
-    category:        str = "",
+    subject: str = "",
+    keywords: str = "",
+    category: str = "",
 ) -> None:
     """Update DOCX core (document information) properties."""
     _purge_mismatched_core_props(doc, ("keywords", "category"))
@@ -802,15 +816,16 @@ def _set_capped(attr: str, value: str) -> None:
         if not value:
             return
         if len(value) > MAX_LEN:
-            log.warning("The document property '%s' is longer than Word allows (%d characters), so it was cut",
-                        attr, MAX_LEN)
-            value = value[:MAX_LEN - 1] + "…"
+            log.warning(
+                "The document property '%s' is longer than Word allows (%d characters), so it was cut", attr, MAX_LEN
+            )
+            value = value[: MAX_LEN - 1] + "…"
         setattr(props, attr, value)
 
     _set_capped("title", title)
     _set_capped("author", author)
     with _correct_cp_namespace():
-        _set_capped("subject",  subject)
+        _set_capped("subject", subject)
         _set_capped("keywords", keywords)
         _set_capped("category", category)
 
@@ -828,17 +843,18 @@ def _set_capped(attr: str, value: str) -> None:
     comments = " ".join(" | ".join(parts).split())
     if len(comments) > MAX_LEN:
         log.warning("The document comments are longer than Word allows (%d characters), so they were cut", MAX_LEN)
-        comments = comments[:MAX_LEN - 1] + "…"
+        comments = comments[: MAX_LEN - 1] + "…"
     try:
         props.comments = comments
     except ValueError:
-        props.comments = comments[:MAX_LEN - 1] + "…"
+        props.comments = comments[: MAX_LEN - 1] + "…"
 
 
 # ---------------------------------------------------------------------------
 # TOC / trailing helpers
 # ---------------------------------------------------------------------------
 
+
 def mark_for_toc_update(doc: Document) -> None:
     """
     Add ``<w:updateFields w:val="true"/>`` to the final section so Word
@@ -856,8 +872,10 @@ def clean_trailing_pagebreak(doc: Document) -> None:
     """Remove the trailing blank paragraph commonly left after the TOC. A paragraph with a picture or field is kept."""
     if len(doc.paragraphs) > 1:
         last_p = doc.paragraphs[-1]
-        holds = last_p._element.xpath(".//w:drawing | .//w:pict | .//w:fldChar | .//w:fldSimple | .//w:sectPr | .//w:br")
+        holds = last_p._element.xpath(
+            ".//w:drawing | .//w:pict | .//w:fldChar | .//w:fldSimple | .//w:sectPr | .//w:br"
+        )
         if not last_p.text.strip() and not holds:
             parent = last_p._element.getparent()
             if parent is not None:
-                parent.remove(last_p._element)
\ No newline at end of file
+                parent.remove(last_p._element)
diff --git a/src/py_doc/pandoc/engine.py b/src/py_doc/pandoc/engine.py
index 8dc6c7f..5e08334 100644
--- a/src/py_doc/pandoc/engine.py
+++ b/src/py_doc/pandoc/engine.py
@@ -85,8 +85,16 @@ def _metadata_file(metadata: Metadata, fmt: str, markdown: str) -> dict[str, Any
 
 _OFFICE = "application/vnd.openxmlformats-officedocument"
 _TEMPLATE_TYPES = {  # template file type -> (its content type, the document one, the document suffix)
-    ".dotx": (f"{_OFFICE}.wordprocessingml.template.main+xml", f"{_OFFICE}.wordprocessingml.document.main+xml", ".docx"),
-    ".potx": (f"{_OFFICE}.presentationml.template.main+xml", f"{_OFFICE}.presentationml.presentation.main+xml", ".pptx"),
+    ".dotx": (
+        f"{_OFFICE}.wordprocessingml.template.main+xml",
+        f"{_OFFICE}.wordprocessingml.document.main+xml",
+        ".docx",
+    ),
+    ".potx": (
+        f"{_OFFICE}.presentationml.template.main+xml",
+        f"{_OFFICE}.presentationml.presentation.main+xml",
+        ".pptx",
+    ),
 }
 
 
@@ -169,7 +177,10 @@ def _command(job: PandocJob, runtime: Runtime, work: Path, reference: Path | Non
             argv.append("--toc")
     else:  # pdf
         argv += ["--pdf-engine=xelatex"]
-        argv += ["--template", job.template if job.template is not None else _required(RESOURCES / "latex_template.tex", "LaTeX template")]
+        argv += [
+            "--template",
+            job.template if job.template is not None else _required(RESOURCES / "latex_template.tex", "LaTeX template"),
+        ]
         if options.get("toc", True):
             argv.append("--toc")
     if fmt in ("pdf", "html") and options.get("number_sections", False):
@@ -200,7 +211,9 @@ def convert(runtime: Runtime, job: PandocJob) -> Path:
                         f"The template {job.template.name} has no style {', '.join(missing)}, so callouts of "
                         "those kinds are plain paragraphs. Add a paragraph style with that name to give them a box"
                     )
-        (work / "metadata.yaml").write_text(yaml.safe_dump(metadata, allow_unicode=True, sort_keys=False), encoding="utf-8")
+        (work / "metadata.yaml").write_text(
+            yaml.safe_dump(metadata, allow_unicode=True, sort_keys=False), encoding="utf-8"
+        )
         argv, mounts = _command(job, runtime, work, reference)
         result = runtime.run(argv, mounts=mounts, workdir=work, timeout=TIMEOUT)
         for line in result.stderr.splitlines():
diff --git a/src/py_doc/pandoc/pptx_finish.py b/src/py_doc/pandoc/pptx_finish.py
index ca81003..edd524b 100644
--- a/src/py_doc/pandoc/pptx_finish.py
+++ b/src/py_doc/pandoc/pptx_finish.py
@@ -66,7 +66,9 @@ def ensure_fntdata_content_type(path: Path) -> None:
         types = zin.read(name).decode("utf-8")
         if 'Extension="fntdata"' in types:
             return
-        types = types.replace("</Types>", '<Default Extension="fntdata" ContentType="application/x-fontdata"/></Types>', 1)
+        types = types.replace(
+            "</Types>", '<Default Extension="fntdata" ContentType="application/x-fontdata"/></Types>', 1
+        )
         temporary = path.with_name(path.name + ".tmp")
         with zipfile.ZipFile(temporary, "w", zipfile.ZIP_DEFLATED) as zout:
             for item in zin.infolist():
@@ -140,7 +142,9 @@ def finish_pptx(path: Path, metadata: Metadata, options: dict[str, Any]) -> None
             without_footer += 1
         lines = _lines(slide)
         if lines > LINES_PER_SLIDE:
-            logger.warning(f"Slide {number} has {lines} lines, which is likely too many to read. Split it with another heading")
+            logger.warning(
+                f"Slide {number} has {lines} lines, which is likely too many to read. Split it with another heading"
+            )
     if without_footer:
         logger.warning(f"The layout of {without_footer} slide(s) has no footer placeholder, so they have no footer")
     presentation.save(str(path))
diff --git a/src/py_doc/pandoc/reference.py b/src/py_doc/pandoc/reference.py
index c4af9b7..aafbe8d 100644
--- a/src/py_doc/pandoc/reference.py
+++ b/src/py_doc/pandoc/reference.py
@@ -57,7 +57,7 @@ def add_styles(document) -> None:
         properties = style.element.get_or_add_pPr()
         properties.append(
             parse_xml(
-                f'<w:pBdr {nsdecls("w")}>'
+                f"<w:pBdr {nsdecls('w')}>"
                 f'<w:top w:val="single" w:sz="4" w:space="4" w:color="{fill}"/>'
                 f'<w:left w:val="single" w:sz="36" w:space="6" w:color="{edge}"/>'
                 f'<w:bottom w:val="single" w:sz="4" w:space="4" w:color="{fill}"/>'
@@ -70,7 +70,7 @@ def add_styles(document) -> None:
         grid = styles.add_style("Table Grid", WD_STYLE_TYPE.TABLE)
         grid.element.append(
             parse_xml(
-                f'<w:tblPr {nsdecls("w")}><w:tblBorders>'
+                f"<w:tblPr {nsdecls('w')}><w:tblBorders>"
                 + "".join(
                     f'<w:{side} w:val="single" w:sz="4" w:space="0" w:color="808080"/>'
                     for side in ("top", "left", "bottom", "right", "insideH", "insideV")
@@ -84,7 +84,9 @@ def default_reference(runtime: Runtime, work: Path) -> Path:
     """Write pandoc's reference.docx with callout styles into ``work`` and return its path."""
     path = work / "reference.docx"
     runtime.run(
-        ["pandoc", "-o", path, "--print-default-data-file", "reference.docx"], mounts=[Mount(work, writable=True)], workdir=work
+        ["pandoc", "-o", path, "--print-default-data-file", "reference.docx"],
+        mounts=[Mount(work, writable=True)],
+        workdir=work,
     )
     document = Document(str(path))
     add_styles(document)
@@ -92,9 +94,7 @@ def default_reference(runtime: Runtime, work: Path) -> Path:
     return path
 
 
-_CALLOUT = re.compile(
-    r"^\s*>+\s*(?:\[!(?P<github>[A-Za-z]+)\]|\*\*(?P<label>[A-Za-z]+):?\*\*)", re.MULTILINE
-)
+_CALLOUT = re.compile(r"^\s*>+\s*(?:\[!(?P<github>[A-Za-z]+)\]|\*\*(?P<label>[A-Za-z]+):?\*\*)", re.MULTILINE)
 
 
 def used_callouts(markdown: str) -> set[str]:
diff --git a/src/py_doc/pandoc/source.py b/src/py_doc/pandoc/source.py
index ea9a644..aacef54 100644
--- a/src/py_doc/pandoc/source.py
+++ b/src/py_doc/pandoc/source.py
@@ -108,14 +108,15 @@ def strip_heading_numbers(text: str) -> str:
         if number:
             found.append((index, level, number))
     counted = {
-        level: all(n is not None and n.isdigit() for n in numbers) and [int(n) for n in numbers] == list(range(1, len(numbers) + 1))
+        level: all(n is not None and n.isdigit() for n in numbers)
+        and [int(n) for n in numbers] == list(range(1, len(numbers) + 1))
         for level, numbers in levels.items()
     }
     for index, level, number in found:
         if number["number"].rstrip(".").isdigit() and not number["number"].endswith(".") and not counted[level]:
             continue  # a bare number that is not a count of the sections: part of the title
         heading = _HEADING.match(lines[index])
-        title = heading["rest"].strip()[number.end():]
+        title = heading["rest"].strip()[number.end() :]
         lines[index] = f"{heading['indent']}{heading['hashes']} {title}"
     return "\n".join(lines) + ("\n" if text.endswith("\n") else "")
 
diff --git a/src/py_doc/poster.py b/src/py_doc/poster.py
index bf24b58..3b65882 100644
--- a/src/py_doc/poster.py
+++ b/src/py_doc/poster.py
@@ -317,6 +317,7 @@ def sub(m):
             return m.group(0)
         mime = mimetypes.guess_type(p.name)[0] or "application/octet-stream"
         return f"![{alt}](data:{mime};base64,{base64.b64encode(p.read_bytes()).decode()})"
+
     return re.sub(r"!\[([^\]]*)\]\(([^)\s]+)\)", sub, text)
 
 
@@ -345,8 +346,12 @@ def marked(m):
         return f'<blockquote class="callout {kind}"><p class="callout-title">{kind.title()}</p><p>'
 
     out = re.sub(rf"<blockquote>\s*<p>\[!({kinds})\]\s*", marked, out, flags=re.I)
-    out = re.sub(rf"<blockquote>(\s*<p><strong>({kinds}):?</strong>)",
-                 lambda m: f'<blockquote class="callout {m.group(2).lower()}">{m.group(1)}', out, flags=re.I)
+    out = re.sub(
+        rf"<blockquote>(\s*<p><strong>({kinds}):?</strong>)",
+        lambda m: f'<blockquote class="callout {m.group(2).lower()}">{m.group(1)}',
+        out,
+        flags=re.I,
+    )
     return out.replace("<p></p>", "")
 
 
@@ -374,7 +379,12 @@ def heading_html(h):
     return esc(h)
 
 
-ROLES = ("stats", "abstract", "summary", "references")  # a section that is one of these says so: ## Key figures {.stats}
+ROLES = (
+    "stats",
+    "abstract",
+    "summary",
+    "references",
+)  # a section that is one of these says so: ## Key figures {.stats}
 # The looks of each kind of section, the default first. colour= colours whichever it is.
 STYLES = {
     "section": ("bar", "line", "card", "plain"),
@@ -406,25 +416,37 @@ def heading_attributes(heading, where):
             attrs["style"] = value.lower()
         elif item == "cols":
             if not value.isdigit() or int(value) < 1:
-                raise PosterError(f"{where}: heading '{text}' has cols={value}; it must be a whole number of at least 1")
+                raise PosterError(
+                    f"{where}: heading '{text}' has cols={value}; it must be a whole number of at least 1"
+                )
             attrs["cols"] = int(value)
         else:
             known = ", ".join([*(f".{r}" for r in ROLES), ".wide", ".flow", "cols=", "colour=", "style="])
             logger.warning(f"{where}: heading '{text}' has '{item}', which a poster does not use. It takes {known}")
     if attrs["role"] != "section":
-        for name in ("wide", "flow", "cols"):  # a stats strip, abstract, summary or references list is always full width
+        for name in (
+            "wide",
+            "flow",
+            "cols",
+        ):  # a stats strip, abstract, summary or references list is always full width
             if attrs[name]:
-                logger.warning(f"{where}: heading '{text}' is .{attrs['role']}, which is always full width, so {name} is ignored")
+                logger.warning(
+                    f"{where}: heading '{text}' is .{attrs['role']}, which is always full width, so {name} is ignored"
+                )
                 attrs[name] = False if name != "cols" else None
     elif attrs["wide"] and (attrs["flow"] or attrs["cols"]):
-        logger.warning(f"{where}: heading '{text}' is wide, so .flow and cols= are ignored: a wide section has no columns")
+        logger.warning(
+            f"{where}: heading '{text}' is wide, so .flow and cols= are ignored: a wide section has no columns"
+        )
         attrs["flow"], attrs["cols"] = False, None
     styles = STYLES[attrs["role"]]
     if attrs["style"] is None:
         attrs["style"] = styles[0]
     elif attrs["style"] not in styles:
         kind = "a section" if attrs["role"] == "section" else f"a .{attrs['role']} section"
-        raise PosterError(f"{where}: heading '{text}' has style={attrs['style']}; {kind} takes style= {', '.join(styles)}")
+        raise PosterError(
+            f"{where}: heading '{text}' has style={attrs['style']}; {kind} takes style= {', '.join(styles)}"
+        )
     return text, attrs
 
 
@@ -436,7 +458,9 @@ def parse_stats(text):
     for r in rows:
         cells = [c.strip() for c in r.strip("|").split("|")]
         if len(cells) >= 2:
-            out.append((cells[0], cells[1], cells[2] if len(cells) > 2 else "", cells[3].lower() if len(cells) > 3 else ""))
+            out.append(
+                (cells[0], cells[1], cells[2] if len(cells) > 2 else "", cells[3].lower() if len(cells) > 3 else "")
+            )
     return out
 
 
@@ -470,7 +494,9 @@ def columns_of(sections, count, split, md_path):
         except ValueError:
             raise PosterError(f"{md_path}: split must be a number, or numbers separated by commas") from None
         if len(sizes) != count - 1 or min(sizes) < 1 or sum(sizes) >= len(sections):
-            raise PosterError(f"{md_path}: split needs {count - 1} number(s) of sections, leaving at least one for the last column")
+            raise PosterError(
+                f"{md_path}: split needs {count - 1} number(s) of sections, leaving at least one for the last column"
+            )
         cuts = [sum(sizes[: i + 1]) for i in range(len(sizes))]
         return [sections[a:b] for a, b in zip([0, *cuts], [*cuts, len(sections)])]
     total, acc, columns = sum(len(c) for _, c, _ in sections), 0, [[]]
@@ -529,8 +555,13 @@ def fill(text, variables):
     return re.sub(r"\{\{\s*(\w+)\s*\}\}", lambda m: str(variables.get(m[1], m[0])), text)
 
 
-def build(md_path, runtime: Callable[[], Runtime], settings: dict | None = None, defaults: dict | None = None,
-          mermaid: dict | None = None):
+def build(
+    md_path,
+    runtime: Callable[[], Runtime],
+    settings: dict | None = None,
+    defaults: dict | None = None,
+    mermaid: dict | None = None,
+):
     """The poster page for ``md_path`` and the build state (diagrams drawn and failed).
 
     ``defaults`` (the ``poster:`` section of py-doc.yml) are under the front matter, and ``settings`` (the
@@ -549,7 +580,9 @@ def build(md_path, runtime: Callable[[], Runtime], settings: dict | None = None,
     title = meta.get("title") or (h1.group(1) if h1 else md_path.stem)
 
     parts = re.split(r"(?m)^## +(.+)$", body)
-    items = [(*heading_attributes(heading, md_path), content.strip()) for heading, content in zip(parts[1::2], parts[2::2])]
+    items = [
+        (*heading_attributes(heading, md_path), content.strip()) for heading, content in zip(parts[1::2], parts[2::2])
+    ]
     if not items:
         raise PosterError(f"{md_path}: no sections found (expected '## Heading' blocks)")
 
@@ -571,20 +604,23 @@ def role_html(h, attrs, c):
         if attrs["role"] == "stats":
             figures = "".join(
                 f'<div class="stat"><b>{esc(v)}</b><span>{esc(label)}</span>{trend_html(change, verdict)}</div>'
-                for v, label, change, verdict in parse_stats(c))
-            return f'<div{look(attrs, "stats")}>{figures}</div>' if figures else ""
+                for v, label, change, verdict in parse_stats(c)
+            )
+            return f"<div{look(attrs, 'stats')}>{figures}</div>" if figures else ""
         if attrs["role"] == "abstract":
-            return f'<div{look(attrs, "abstract")}>{render(c, ctx)}</div>'
+            return f"<div{look(attrs, 'abstract')}>{render(c, ctx)}</div>"
         if attrs["role"] == "references":
-            return f'<div{look(attrs, "refs")}><b>{esc(h)}</b>{render(c, ctx)}</div>'
+            return f"<div{look(attrs, 'refs')}><b>{esc(h)}</b>{render(c, ctx)}</div>"
         chunks = re.split(r"(?m)^### +(.+)$", c)  # the summary: a banner, then a block for each ###
         banner = " ".join(chunks[0].split())
         blocks = "".join(
             f'<div class="block"><h3>{esc(head.strip())}</h3><div class="body">{render(text.strip(), ctx)}</div></div>'
-            for head, text in zip(chunks[1::2], chunks[2::2]))
-        parts = ((f'<div class="banner">{inline(banner)}</div>' if banner else "")
-                 + (f'<div class="blocks">{blocks}</div>' if blocks else ""))
-        return f'<div{look(attrs, "summary")}>{parts}</div>' if parts else ""
+            for head, text in zip(chunks[1::2], chunks[2::2])
+        )
+        parts = (f'<div class="banner">{inline(banner)}</div>' if banner else "") + (
+            f'<div class="blocks">{blocks}</div>' if blocks else ""
+        )
+        return f"<div{look(attrs, 'summary')}>{parts}</div>" if parts else ""
 
     bands, run = [], []  # in file order: full-width parts, and runs of sections that share columns
     for item in items:
@@ -599,8 +635,10 @@ def role_html(h, attrs, c):
         bands.append(run)
     runs = [band for band in bands if isinstance(band, list)]
     if meta.get("split") and len(runs) != 1:
-        raise PosterError(f"{md_path}: split chooses the columns of one band of sections, and this poster has {len(runs)}. "
-                          "Leave it out, and the columns of each band are balanced for you")
+        raise PosterError(
+            f"{md_path}: split chooses the columns of one band of sections, and this poster has {len(runs)}. "
+            "Leave it out, and the columns of each band are balanced for you"
+        )
     middle = ""
     for band in bands:
         if isinstance(band, tuple):
@@ -608,10 +646,16 @@ def role_html(h, attrs, c):
             continue
         asked = {attrs["cols"] for _, attrs, _ in band if attrs["cols"]}
         if len(asked) > 1:
-            raise PosterError(f"{md_path}: the band of sections from '{band[0][0]}' asks for {' and '.join(map(str, sorted(asked)))} "
-                              "columns. Give cols= once, on any of its sections")
-        columns = columns_of([(h, c, attrs) for h, attrs, c in band], asked.pop() if asked else count, meta.get("split"), md_path)
-        cols = "".join(f'<div class="col">{"".join(sec(h, attrs, c) for h, c, attrs in column)}</div>' for column in columns)
+            raise PosterError(
+                f"{md_path}: the band of sections from '{band[0][0]}' asks for {' and '.join(map(str, sorted(asked)))} "
+                "columns. Give cols= once, on any of its sections"
+            )
+        columns = columns_of(
+            [(h, c, attrs) for h, attrs, c in band], asked.pop() if asked else count, meta.get("split"), md_path
+        )
+        cols = "".join(
+            f'<div class="col">{"".join(sec(h, attrs, c) for h, c, attrs in column)}</div>' for column in columns
+        )
         balanced = "" if meta.get("split") else " data-balance"  # the page script shares them out by height
         middle += f'<div class="cols"{balanced}>{cols}</div>'
 
@@ -624,10 +668,17 @@ def role_html(h, attrs, c):
     # The paper's own height to width, rounded down: A paper is not exactly 1.4142, and a poster any
     # taller than its page prints a second, empty page
     ratio = math.floor(paper_mm[1] / paper_mm[0] * 10000) / 10000
-    css = (CSS.replace("__VARS__", ctx.theme.css_variables()).replace("__W__", str(width))
-           .replace("__H__", str(round(width * ratio))).replace("__PAPER__", "{}mm {}mm".format(*paper_mm)))
-    script = (SCRIPT.replace("__RATIO__", f"{ratio:.4f}").replace("__MIN__", str(width))
-              .replace("__PAPER_PX__", str(paper_mm[0] / 25.4 * 96)))
+    css = (
+        CSS.replace("__VARS__", ctx.theme.css_variables())
+        .replace("__W__", str(width))
+        .replace("__H__", str(round(width * ratio)))
+        .replace("__PAPER__", "{}mm {}mm".format(*paper_mm))
+    )
+    script = (
+        SCRIPT.replace("__RATIO__", f"{ratio:.4f}")
+        .replace("__MIN__", str(width))
+        .replace("__PAPER_PX__", str(paper_mm[0] / 25.4 * 96))
+    )
     faces, link = font_css(ctx.theme, meta.get("embed_fonts") or False, str(md_path))
     fonts = ctx.theme.fonts.get("stylesheet") if link else None
     ctx.stylesheet = fonts  # still linked, so the PDF gets its fonts put inside: see with_web_fonts
@@ -680,18 +731,29 @@ def text(key):
         logos += f'<img alt="Logo" src="data:{mime};base64,{base64.b64encode(path.read_bytes()).decode()}">'
     qr = ""
     if footer.get("qr"):
-        label = f'<span>{text("qr-label")}</span>' if footer.get("qr-label") else ""
+        label = f"<span>{text('qr-label')}</span>" if footer.get("qr-label") else ""
         qr = f'<div class="fqr">{qr_svg(str(footer["qr"]), ctx.theme.colours["strong"], 96)}{label}</div>'
     info = [text("document"), f"Version {text('version')}" if text("version") else ""]
     docinfo = "".join(f"<span>{item}</span>" for item in info if item)
-    return (f'<footer><b class="fl">{text("left")}</b><span class="fc">{text("centre")}</span>'
-            f'<span class="fr">{text("right")}</span>'
-            + (f'<div class="logos">{logos}</div>' if logos else "") + qr + "</footer>"
-            + (f'<div class="docinfo">{docinfo}</div>' if docinfo else ""))
-
-
-def write_poster(source: Path, output: Path, runtime: Callable[[], Runtime], settings: dict | None = None,
-                 defaults: dict | None = None, pdf: bool | None = None, mermaid: dict | None = None):
+    return (
+        f'<footer><b class="fl">{text("left")}</b><span class="fc">{text("centre")}</span>'
+        f'<span class="fr">{text("right")}</span>'
+        + (f'<div class="logos">{logos}</div>' if logos else "")
+        + qr
+        + "</footer>"
+        + (f'<div class="docinfo">{docinfo}</div>' if docinfo else "")
+    )
+
+
+def write_poster(
+    source: Path,
+    output: Path,
+    runtime: Callable[[], Runtime],
+    settings: dict | None = None,
+    defaults: dict | None = None,
+    pdf: bool | None = None,
+    mermaid: dict | None = None,
+):
     """Build the poster ``source`` into ``output``, and print its PDF when its settings or ``pdf`` ask.
 
     ``pdf`` (``--pdf`` or ``--no-pdf``) wins over the ``pdf`` setting. Returns the build state and the files written.
@@ -740,4 +802,3 @@ def print_pdf(runtime: Runtime, page: str, pdf: Path) -> None:
             raise PosterError(f"Chromium wrote no PDF for {pdf}")
         pdf.parent.mkdir(parents=True, exist_ok=True)
         shutil.copyfile(output, pdf)
-
diff --git a/src/py_doc/poster_barcode.py b/src/py_doc/poster_barcode.py
index eb31106..41d5d29 100644
--- a/src/py_doc/poster_barcode.py
+++ b/src/py_doc/poster_barcode.py
@@ -13,7 +13,17 @@
 import barcode
 
 TYPES = ("code128", "code39", "ean13", "ean8", "upca", "itf14")
-ALIASES = {"128": "code128", "39": "code39", "ean": "ean13", "ean-13": "ean13", "ean-8": "ean8", "upc": "upca", "upc-a": "upca", "itf": "itf14", "itf-14": "itf14"}
+ALIASES = {
+    "128": "code128",
+    "39": "code39",
+    "ean": "ean13",
+    "ean-13": "ean13",
+    "ean-8": "ean8",
+    "upc": "upca",
+    "upc-a": "upca",
+    "itf": "itf14",
+    "itf-14": "itf14",
+}
 _GS1 = {"ean13": 13, "ean8": 8, "upca": 12, "itf14": 14}  # digits with the check digit
 _CODE39 = set("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ-. $/+%")
 # The clear space each side, in modules. An ITF narrow bar is two modules, and ITF-14 needs ten of them
@@ -47,17 +57,23 @@ def checked(kind: str, data: str) -> str:
         digits = data.replace(" ", "").replace("-", "")
         size = _GS1[kind]
         if not digits.isdigit() or len(digits) not in (size - 1, size):
-            raise BarcodeError(f"{kind} takes {size - 1} digits (the check digit is worked out) or {size} with the check digit, not '{data}'")
+            raise BarcodeError(
+                f"{kind} takes {size - 1} digits (the check digit is worked out) or {size} with the check digit, not '{data}'"
+            )
         if len(digits) == size:
             if gs1_check_digit(digits[:-1]) != digits[-1]:
-                raise BarcodeError(f"the check digit of {digits} should be {gs1_check_digit(digits[:-1])}, not {digits[-1]}: is a digit mistyped?")
+                raise BarcodeError(
+                    f"the check digit of {digits} should be {gs1_check_digit(digits[:-1])}, not {digits[-1]}: is a digit mistyped?"
+                )
             return digits
         return digits + gs1_check_digit(digits)
     if kind == "code39":
         upper = data.upper()
         bad = sorted(set(upper) - _CODE39)
         if bad:
-            raise BarcodeError(f"code39 has only A to Z, 0 to 9 and - . $ / + % and space, not {' '.join(repr(c) for c in bad)}")
+            raise BarcodeError(
+                f"code39 has only A to Z, 0 to 9 and - . $ / + % and space, not {' '.join(repr(c) for c in bad)}"
+            )
         return upper
     if any(ord(c) > 126 or (ord(c) < 32) for c in data):
         raise BarcodeError("code128 takes printable ASCII only")
@@ -105,13 +121,20 @@ def _digit_groups(kind: str, data: str) -> list[tuple[str, float, float, str]]:
     if kind == "ean13":  # guards at modules 0-2, 45-49 and 92-94
         return [(data[0], -1.5, -1.5, "end"), (data[1:7], 3, 45, "middle"), (data[7:], 50, 92, "middle")]
     if kind == "upca":
-        return [(data[0], -1.5, -1.5, "end"), (data[1:6], 10, 45, "middle"), (data[6:11], 50, 85, "middle"), (data[11], 96.5, 96.5, "start")]
+        return [
+            (data[0], -1.5, -1.5, "end"),
+            (data[1:6], 10, 45, "middle"),
+            (data[6:11], 50, 85, "middle"),
+            (data[11], 96.5, 96.5, "start"),
+        ]
     if kind == "ean8":  # guards at modules 0-2, 31-35 and 64-66
         return [(data[:4], 3, 31, "middle"), (data[4:], 36, 64, "middle")]
     return []
 
 
-def barcode_svg(kind: str, data: str, colour: str, width: int = 240, height: int = 70, text: bool = True, check: bool = False) -> str:
+def barcode_svg(
+    kind: str, data: str, colour: str, width: int = 240, height: int = 70, text: bool = True, check: bool = False
+) -> str:
     """An inline SVG ``width`` pixels wide: quiet zones, the bars, and the human-readable text under them."""
     modules = pattern(kind, data, check)
     quiet = QUIET[kind]
@@ -133,14 +156,18 @@ def barcode_svg(kind: str, data: str, colour: str, width: int = 240, height: int
             continue
         if run_start is not None:
             h = guard_h if run_kind == "G" else bar_h
-            rects.append(f'<rect x="{x0 + run_start * unit:.3f}" y="{top:.3f}" width="{(i - run_start) * unit:.3f}" height="{h:.3f}"/>')
+            rects.append(
+                f'<rect x="{x0 + run_start * unit:.3f}" y="{top:.3f}" width="{(i - run_start) * unit:.3f}" height="{h:.3f}"/>'
+            )
             run_start, run_kind = None, None
         if m in "1G":
             run_start, run_kind = i, m
     if bearer:  # bars all round the symbol, as printed on cartons
         b = bearer * unit
         inner_w, inner_h = width - 2 * b, bar_h + 2 * b
-        rects.append(f'<path fill-rule="evenodd" d="M0,0H{width:.3f}V{inner_h:.3f}H0Z M{b:.3f},{b:.3f}V{bar_h + b:.3f}H{inner_w + b:.3f}V{b:.3f}Z"/>')
+        rects.append(
+            f'<path fill-rule="evenodd" d="M0,0H{width:.3f}V{inner_h:.3f}H0Z M{b:.3f},{b:.3f}V{bar_h + b:.3f}H{inner_w + b:.3f}V{b:.3f}Z"/>'
+        )
     label = ""
     if text:
         y = (bar_h + 2 * bearer * unit if bearer else bar_h) + font * 0.95
diff --git a/src/py_doc/poster_blocks.py b/src/py_doc/poster_blocks.py
index 13b5893..b18af46 100644
--- a/src/py_doc/poster_blocks.py
+++ b/src/py_doc/poster_blocks.py
@@ -54,8 +54,8 @@ def mermaid_init(theme):
     }  # fmt: skip
     return "---\nconfig: " + json.dumps({"theme": "base", "themeVariables": variables}) + "\n---\n"
 
-TOK = re.compile(r"\[([^\]|]+)(?:\|([^\]]+))?\]|-(?:([^>\[\]]*?)-)?>")
 
+TOK = re.compile(r"\[([^\]|]+)(?:\|([^\]]+))?\]|-(?:([^>\[\]]*?)-)?>")
 
 
 class Ctx:
@@ -99,6 +99,7 @@ def parse_opts(info):
 # Diagram fences -> the tool container -> embedded image
 # ---------------------------------------------------------------------------
 
+
 def render_diagram(lang, code, ctx):
     ctx.n += 1
     if lang == "mermaid" and "%%{init" not in code and not code.lstrip().startswith("---"):
@@ -122,14 +123,17 @@ def diagram_html(lang, code, opts, ctx):
         errs = [line.strip() for line in lines if "error" in line.lower()]
         msg = (errs or lines or [type(exc).__name__])[0 if errs else -1].strip()[:160]
         logger.warning(f"{lang} diagram not rendered: {msg}")
-        return (f'<pre><code>{esc(code)}</code></pre>'
-                f'<p class="caption">{esc(lang)} diagram could not be rendered: {esc(msg)}</p>')
+        return (
+            f"<pre><code>{esc(code)}</code></pre>"
+            f'<p class="caption">{esc(lang)} diagram could not be rendered: {esc(msg)}</p>'
+        )
 
 
 # ---------------------------------------------------------------------------
 # Poster blocks: cards, lcd, and the figure kinds (segments, flow, lanes)
 # ---------------------------------------------------------------------------
 
+
 def cards_html(code, opts, ctx):
     rows = [[c.strip() for c in line.split("|")] for line in code.splitlines() if line.strip()]
     style = opts.get("style", "title")
@@ -158,8 +162,11 @@ def lcd_html(code, opts, ctx):
             continue
         shown = "".join(f"<div>{esc(x)}</div>" for x in s if not x.startswith("--"))
         cap = " ".join(x[2:].strip() for x in s if x.startswith("--"))
-        out += (f'<div class="lcd"><div class="scr">{shown}</div>'
-                + (f'<div class="cap">{esc(cap)}</div>' if cap else "") + "</div>")
+        out += (
+            f'<div class="lcd"><div class="scr">{shown}</div>'
+            + (f'<div class="cap">{esc(cap)}</div>' if cap else "")
+            + "</div>"
+        )
     count = sum(1 for s in screens if s)
     cols = _whole(opts, "cols", min(count, 3) or 1, ctx)
     return f'<div class="lcds" style="grid-template-columns:repeat({cols},minmax(0,1fr))">{out}</div>'
@@ -186,8 +193,11 @@ def segments_part(code, ctx):
         label = r[1] if len(r) > 1 else ""
         det = r[2] if len(r) > 2 else ""
         detailed = detailed or bool(det)
-        cells += (f'<div style="flex:{r[0]};background:{ctx.theme.colour(r[3] if len(r) > 3 else None)}">{inline(label)}'
-                  + (f"<small>{inline(det)}</small>" if det else "") + "</div>")
+        cells += (
+            f'<div style="flex:{r[0]};background:{ctx.theme.colour(r[3] if len(r) > 3 else None)}">{inline(label)}'
+            + (f"<small>{inline(det)}</small>" if det else "")
+            + "</div>"
+        )
     h = meta.get("height") or ("64" if detailed else "36")
     return meta.get("title"), f'<div class="bar" style="min-height:{h}px">{cells}</div>', "\n".join(notes).strip()
 
@@ -223,8 +233,11 @@ def lanes_part(code, ctx):
         label, *cells = [c.strip() for c in line.split("|")]
         cells = [c.replace("-", "‑") for c in cells]  # non-breaking hyphen keeps "wake-up" whole
         inner = "".join(
-            f'<div class="cell fill">{inline(c[1:].strip())}</div>' if c.startswith("*")
-            else f'<div class="cell dash">{inline(c)}</div>' for c in cells)
+            f'<div class="cell fill">{inline(c[1:].strip())}</div>'
+            if c.startswith("*")
+            else f'<div class="cell dash">{inline(c)}</div>'
+            for c in cells
+        )
         lanes += f'<div class="lane"><b>{esc(label)}</b><div class="cells">{inner}</div></div>'
     return meta.get("title"), f'<div class="lanes">{lanes}</div>', "\n".join(notes).strip()
 
@@ -249,8 +262,11 @@ def timeline_html(code, opts, ctx):
         date, label = cells[0], cells[1] if len(cells) > 1 else ""
         detail = cells[2] if len(cells) > 2 else ""
         colour = ctx.theme.colour(cells[3] if len(cells) > 3 else None, "accent")
-        items += (f'<div class="tl-item"><i style="background:{colour}"></i><b>{inline(date)}</b><span>{inline(label)}</span>'
-                  + (f"<small>{inline(detail)}</small>" if detail else "") + "</div>")
+        items += (
+            f'<div class="tl-item"><i style="background:{colour}"></i><b>{inline(date)}</b><span>{inline(label)}</span>'
+            + (f"<small>{inline(detail)}</small>" if detail else "")
+            + "</div>"
+        )
     return f'<div class="timeline{" vertical" if "vertical" in opts else ""}">{items}</div>'
 
 
@@ -311,7 +327,11 @@ def chart_html(code, opts, ctx):
     colours = [ctx.theme.colour(names[i % len(names)].strip()) for i in range(count)]
     unit = opts.get("unit", "")
     dashed = {name.strip().lower() for name in opts.get("dashed", "").split(",") if name.strip()}
-    dashed = {j for j in range(count) if (series[j].lower() if j < len(series) else str(j + 1)) in dashed or str(j + 1) in dashed}
+    dashed = {
+        j
+        for j in range(count)
+        if (series[j].lower() if j < len(series) else str(j + 1)) in dashed or str(j + 1) in dashed
+    }
     values = [v for _, vs in rows for v in vs]
     low = _float(opts, "min", ctx) if "min" in opts else -_nice(-min(values)) if min(values) < 0 else 0.0
     high = _float(opts, "max", ctx) if "max" in opts else _nice(max(values)) or 1.0
@@ -339,12 +359,18 @@ def chart_html(code, opts, ctx):
             for j, v in enumerate(vs):
                 x1 = left + (v - low) / span * plot_w
                 yy = y + band * 0.15 + j * thick
-                out.append(f'<rect x="{min(x0, x1):.1f}" y="{yy:.1f}" width="{abs(x1 - x0):.1f}" height="{thick:.1f}" fill="{colours[j]}"/>')
+                out.append(
+                    f'<rect x="{min(x0, x1):.1f}" y="{yy:.1f}" width="{abs(x1 - x0):.1f}" height="{thick:.1f}" fill="{colours[j]}"/>'
+                )
                 if shown == "all" or shown == "last" and i == len(rows) - 1:
-                    out.append(f'<text x="{max(x0, x1) + 4:.1f}" y="{yy + thick / 2 + 4:.1f}" {text}>{_number(v)}{esc(unit)}</text>')
+                    out.append(
+                        f'<text x="{max(x0, x1) + 4:.1f}" y="{yy + thick / 2 + 4:.1f}" {text}>{_number(v)}{esc(unit)}</text>'
+                    )
         out.append(f'<line x1="{x0:.1f}" y1="{top}" x2="{x0:.1f}" y2="{height - bottom}" stroke="currentColor"/>')
         if axis:
-            out.append(f'<text x="{left + plot_w / 2:.1f}" y="{height - 2}" text-anchor="middle" {text}>{esc(axis)}</text>')
+            out.append(
+                f'<text x="{left + plot_w / 2:.1f}" y="{height - 2}" text-anchor="middle" {text}>{esc(axis)}</text>'
+            )
     else:
         left, top, right, bottom = 52 + (22 if axis else 0), 12 + legend, 12, 30
         plot_w, plot_h = width - left - right, height - top - bottom
@@ -354,31 +380,47 @@ def y_of(v):
 
         for n in range(round(span / step) + 1):
             v = low + step * n
-            out.append(f'<line x1="{left}" y1="{y_of(v):.1f}" x2="{width - right}" y2="{y_of(v):.1f}" stroke="currentColor" stroke-opacity=".25"/>')
-            out.append(f'<text x="{left - 6}" y="{y_of(v) + 4:.1f}" text-anchor="end" {text}>{_number(round(v, 9))}</text>')
+            out.append(
+                f'<line x1="{left}" y1="{y_of(v):.1f}" x2="{width - right}" y2="{y_of(v):.1f}" stroke="currentColor" stroke-opacity=".25"/>'
+            )
+            out.append(
+                f'<text x="{left - 6}" y="{y_of(v) + 4:.1f}" text-anchor="end" {text}>{_number(round(v, 9))}</text>'
+            )
         if axis:
             middle = top + plot_h / 2
-            out.append(f'<text x="14" y="{middle:.1f}" transform="rotate(-90 14 {middle:.1f})" text-anchor="middle" {text}>{esc(axis)}</text>')
+            out.append(
+                f'<text x="14" y="{middle:.1f}" transform="rotate(-90 14 {middle:.1f})" text-anchor="middle" {text}>{esc(axis)}</text>'
+            )
         band = plot_w / len(rows)
         for i, (label, _) in enumerate(rows):
-            out.append(f'<text x="{left + band * (i + 0.5):.1f}" y="{height - 10}" text-anchor="middle" {text}>{esc(label)}</text>')
+            out.append(
+                f'<text x="{left + band * (i + 0.5):.1f}" y="{height - 10}" text-anchor="middle" {text}>{esc(label)}</text>'
+            )
         if kind == "column":
             for i, (_, vs) in enumerate(rows):
                 thick = band * 0.7 / len(vs)
                 for j, v in enumerate(vs):
                     x = left + band * i + band * 0.15 + j * thick
                     y1, y0 = y_of(v), y_of(0)
-                    out.append(f'<rect x="{x:.1f}" y="{min(y0, y1):.1f}" width="{thick:.1f}" height="{abs(y0 - y1):.1f}" fill="{colours[j]}"/>')
+                    out.append(
+                        f'<rect x="{x:.1f}" y="{min(y0, y1):.1f}" width="{thick:.1f}" height="{abs(y0 - y1):.1f}" fill="{colours[j]}"/>'
+                    )
                     if shown == "all" or shown == "last" and i == len(rows) - 1:
-                        out.append(f'<text x="{x + thick / 2:.1f}" y="{min(y0, y1) - 4:.1f}" text-anchor="middle" {text}>{_number(v)}{esc(unit)}</text>')
+                        out.append(
+                            f'<text x="{x + thick / 2:.1f}" y="{min(y0, y1) - 4:.1f}" text-anchor="middle" {text}>{_number(v)}{esc(unit)}</text>'
+                        )
         else:
             placed: dict[float, list[float]] = {}  # the value labels at each point across, so two do not overlap
             for j in range(count):
-                points = [(left + band * (i + 0.5), y_of(vs[j]), vs[j]) for i, (_, vs) in enumerate(rows) if j < len(vs)]
+                points = [
+                    (left + band * (i + 0.5), y_of(vs[j]), vs[j]) for i, (_, vs) in enumerate(rows) if j < len(vs)
+                ]
                 path = " ".join(f"{x:.1f},{y:.1f}" for x, y, _ in points)
                 if area:
                     base = y_of(max(low, 0)) if low < 0 < high else y_of(low)
-                    out.append(f'<polygon points="{points[0][0]:.1f},{base:.1f} {path} {points[-1][0]:.1f},{base:.1f}" fill="{colours[j]}" fill-opacity=".15"/>')
+                    out.append(
+                        f'<polygon points="{points[0][0]:.1f},{base:.1f} {path} {points[-1][0]:.1f},{base:.1f}" fill="{colours[j]}" fill-opacity=".15"/>'
+                    )
                 dash = ' stroke-dasharray="10 6"' if j in dashed else ""
                 out.append(f'<polyline points="{path}" fill="none" stroke="{colours[j]}" stroke-width="3"{dash}/>')
                 if markers:
@@ -387,15 +429,22 @@ def y_of(v):
                     if shown == "all" or shown == "last" and n == len(points) - 1:
                         at = y - 9 if all(abs(y - 9 - other) >= 16 for other in placed.get(x, [])) else y + 21
                         placed.setdefault(x, []).append(at)
-                        out.append(f'<text x="{x:.1f}" y="{at:.1f}" text-anchor="middle" {text}>{_number(v)}{esc(unit)}</text>')
+                        out.append(
+                            f'<text x="{x:.1f}" y="{at:.1f}" text-anchor="middle" {text}>{_number(v)}{esc(unit)}</text>'
+                        )
         zero = y_of(min(max(0, low), high))  # the zero line, or the bottom of the axis when zero is not on it
         out.append(f'<line x1="{left}" y1="{zero:.1f}" x2="{width - right}" y2="{zero:.1f}" stroke="currentColor"/>')
     for j, name in enumerate(series[:count] if legend else []):
         x = 12 + j * 150
-        out.append(f'<rect x="{x}" y="4" width="14" height="14" fill="{colours[j]}"/><text x="{x + 20}" y="16" {text}>{esc(name)}</text>')
+        out.append(
+            f'<rect x="{x}" y="4" width="14" height="14" fill="{colours[j]}"/><text x="{x + 20}" y="16" {text}>{esc(name)}</text>'
+        )
     title = f'<div class="fig-title">{esc(opts["title"])}</div>' if opts.get("title") else ""
-    svg = (f'<svg class="chart" viewBox="0 0 {width} {height}" role="img" aria-label="{esc(opts.get("title", "chart"))}">'
-           + "".join(out) + "</svg>")
+    svg = (
+        f'<svg class="chart" viewBox="0 0 {width} {height}" role="img" aria-label="{esc(opts.get("title", "chart"))}">'
+        + "".join(out)
+        + "</svg>"
+    )
     return f'<div class="fig">{title}{svg}</div>'
 
 
@@ -404,7 +453,9 @@ def qr_svg(text, colour, size=140, error="m"):
     try:
         code = segno.make(text.strip(), error=error, micro=False)
     except segno.DataOverflowError:
-        raise PosterError(f"'{text.strip()[:60]}...' is too long for a QR code; use shorter text, or a lower ecc=") from None
+        raise PosterError(
+            f"'{text.strip()[:60]}...' is too long for a QR code; use shorter text, or a lower ecc="
+        ) from None
     # SVG needs no whole pixels, so every code is the size asked for, however many modules it has
     scale = round(size / code.symbol_size(scale=1, border=2)[0], 4)
     return code.svg_inline(scale=scale, border=2, dark=colour, light=None)
@@ -455,7 +506,9 @@ def barcode_html(code, opts, ctx):
     if flags["check"] and kind != "code39":
         raise PosterError(f"{ctx.where}: check=yes is for code39; {kind} always has its check digit")
     width, height = _whole(opts, "width", 240, ctx), _whole(opts, "height", 70, ctx)
-    svg = poster_barcode.barcode_svg(kind, data, ctx.theme.colours["strong"], width, height, flags["text"], flags["check"])
+    svg = poster_barcode.barcode_svg(
+        kind, data, ctx.theme.colours["strong"], width, height, flags["text"], flags["check"]
+    )
     label = f'<div class="cap">{inline(opts["label"])}</div>' if opts.get("label") else ""
     return f'<div class="barcode">{svg}{label}</div>'
 
@@ -530,10 +583,16 @@ def progress_html(code, opts, ctx):
         default = "good" if met else "bad" if lower else "accent"
         colour = ctx.theme.colour(row[3] if len(row) > 3 else None, default)
         share = min(value / target, 1.0)
-        text = f"{value / target * 100:.0f} %" if shown == "percent" else f"{esc(row[1])}{esc(unit)} of {esc(row[2])}{esc(unit)}"
+        text = (
+            f"{value / target * 100:.0f} %"
+            if shown == "percent"
+            else f"{esc(row[1])}{esc(unit)} of {esc(row[2])}{esc(unit)}"
+        )
         mark = " &#10003;" if met else ""
-        out += (f'<div class="prog"><div class="pl"><span>{inline(row[0])}</span><b>{text}{mark}</b></div>'
-                f'<div class="pt"><i style="width:{share * 100:.1f}%;background:{colour}"></i></div></div>')
+        out += (
+            f'<div class="prog"><div class="pl"><span>{inline(row[0])}</span><b>{text}{mark}</b></div>'
+            f'<div class="pt"><i style="width:{share * 100:.1f}%;background:{colour}"></i></div></div>'
+        )
     return f'<div class="progress">{out}</div>'
 
 
@@ -559,15 +618,24 @@ def compare_html(code, opts, ctx):
     """A ``| Before | After`` header, then ``Label | before | after`` lines. The last column is the one to see."""
     rows = _rows(code)
     if len(rows) < 2 or rows[0][0] or len(rows[0]) < 3:
-        raise PosterError(f"{ctx.where}: a compare block starts with a header such as '| Before | After', then 'Label | before | after' lines")
+        raise PosterError(
+            f"{ctx.where}: a compare block starts with a header such as '| Before | After', then 'Label | before | after' lines"
+        )
     heads, width = rows[0][1:], len(rows[0])
     grid = f"grid-template-columns:minmax(0,1.2fr) repeat({len(heads)},minmax(0,1fr))"
-    out = '<div class="cmp-h"></div>' + "".join(f'<div class="cmp-h{" last" if n == len(heads) - 1 else ""}">{inline(h)}</div>' for n, h in enumerate(heads))
+    out = '<div class="cmp-h"></div>' + "".join(
+        f'<div class="cmp-h{" last" if n == len(heads) - 1 else ""}">{inline(h)}</div>' for n, h in enumerate(heads)
+    )
     for row in rows[1:]:
         if len(row) != width:
-            raise PosterError(f"{ctx.where}: the compare line '{' | '.join(row)}' needs {width} cells, as its header has")
+            raise PosterError(
+                f"{ctx.where}: the compare line '{' | '.join(row)}' needs {width} cells, as its header has"
+            )
         out += f'<div class="cmp-l">{inline(row[0])}</div>'
-        out += "".join(f'<div class="cmp-v{" last" if n == len(heads) - 1 else ""}">{inline(v)}</div>' for n, v in enumerate(row[1:]))
+        out += "".join(
+            f'<div class="cmp-v{" last" if n == len(heads) - 1 else ""}">{inline(v)}</div>'
+            for n, v in enumerate(row[1:])
+        )
     return f'<div class="compare" style="{grid}">{out}</div>'
 
 
diff --git a/src/py_doc/poster_cli.py b/src/py_doc/poster_cli.py
index 6cc8895..cc7eb5b 100644
--- a/src/py_doc/poster_cli.py
+++ b/src/py_doc/poster_cli.py
@@ -34,12 +34,32 @@ def run_poster(argv: list[str]) -> int:
         prog="py-doc poster", description="Build self-contained HTML posters from Markdown",
         epilog=POSTER_EXAMPLES, formatter_class=argparse.RawDescriptionHelpFormatter,
     )  # fmt: skip
-    parser.add_argument("targets", nargs="*", metavar="POSTER", help="Markdown files, or names under posters: in py-doc.yml (default: every poster)")
-    parser.add_argument("-o", "--output", help="Output path, for one poster (default: the input name with .html, or the poster's output)")
+    parser.add_argument(
+        "targets",
+        nargs="*",
+        metavar="POSTER",
+        help="Markdown files, or names under posters: in py-doc.yml (default: every poster)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        help="Output path, for one poster (default: the input name with .html, or the poster's output)",
+    )
     parser.add_argument("-c", "--config", help="Configuration file (default: the nearest py-doc.yml)")
-    parser.add_argument("--theme", help=f"A built-in theme ({', '.join(BUILTIN)}) or a theme file. Wins over every other setting")
-    parser.add_argument("--var", action="append", default=[], metavar="NAME=VALUE", type=_assignment, help="Set a {{variable}}")
-    parser.add_argument("--condition", action="append", default=[], metavar="NAME=VALUE", type=_assignment, help="Set a [[IF:]] condition")
+    parser.add_argument(
+        "--theme", help=f"A built-in theme ({', '.join(BUILTIN)}) or a theme file. Wins over every other setting"
+    )
+    parser.add_argument(
+        "--var", action="append", default=[], metavar="NAME=VALUE", type=_assignment, help="Set a {{variable}}"
+    )
+    parser.add_argument(
+        "--condition",
+        action="append",
+        default=[],
+        metavar="NAME=VALUE",
+        type=_assignment,
+        help="Set a [[IF:]] condition",
+    )
     parser.add_argument(
         "--embed-fonts", action=argparse.BooleanOptionalAction, default=None,
         help="Download the theme's web fonts once and put them inside the page (default: the embed_fonts setting)",
@@ -48,8 +68,14 @@ def run_poster(argv: list[str]) -> int:
         "--pdf", action=argparse.BooleanOptionalAction, default=None,
         help="Also print each poster to a one-page PDF beside its page (default: the pdf setting)",
     )  # fmt: skip
-    parser.add_argument("--watch", action="store_true", help="Build again on every save, and reload the page in the browser (Ctrl+C stops)")
-    parser.add_argument("--port", type=int, default=0, help="With --watch, the local port to serve the pages on (default: a free one)")
+    parser.add_argument(
+        "--watch",
+        action="store_true",
+        help="Build again on every save, and reload the page in the browser (Ctrl+C stops)",
+    )
+    parser.add_argument(
+        "--port", type=int, default=0, help="With --watch, the local port to serve the pages on (default: a free one)"
+    )
     parser.add_argument("--no-open", action="store_true", help="With --watch, do not open the browser")
     noise = parser.add_mutually_exclusive_group()
     noise.add_argument("-q", "--quiet", action="store_true", help="Only show warnings and errors")
@@ -81,8 +107,14 @@ def build_all() -> tuple[dict[str, Path], set[Path]]:
         if args.output and len(jobs) != 1:
             raise ConfigError("--output needs exactly one poster")
         command_line = layer(
-            {"theme": args.theme, "variables": dict(args.var), "conditions": _conditions(args.condition), "embed_fonts": args.embed_fonts},
-            Path.cwd(), "the command line",
+            {
+                "theme": args.theme,
+                "variables": dict(args.var),
+                "conditions": _conditions(args.condition),
+                "embed_fonts": args.embed_fonts,
+            },
+            Path.cwd(),
+            "the command line",
         )
         defaults = project.poster if project else {}
         pages, sources = {}, {config_path.resolve()} if config_path else set()
@@ -127,7 +159,9 @@ def _jobs(targets: list[str], files: dict[str, Path], project) -> list[PosterCon
     posters = project.posters if project else {}
     if not targets:
         if not posters:
-            raise ConfigError("no poster given, and no posters: in py-doc.yml. Name a Markdown file, or add posters to py-doc.yml")
+            raise ConfigError(
+                "no poster given, and no posters: in py-doc.yml. Name a Markdown file, or add posters to py-doc.yml"
+            )
         return list(posters.values())
     jobs = []
     for target in targets:
diff --git a/src/py_doc/poster_fonts.py b/src/py_doc/poster_fonts.py
index ad87317..26d5703 100644
--- a/src/py_doc/poster_fonts.py
+++ b/src/py_doc/poster_fonts.py
@@ -84,7 +84,9 @@ def merge_weights(css: str) -> str:
         weight = props.pop("font-weight", "400").strip()
         if not re.fullmatch(r"\d{3}( \d{3})?", weight):
             return css  # a weight such as 'bold': leave the rules as they are
-        merged.setdefault(tuple(sorted((k, v.strip()) for k, v in props.items())), []).extend(int(w) for w in weight.split())
+        merged.setdefault(tuple(sorted((k, v.strip()) for k, v in props.items())), []).extend(
+            int(w) for w in weight.split()
+        )
     rules = []
     for props, weights in merged.items():
         low, high = min(weights), max(weights)
@@ -142,5 +144,7 @@ def font_css(theme, embed, where: str) -> tuple[str, bool]:
             link = False
     size = len(css.encode("utf-8"))
     if size > MAX_BYTES:
-        logger.warning(f"{where}: the embedded fonts are {size // (1024 * 1024)} MB, so the page is slow to send and open")
+        logger.warning(
+            f"{where}: the embedded fonts are {size // (1024 * 1024)} MB, so the page is slow to send and open"
+        )
     return css, link
diff --git a/src/py_doc/poster_qr.py b/src/py_doc/poster_qr.py
index 303e9f0..730497f 100644
--- a/src/py_doc/poster_qr.py
+++ b/src/py_doc/poster_qr.py
@@ -13,7 +13,16 @@
 from urllib.parse import quote
 
 TYPES = ("url", "text", "vcard", "event", "wifi", "email", "phone", "sms", "geo")
-ALIASES = {"contact": "vcard", "vcf": "vcard", "ical": "event", "ics": "event", "calendar": "event", "tel": "phone", "mail": "email", "mailto": "email"}
+ALIASES = {
+    "contact": "vcard",
+    "vcf": "vcard",
+    "ical": "event",
+    "ics": "event",
+    "calendar": "event",
+    "tel": "phone",
+    "mail": "email",
+    "mailto": "email",
+}
 EXTENSIONS = {".vcf": "vcard", ".vcard": "vcard", ".ics": "event", ".ical": "event"}
 KEYS = {
     "vcard": ("name", "first", "last", "org", "title", "tel", "mobile", "email", "url", "address", "note"),
@@ -48,7 +57,15 @@ def payload(kind: str, text: str) -> str:
     if re.match(r"^\s*(BEGIN:V|WIFI:|MAILTO:|TEL:|SMSTO:|GEO:)", text, re.IGNORECASE):
         return text.strip()  # already in the standard form, such as a .vcf file's text
     fields = _fields(kind, text)
-    return {"vcard": _vcard, "event": _event, "wifi": _wifi, "email": _email, "phone": _phone, "sms": _sms, "geo": _geo}[kind](fields)
+    return {
+        "vcard": _vcard,
+        "event": _event,
+        "wifi": _wifi,
+        "email": _email,
+        "phone": _phone,
+        "sms": _sms,
+        "geo": _geo,
+    }[kind](fields)
 
 
 def _fields(kind: str, text: str) -> dict[str, list[str]]:
@@ -102,9 +119,13 @@ def _vcard(fields: dict) -> str:
     lines += [f"TEL;TYPE=CELL:{n}" for n in fields.get("mobile", [])]
     lines += [f"EMAIL;TYPE=INTERNET:{e}" for e in fields.get("email", [])]
     lines += [f"URL:{u}" for u in fields.get("url", [])]
-    for address in fields.get("address", []):  # one line, its parts separated by commas: street, town, postcode, country
+    for address in fields.get(
+        "address", []
+    ):  # one line, its parts separated by commas: street, town, postcode, country
         parts = [p.strip() for p in address.split(",")]
-        street, town, code, country = (parts + ["", "", "", ""])[:4] if len(parts) <= 4 else (", ".join(parts[:-3]), *parts[-3:])
+        street, town, code, country = (
+            (parts + ["", "", "", ""])[:4] if len(parts) <= 4 else (", ".join(parts[:-3]), *parts[-3:])
+        )
         lines.append(f"ADR;TYPE=WORK:;;{_v(street)};{_v(town)};;{_v(code)};{_v(country)}")
     if fields.get("note"):
         lines.append(f"NOTE:{_v(_one(fields, 'note', 'vcard'))}")
@@ -144,7 +165,10 @@ def _event(fields: dict) -> str:
         if end < start:
             raise QrError("type=event: end is before start")
     else:
-        end, end_utc = (start + timedelta(days=1) if not isinstance(start, datetime) else start + timedelta(hours=1)), utc
+        end, end_utc = (
+            (start + timedelta(days=1) if not isinstance(start, datetime) else start + timedelta(hours=1)),
+            utc,
+        )
     if isinstance(start, datetime):
         timing = [f"DTSTART:{_ical(start, utc)}", f"DTEND:{_ical(end, end_utc)}"]
     else:  # an all-day event ends on the day after its last day
@@ -184,7 +208,9 @@ def _wifi(fields: dict) -> str:
         raise QrError(f"type=wifi: security {security} needs a 'password:' line")
     security = "WPA" if security in ("WPA2", "WPA3", "SAE") else security  # what the WIFI: form names WPA2 and WPA3
     hidden = _one(fields, "hidden", "wifi").lower() in ("true", "yes", "1")
-    text = f"WIFI:T:{security};S:{_w(ssid)};" + (f"P:{_w(password)};" if password else "") + ("H:true;" if hidden else "")
+    text = (
+        f"WIFI:T:{security};S:{_w(ssid)};" + (f"P:{_w(password)};" if password else "") + ("H:true;" if hidden else "")
+    )
     return text + ";"
 
 
diff --git a/src/py_doc/poster_settings.py b/src/py_doc/poster_settings.py
index da7eccf..e5979f8 100644
--- a/src/py_doc/poster_settings.py
+++ b/src/py_doc/poster_settings.py
@@ -71,7 +71,11 @@ def layer(data: dict, folder: Path, where: str, strict: bool = True) -> dict:
         elif key == "logo":
             out[key] = _path(value, folder, place)
         elif key == "embed_fonts":  # true: every font of the stylesheet; a list: only those subsets, such as latin
-            if isinstance(value, list) and value and all(isinstance(v, str) and re.fullmatch(r"[a-z][a-z0-9-]*", v) for v in value):
+            if (
+                isinstance(value, list)
+                and value
+                and all(isinstance(v, str) and re.fullmatch(r"[a-z][a-z0-9-]*", v) for v in value)
+            ):
                 out[key] = [str(v) for v in value]
             elif isinstance(value, bool):
                 out[key] = value
@@ -91,7 +95,9 @@ def layer(data: dict, folder: Path, where: str, strict: bool = True) -> dict:
     files = out.get("fonts", {}).get("files")
     if isinstance(files, list):  # a font file is from this layer's file, as a logo is
         out["fonts"]["files"] = [
-            {**item, "file": str(_path(item["file"], folder, f"{where}.fonts.files"))} if isinstance(item, dict) and item.get("file") else item
+            {**item, "file": str(_path(item["file"], folder, f"{where}.fonts.files"))}
+            if isinstance(item, dict) and item.get("file")
+            else item
             for item in files
         ]
     if "header" in out:
diff --git a/src/py_doc/poster_themes.py b/src/py_doc/poster_themes.py
index 9f4de59..1badbb1 100644
--- a/src/py_doc/poster_themes.py
+++ b/src/py_doc/poster_themes.py
@@ -157,7 +157,9 @@ def _checked(value, where: str) -> str:
 def _apply(theme: Theme, data: dict, where: str, folder: Path | None) -> None:
     unknown = set(data) - {"extends", "colours", "palette", "fonts", "logo", "name", "description"}
     if unknown:
-        raise ThemeError(f"{where}: unknown key '{sorted(unknown)[0]}'. Allowed: colours, extends, fonts, logo, palette")
+        raise ThemeError(
+            f"{where}: unknown key '{sorted(unknown)[0]}'. Allowed: colours, extends, fonts, logo, palette"
+        )
     for name, value in (data.get("colours") or {}).items():
         if name not in COLOUR_ROLES:
             raise ThemeError(f"{where}: unknown colour '{name}'. Colours: {', '.join(COLOUR_ROLES)}")
@@ -192,7 +194,11 @@ def _font_files(value, folder: Path | None, where: str) -> list[FontFile]:
         unknown = set(item) - {"family", "file", "weight", "style"}
         if unknown:
             raise ThemeError(f"{place}: unknown key '{sorted(unknown)[0]}'. Allowed: family, file, weight, style")
-        family, weight, style = str(item["family"]).strip(), str(item.get("weight", 400)).strip(), str(item.get("style", "normal")).strip()
+        family, weight, style = (
+            str(item["family"]).strip(),
+            str(item.get("weight", 400)).strip(),
+            str(item.get("style", "normal")).strip(),
+        )
         if re.search(r"['\"\\;{}<>]", family):
             raise ThemeError(f"{place}: the family '{family}' has a character a font name cannot have")
         if not re.fullmatch(r"[1-9]00( [1-9]00)?", weight):
diff --git a/src/py_doc/pptx_import.py b/src/py_doc/pptx_import.py
index a0183e3..01fbe30 100644
--- a/src/py_doc/pptx_import.py
+++ b/src/py_doc/pptx_import.py
@@ -103,7 +103,11 @@ def _title_slide(self, slide) -> bool:
         if SUBTITLE in kinds:  # pandoc puts the author and the date on later lines of the subtitle
             lines = kinds[SUBTITLE].text_frame.text.replace(LINE_BREAK, "\n").strip().splitlines()
             self.subtitle = _plain(lines[0]) if lines else None
-        others = [s for s in _shapes(slide) if not (s.is_placeholder and s.placeholder_format.type in (*TITLES, SUBTITLE, *FURNITURE))]
+        others = [
+            s
+            for s in _shapes(slide)
+            if not (s.is_placeholder and s.placeholder_format.type in (*TITLES, SUBTITLE, *FURNITURE))
+        ]
         if others:  # more than a title slide: keep its content as a slide of its own
             self._slide(slide, skip_title=True)
         return True
@@ -300,7 +304,11 @@ def _is_picture(shape) -> bool:
 
 def _is_caption(shape, below) -> bool:
     """``below`` is one short line of text right under ``shape``, as pandoc writes a caption."""
-    if not below.has_text_frame or below.has_text_frame and len([p for p in below.text_frame.paragraphs if p.text.strip()]) != 1:
+    if (
+        not below.has_text_frame
+        or below.has_text_frame
+        and len([p for p in below.text_frame.paragraphs if p.text.strip()]) != 1
+    ):
         return False
     if _marker(below.text_frame.paragraphs[0], False) or _is_code(below.text_frame.paragraphs[0]):
         return False
diff --git a/src/py_doc/report.py b/src/py_doc/report.py
index be9a99a..675b7e7 100644
--- a/src/py_doc/report.py
+++ b/src/py_doc/report.py
@@ -171,7 +171,11 @@ def _version(runtime: Runtime, tool: str) -> str | None:
     # --- output -----------------------------------------------------------------------------------
 
     def data(self) -> dict[str, Any]:
-        failed = bool(self.error) or any(d["status"] == "failed" for d in self.documents) or any(s["status"] == "failed" for s in self.steps)
+        failed = (
+            bool(self.error)
+            or any(d["status"] == "failed" for d in self.documents)
+            or any(s["status"] == "failed" for s in self.steps)
+        )
         data: dict[str, Any] = {
             "schema": 1,
             "py_doc": __version__,
diff --git a/src/py_doc/runtime/engine.py b/src/py_doc/runtime/engine.py
index b1715ca..67be813 100644
--- a/src/py_doc/runtime/engine.py
+++ b/src/py_doc/runtime/engine.py
@@ -36,7 +36,7 @@
     "failed to connect to the docker api",
     "is the docker daemon running",
 )
-_NO_DOCKER = ("execvpe(docker) failed", "docker: command not found", 'executable file not found in $path')
+_NO_DOCKER = ("execvpe(docker) failed", "docker: command not found", "executable file not found in $path")
 _IMAGE_MISSING = ("unable to find image", "no such image", "pull access denied")
 _MISSING_BIND = "bind source path does not exist"
 
@@ -209,7 +209,11 @@ def _raise_environment(self, result: ToolResult, running: bool = False) -> None:
         """Turn the engine's own failures into environment problems, with what to do about them."""
         low = result.stderr.lower()
         if any(marker in low for marker in _NO_DOCKER):
-            where = "inside the WSL distro (`wsl -d <distro>`, then follow https://docs.docker.com/engine/install/ubuntu/)" if self.windows else "(https://docs.docker.com/engine/install/)"
+            where = (
+                "inside the WSL distro (`wsl -d <distro>`, then follow https://docs.docker.com/engine/install/ubuntu/)"
+                if self.windows
+                else "(https://docs.docker.com/engine/install/)"
+            )
             raise EnvironmentProblem(
                 f"Docker Engine is not installed {where}. "
                 "Set runtime.wsl_distro in py-doc.yml if Docker is in a distro other than the default"
@@ -241,8 +245,15 @@ def container_path(self, path: str | os.PathLike) -> str:
             if code != 0 or not converted:
                 converted = _drive_path(text)  # some distros cannot start wslpath ("Exec format error")
                 if converted is None:
-                    raise EnvironmentProblem(f"WSL cannot see '{text}': {err.decode('utf-8', errors='replace').strip()}")
-                logger.debug("wslpath failed (%s), so '%s' is taken as %s", err.decode("utf-8", errors="replace").strip(), text, converted)
+                    raise EnvironmentProblem(
+                        f"WSL cannot see '{text}': {err.decode('utf-8', errors='replace').strip()}"
+                    )
+                logger.debug(
+                    "wslpath failed (%s), so '%s' is taken as %s",
+                    err.decode("utf-8", errors="replace").strip(),
+                    text,
+                    converted,
+                )
         else:
             converted = Path(text).resolve().as_posix()
         self._paths[text] = converted
@@ -367,12 +378,18 @@ def keep_alive(self, detached: bool = False) -> subprocess.Popen | None:
         """
         if not self.windows:
             return None
-        flags = 0x00000008 | 0x00000200 if detached else 0x08000000  # DETACHED_PROCESS | NEW_PROCESS_GROUP, else NO_WINDOW
+        flags = (
+            0x00000008 | 0x00000200 if detached else 0x08000000
+        )  # DETACHED_PROCESS | NEW_PROCESS_GROUP, else NO_WINDOW
         command = [*self._prefix(), "sleep", "infinity"]
         logger.debug("Keeping WSL running: %s", " ".join(command))
         try:
             return subprocess.Popen(
-                command, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, creationflags=flags
+                command,
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                creationflags=flags,
             )
         except FileNotFoundError as exc:
             raise EnvironmentProblem("wsl.exe was not found. Install WSL 2 (`wsl --install`)") from exc
diff --git a/src/py_doc/runtime/image.py b/src/py_doc/runtime/image.py
index d047bae..c43b4d1 100644
--- a/src/py_doc/runtime/image.py
+++ b/src/py_doc/runtime/image.py
@@ -128,7 +128,11 @@ def exists(runtime: Runtime) -> bool:
         where = "Docker in WSL" if runtime.windows else "Docker"
         raise EnvironmentProblem(
             f"{where} did not answer within {STARTUP_TIMEOUT:g} seconds. It may be stuck: "
-            + ("run `wsl --shutdown` and try again" if runtime.windows else "restart it, for example `sudo systemctl restart docker`")
+            + (
+                "run `wsl --shutdown` and try again"
+                if runtime.windows
+                else "restart it, for example `sudo systemctl restart docker`"
+            )
         ) from exc
     return found.returncode == 0
 
diff --git a/src/py_doc/runtime/setup.py b/src/py_doc/runtime/setup.py
index a775053..7c80605 100644
--- a/src/py_doc/runtime/setup.py
+++ b/src/py_doc/runtime/setup.py
@@ -131,7 +131,9 @@ def install(runtime: Runtime, user: str, run: Run = subprocess.run) -> None:
     except FileNotFoundError as exc:
         raise EnvironmentProblem(f"'{argv[0]}' was not found") from exc
     if done.returncode == UNSUPPORTED:
-        raise EnvironmentProblem("py-doc setup supports Ubuntu and Debian. Install Docker Engine yourself: https://docs.docker.com/engine/install/")
+        raise EnvironmentProblem(
+            "py-doc setup supports Ubuntu and Debian. Install Docker Engine yourself: https://docs.docker.com/engine/install/"
+        )
     if done.returncode != 0:
         raise EnvironmentProblem(f"The setup script stopped with exit status {done.returncode}. Its output is above")
 
diff --git a/src/py_doc/site/cli.py b/src/py_doc/site/cli.py
index 7f8030b..c67d9ff 100644
--- a/src/py_doc/site/cli.py
+++ b/src/py_doc/site/cli.py
@@ -28,7 +28,9 @@ def _assignment(text: str) -> tuple[str, str]:
 
 
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="py-doc site", description="A web site of the documents, made with MkDocs or Astro + Starlight")
+    parser = argparse.ArgumentParser(
+        prog="py-doc site", description="A web site of the documents, made with MkDocs or Astro + Starlight"
+    )
     actions = parser.add_subparsers(dest="action", metavar="action", required=True)
 
     def common(sub: argparse.ArgumentParser) -> None:
@@ -37,7 +39,9 @@ def common(sub: argparse.ArgumentParser) -> None:
         noise.add_argument("-q", "--quiet", action="store_true", help="Only show warnings and errors")
         noise.add_argument("-v", "--verbose", action="store_true", help="Show debug detail")
 
-    init = actions.add_parser("init", help="Make the site project (mkdocs.yml, or an Astro + Starlight project) if it is not there")
+    init = actions.add_parser(
+        "init", help="Make the site project (mkdocs.yml, or an Astro + Starlight project) if it is not there"
+    )
     common(init)
     init.add_argument("--engine", choices=SITE_ENGINES, help="The site generator (default: site.engine in py-doc.yml)")
     for name, text in (
@@ -46,11 +50,26 @@ def common(sub: argparse.ArgumentParser) -> None:
     ):
         sub = actions.add_parser(name, help=text)
         common(sub)
-        sub.add_argument("--var", action="append", default=[], metavar="NAME=VALUE", type=_assignment, help="Set a {{variable}}")
-        sub.add_argument("--condition", action="append", default=[], metavar="NAME=VALUE", type=_assignment, help="Set an [[IF:]] condition")
+        sub.add_argument(
+            "--var", action="append", default=[], metavar="NAME=VALUE", type=_assignment, help="Set a {{variable}}"
+        )
+        sub.add_argument(
+            "--condition",
+            action="append",
+            default=[],
+            metavar="NAME=VALUE",
+            type=_assignment,
+            help="Set an [[IF:]] condition",
+        )
         sub.add_argument("--no-generate", action="store_true", help="Do not run content.generators first")
         if name == "build":
-            sub.add_argument("--target", action="append", default=[], metavar="NAME", help="Build only this site of site.targets (default: every one)")
+            sub.add_argument(
+                "--target",
+                action="append",
+                default=[],
+                metavar="NAME",
+                help="Build only this site of site.targets (default: every one)",
+            )
     return parser
 
 
@@ -110,7 +129,9 @@ def _targets(config: ProjectConfig, chosen: list[str]) -> list[tuple[str | None,
     for name, config_file in picked:
         out = engine.site_dir(config_file)
         if out in outs:
-            raise ConfigError(f"site.targets {outs[out]} and {name} both build to {out}. Give each config file its own site_dir")
+            raise ConfigError(
+                f"site.targets {outs[out]} and {name} both build to {out}. Give each config file its own site_dir"
+            )
         outs[out] = name
     return picked
 
@@ -119,7 +140,10 @@ def _init(config: ProjectConfig, chosen: str | None) -> int:
     site = config.site
     name = chosen or (site.engine if site else None)
     if name is None:
-        print("Error: say which site to make: --engine mkdocs or --engine starlight, or set site.engine in py-doc.yml", file=sys.stderr)
+        print(
+            "Error: say which site to make: --engine mkdocs or --engine starlight, or set site.engine in py-doc.yml",
+            file=sys.stderr,
+        )
         return 1
     if site is not None and chosen and site.engine != chosen:
         print(f"Error: py-doc.yml says site.engine: {site.engine}, not {chosen}", file=sys.stderr)
@@ -133,7 +157,9 @@ def _init(config: ProjectConfig, chosen: str | None) -> int:
     if not written:
         print(f"The {name} site in {root} is already there. Nothing was changed")
     if site is None:
-        print(f"Add this to {config.root / 'py-doc.yml'} to fill it:\n\nsite:\n  engine: {name}\n  dir: {root.relative_to(config.root).as_posix()}\n")
+        print(
+            f"Add this to {config.root / 'py-doc.yml'} to fill it:\n\nsite:\n  engine: {name}\n  dir: {root.relative_to(config.root).as_posix()}\n"
+        )
     else:
         print("Next: py-doc site build")
     return 0
diff --git a/src/py_doc/site/engines.py b/src/py_doc/site/engines.py
index 46f6ef0..533b7eb 100644
--- a/src/py_doc/site/engines.py
+++ b/src/py_doc/site/engines.py
@@ -161,7 +161,9 @@ def write_nav(self, sections: list[NavSection], pages: dict[str, str] | None = N
             nav.append({"Home": "index.md"})
         for section in sections:
             entries = _mkdocs_entries(section.pages)
-            nav.append(entries[0] if len(entries) == 1 and not section.nested else {section.title: entries})  # one page: no section
+            nav.append(
+                entries[0] if len(entries) == 1 and not section.nested else {section.title: entries}
+            )  # one page: no section
         nav += [{title: path} for title, path in (pages or {}).items()]
         path = self.root / MKDOCS_NAV
         header = "# Written by py-doc site from py-doc.yml. mkdocs.yml takes it in with INHERIT: py-doc-nav.yml\n"
@@ -174,7 +176,9 @@ def check(self, config_file: str | None = None) -> list[str]:
             return [f"{path} is not there. site.targets names it"]
         config = self._config(config_file)
         if config_file and self.root / str(config.get("docs_dir") or "docs") != self.content:
-            return [f"{path} reads its pages from {config.get('docs_dir')}, but py-doc writes them to {self.content}. Leave docs_dir to {self.marker}"]
+            return [
+                f"{path} reads its pages from {config.get('docs_dir')}, but py-doc writes them to {self.content}. Leave docs_dir to {self.marker}"
+            ]
         if MKDOCS_NAV in config.get("INHERITS", []):
             return []
         if "nav" in config:
@@ -189,13 +193,21 @@ def build(self, runtime: Runtime, config_file: str | None = None) -> Path:
         config = self.root / (config_file or self.marker)
         if config_file and not config.is_file():
             raise ConversionError(f"{config} is not there, so that site cannot be built. site.targets names it")
-        runtime.run(["mkdocs", "build", "--config-file", config], mounts=[Mount(self.root, writable=True)], workdir=self.root, timeout=TIMEOUT)
+        runtime.run(
+            ["mkdocs", "build", "--config-file", config],
+            mounts=[Mount(self.root, writable=True)],
+            workdir=self.root,
+            timeout=TIMEOUT,
+        )
         return self.site_dir(config_file)
 
 
 def _mkdocs_entries(items: list[NavPage | NavSection]) -> list[dict]:
     """A page as {title: path}, a folder as {title: [its entries]}: with navigation.indexes, its index page leads it."""
-    return [{item.title: _mkdocs_entries(item.pages)} if isinstance(item, NavSection) else {item.title: item.path} for item in items]
+    return [
+        {item.title: _mkdocs_entries(item.pages)} if isinstance(item, NavSection) else {item.title: item.path}
+        for item in items
+    ]
 
 
 MKDOCS_YML = """\
@@ -266,7 +278,9 @@ def write_nav(self, sections: list[NavSection], pages: dict[str, str] | None = N
         sidebar = []
         for section in sections:
             # A flat document lists its folder; one with folders lists its pages, so a group takes its index page's title
-            items = _starlight_items(section.pages) if section.nested else [{"autogenerate": {"directory": section.folder}}]
+            items = (
+                _starlight_items(section.pages) if section.nested else [{"autogenerate": {"directory": section.folder}}]
+            )
             sidebar.append({"label": section.title, "items": items})
         for title, page in (pages or {}).items():
             link = "/" + page.removesuffix(".md").removesuffix("index").strip("/")
@@ -291,7 +305,14 @@ def build(self, runtime: Runtime, config_file: str | None = None) -> Path:
         mounts = [Mount(self.root, writable=True)]
         env = {"ASTRO_TELEMETRY_DISABLED": "1"}
         # npm install keeps to package-lock.json when it matches package.json, and brings it up to date when not
-        runtime.run(["npm", "install", "--no-audit", "--no-fund"], mounts=mounts, workdir=self.root, network=True, env=env, timeout=TIMEOUT)
+        runtime.run(
+            ["npm", "install", "--no-audit", "--no-fund"],
+            mounts=mounts,
+            workdir=self.root,
+            network=True,
+            env=env,
+            timeout=TIMEOUT,
+        )
         runtime.run(["npx", "astro", "build"], mounts=mounts, workdir=self.root, env=env, timeout=TIMEOUT)
         return self.root / "dist"
 
diff --git a/src/py_doc/site/pages.py b/src/py_doc/site/pages.py
index dda7d94..2b0eda8 100644
--- a/src/py_doc/site/pages.py
+++ b/src/py_doc/site/pages.py
@@ -130,12 +130,16 @@ def _pages_of(config: ProjectConfig, name: str, runtime, variables: dict, condit
     sources = [replace(s, heading_offset=0, page_break=False) for s in sources if s.include]
     joined = join_sources(sources, {**doc.variables, **variables}, {**doc.conditions, **conditions}, doc.id)
     metadata = _combine_metadata(doc, joined.metadata, joined.first_heading, config.root)
-    slugs = _slugs(name, [file for file, _ in joined.parts], [s for s in doc.sources if s.include and s.structurizr is None])
+    slugs = _slugs(
+        name, [file for file, _ in joined.parts], [s for s in doc.sources if s.include and s.structurizr is None]
+    )
     pages: list[Page] = []
     for order, ((file, text), name_) in enumerate(zip(joined.parts, slugs, strict=True), start=1):
         title = first_heading(text) or (metadata.title if order == 1 else file.stem)
         rendered = render_parts([(file, text)], "html", runtime, mermaid=config.mermaid)
-        pages.append(Page(name, file, name_, title, order, rendered.markdown, rendered.pictures, version=metadata.version))
+        pages.append(
+            Page(name, file, name_, title, order, rendered.markdown, rendered.pictures, version=metadata.version)
+        )
     if pages:
         pages[0].meta = page_meta(metadata)
     return metadata.title or name, pages
@@ -287,13 +291,21 @@ def _convert(pages: list[Page], engine: str, runtime: Runtime) -> None:
         filters = " ".join(f"--lua-filter '{runtime.container_path(RESOURCES / name)}'" for name in FILTERS)
         for number, page in enumerate(pages):
             (work / f"{number}.md").write_text(page.markdown, encoding="utf-8", newline="\n")
-            source, target = runtime.container_path(work / f"{number}.md"), runtime.container_path(work / f"{number}.out")
+            source, target = (
+                runtime.container_path(work / f"{number}.md"),
+                runtime.container_path(work / f"{number}.out"),
+            )
             lines.append(
                 f"pandoc '{source}' --from={INPUT_FORMAT} {filters} -M site-engine={engine} "
                 f"--to={OUTPUT_FORMAT} --wrap=none --output '{target}'"
             )
         (work / "pages.sh").write_text("\n".join(lines) + "\n", encoding="utf-8", newline="\n")
-        result = runtime.run(["sh", work / "pages.sh"], mounts=[Mount(RESOURCES), Mount(work, writable=True)], workdir=work, timeout=TIMEOUT)
+        result = runtime.run(
+            ["sh", work / "pages.sh"],
+            mounts=[Mount(RESOURCES), Mount(work, writable=True)],
+            workdir=work,
+            timeout=TIMEOUT,
+        )
         for line in result.stderr.splitlines():
             if line.startswith("[WARNING]"):
                 logger.warning(f"pandoc: {line.removeprefix('[WARNING]').strip()}")
@@ -325,14 +337,18 @@ def _write(pages: list[Page], engine: Engine, extra: dict[Path, bytes] | None =
             front.update(page.meta)  # MkDocs makes every key page.meta, for a theme or a plugin
         header = "---\n" + yaml.safe_dump(front, allow_unicode=True, sort_keys=False) + "---\n\n"
         files[content / page.path] = (header + text.rstrip() + "\n").encode("utf-8")
-        files[content / page.document / ".gitignore"] = b"# Written by py-doc site: built from the sources, so not kept in Git\n*\n"
+        files[content / page.document / ".gitignore"] = (
+            b"# Written by py-doc site: built from the sources, so not kept in Git\n*\n"
+        )
 
     def relative(path: Path) -> str:
         return path.relative_to(engine.root).as_posix()
 
     clashes = [path for path in files if path.exists() and relative(path) not in before]
     if clashes:
-        raise ConversionError(f"{clashes[0]} is already there and py-doc did not write it, so it is left alone. Move it, or leave the document out of site.documents")
+        raise ConversionError(
+            f"{clashes[0]} is already there and py-doc did not write it, so it is left alone. Move it, or leave the document out of site.documents"
+        )
     for old in sorted(before - {relative(p) for p in files}):
         (engine.root / old).unlink(missing_ok=True)  # a page or picture of an earlier run that is gone now
     for path, data in files.items():
diff --git a/src/py_doc/template_check.py b/src/py_doc/template_check.py
index 37a6376..479bd38 100644
--- a/src/py_doc/template_check.py
+++ b/src/py_doc/template_check.py
@@ -124,7 +124,9 @@ def _language(style) -> str | None:
     return lang.get(qn("w:val")) if lang is not None else None
 
 
-def _check_word(document, report: TemplateReport, prefix: str = "Replace-with-", marker_text: str = "[[INSERTCONTENT]]") -> None:
+def _check_word(
+    document, report: TemplateReport, prefix: str = "Replace-with-", marker_text: str = "[[INSERTCONTENT]]"
+) -> None:
     styles = styles_of(document)
     counts = {kind: sum(1 for k, _ in styles.values() if k == kind) for kind in ("paragraph", "character", "table")}
     report.add(
@@ -151,7 +153,9 @@ def _check_word(document, report: TemplateReport, prefix: str = "Replace-with-",
         report.add("WARN", "Pandoc styles", f"Not in the template, so pandoc's defaults are used: {', '.join(absent)}")
 
     if "Caption" not in styles:
-        report.add("WARN", "Caption style", "No 'Caption' style: [[CAPTION:Figure]] lines fall back to the default look")
+        report.add(
+            "WARN", "Caption style", "No 'Caption' style: [[CAPTION:Figure]] lines fall back to the default look"
+        )
     elif styles["Caption"][0] != "paragraph":
         report.add("FAIL", "Caption style", f"Caption must be a paragraph style, not a {styles['Caption'][0]} style")
     elif _bold(styles["Caption"][1]):
@@ -160,14 +164,20 @@ def _check_word(document, report: TemplateReport, prefix: str = "Replace-with-",
     if "Table Grid" not in styles:
         report.add("WARN", "Table style", "No 'Table Grid' table style: tables use the Word default")
     elif styles["Table Grid"][0] != "table":
-        report.add("FAIL", "Table style", f"'Table Grid' exists but is a {styles['Table Grid'][0]} style, not a table style")
+        report.add(
+            "FAIL", "Table style", f"'Table Grid' exists but is a {styles['Table Grid'][0]} style, not a table style"
+        )
 
     for name in ("Source Code", "Verbatim Char"):
         if name in styles and not styles[name][1].font.no_proof:
             report.add("INFO", "Code spelling", f"{name} has spell-check on")
 
     soft = [n for n, (kind, s) in styles.items() if kind == "paragraph" and n.lower().startswith("heading")]
-    loose = [n for n in soft if not (styles[n][1].paragraph_format.keep_with_next and styles[n][1].paragraph_format.keep_together)]
+    loose = [
+        n
+        for n in soft
+        if not (styles[n][1].paragraph_format.keep_with_next and styles[n][1].paragraph_format.keep_together)
+    ]
     if not soft:
         report.add("WARN", "Headings", "No heading styles")
     elif loose:
@@ -279,7 +289,12 @@ def inventory(path: Path) -> list[tuple[str, ...]]:
             rows.append((type_name, name, "bold" if _bold(style) else "", following.name if following else ""))
         return sorted(rows)
     return [
-        (layout.name, ", ".join(sorted({str(p.placeholder_format.type).split(".")[-1].split(" ")[0] for p in layout.placeholders})))
+        (
+            layout.name,
+            ", ".join(
+                sorted({str(p.placeholder_format.type).split(".")[-1].split(" ")[0] for p in layout.placeholders})
+            ),
+        )
         for layout in opened.slide_layouts
     ]
 
@@ -299,7 +314,9 @@ def _definition(style) -> tuple[str, ...]:
         "size": size,
         "bold": font.bold,
         "italic": font.italic,
-        "colour": str(font.color.rgb) if font.color is not None and font.color.type is not None and font.color.rgb else None,
+        "colour": str(font.color.rgb)
+        if font.color is not None and font.color.type is not None and font.color.rgb
+        else None,
         "keep with next": fmt.keep_with_next if fmt is not None else None,
         "keep together": fmt.keep_together if fmt is not None else None,
         "space before": fmt.space_before.pt if fmt is not None and fmt.space_before else None,
@@ -331,8 +348,12 @@ def compare(first: Path, second: Path) -> list[tuple[str, str, str]]:
                     changed = sorted(set(one) ^ set(two))
                     rows.append(("differs", name, "; ".join(changed)))
         return rows
-    left = {layout.name: sorted(str(p.placeholder_format.type) for p in layout.placeholders) for layout in a.slide_layouts}
-    right = {layout.name: sorted(str(p.placeholder_format.type) for p in layout.placeholders) for layout in b.slide_layouts}
+    left = {
+        layout.name: sorted(str(p.placeholder_format.type) for p in layout.placeholders) for layout in a.slide_layouts
+    }
+    right = {
+        layout.name: sorted(str(p.placeholder_format.type) for p in layout.placeholders) for layout in b.slide_layouts
+    }
     for name in sorted(left.keys() | right.keys()):
         if name not in right:
             rows.append(("only in first", name, ""))
diff --git a/src/py_doc/template_cli.py b/src/py_doc/template_cli.py
index 69ced7e..c2ec9c9 100644
--- a/src/py_doc/template_cli.py
+++ b/src/py_doc/template_cli.py
@@ -11,14 +11,20 @@
 from .errors import ConversionError
 from .template_check import LEVELS, check_template, compare, inventory, kind_of, usage
 
+
 def _error(message: str) -> None:
     print(f"Error: {message}", file=sys.stderr)
 
 
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="py-doc template", description="Check and inspect Word and PowerPoint templates")
+    parser = argparse.ArgumentParser(
+        prog="py-doc template", description="Check and inspect Word and PowerPoint templates"
+    )
     commands = parser.add_subparsers(dest="action", metavar="action", required=True)
-    for name, help_text in (("check", "Report what a template lacks for the pandoc pipeline"), ("show", "List its styles or layouts")):
+    for name, help_text in (
+        ("check", "Report what a template lacks for the pandoc pipeline"),
+        ("show", "List its styles or layouts"),
+    ):
         sub = commands.add_parser(name, help=help_text, description=help_text)
         sub.add_argument("template", type=Path, help="A .docx, .dotx, .pptx or .potx file")
         noise = sub.add_mutually_exclusive_group()
@@ -26,13 +32,27 @@ def build_parser() -> argparse.ArgumentParser:
         verbose = "Show debug detail, and the INFO findings too" if name == "check" else "Show debug detail"
         noise.add_argument("-v", "--verbose", action="store_true", help=verbose)
         if name == "check":
-            sub.add_argument("--strict", action="store_true", help="Exit with status 1 for warnings as well as failures")
-            sub.add_argument("--prefix", default="Replace-with-", help="The placeholder_prefix of the template (default: Replace-with-)")
-            sub.add_argument("--marker", default="[[INSERTCONTENT]]", help="The marker line where the body goes (default: [[INSERTCONTENT]])")
-    diff = commands.add_parser("diff", help="Compare the styles (or layouts) of two templates", description="Compare two templates")
+            sub.add_argument(
+                "--strict", action="store_true", help="Exit with status 1 for warnings as well as failures"
+            )
+            sub.add_argument(
+                "--prefix",
+                default="Replace-with-",
+                help="The placeholder_prefix of the template (default: Replace-with-)",
+            )
+            sub.add_argument(
+                "--marker",
+                default="[[INSERTCONTENT]]",
+                help="The marker line where the body goes (default: [[INSERTCONTENT]])",
+            )
+    diff = commands.add_parser(
+        "diff", help="Compare the styles (or layouts) of two templates", description="Compare two templates"
+    )
     diff.add_argument("first", type=Path, help="The template to start from")
     diff.add_argument("second", type=Path, help="The template to compare it with")
-    count = commands.add_parser("usage", help="Count the styles a Word file uses", description="Count the styles a Word file uses")
+    count = commands.add_parser(
+        "usage", help="Count the styles a Word file uses", description="Count the styles a Word file uses"
+    )
     count.add_argument("document", type=Path, help="A .docx file")
     for sub in (diff, count):
         noise = sub.add_mutually_exclusive_group()
diff --git a/src/py_doc/tools_cli.py b/src/py_doc/tools_cli.py
index 9f53918..b40cda3 100644
--- a/src/py_doc/tools_cli.py
+++ b/src/py_doc/tools_cli.py
@@ -159,7 +159,9 @@ def run_setup(argv: Sequence[str] | None = None, *, run=None, ask=input) -> int:
     )
     parser.add_argument("-y", "--yes", action="store_true", help="Do not ask first")
     parser.add_argument("--dry-run", action="store_true", help="Show the script that would run, and run nothing")
-    parser.add_argument("--distro", help="The WSL distribution to set up (default: runtime.wsl_distro, else the default one)")
+    parser.add_argument(
+        "--distro", help="The WSL distribution to set up (default: runtime.wsl_distro, else the default one)"
+    )
     _common(parser)
     args = parser.parse_args(argv)
     configure_logging(quiet=args.quiet, verbose=args.verbose)
@@ -222,6 +224,8 @@ def _setup(runtime: Runtime, args: argparse.Namespace, run, ask) -> int:
             + ". Close every WSL window, run `wsl --shutdown`, and run `py-doc doctor`"
         )
     else:
-        print("Docker is installed. Log out and in again so the docker group applies (or run `newgrp docker`), then run `py-doc doctor`.")
+        print(
+            "Docker is installed. Log out and in again so the docker group applies (or run `newgrp docker`), then run `py-doc doctor`."
+        )
         return 0
     return 2
diff --git a/src/py_doc/watch.py b/src/py_doc/watch.py
index b7f459d..64ac8f0 100644
--- a/src/py_doc/watch.py
+++ b/src/py_doc/watch.py
@@ -95,8 +95,14 @@ def do_GET(self):  # noqa: N802 (the name http.server calls)
                 script = RELOAD.replace("__VERSION__", str(version))
                 return self._send(200, "text/html; charset=utf-8", page.replace("</body>", script + "</body>", 1))
             if not name:
-                links = "".join(f'<li><a href="/{html.escape(urllib.parse.quote(n))}.html">{html.escape(n)}</a></li>' for n in pages)
-                return self._send(200, "text/html; charset=utf-8", f"<!doctype html><title>{html.escape(state.title)}</title><ul>{links}</ul>")
+                links = "".join(
+                    f'<li><a href="/{html.escape(urllib.parse.quote(n))}.html">{html.escape(n)}</a></li>' for n in pages
+                )
+                return self._send(
+                    200,
+                    "text/html; charset=utf-8",
+                    f"<!doctype html><title>{html.escape(state.title)}</title><ul>{links}</ul>",
+                )
             self._send(404, "text/plain", f"No page {name}")
 
         def _send(self, code: int, kind: str, body: str) -> None:
@@ -116,8 +122,15 @@ def log_message(self, *args) -> None:
     return server
 
 
-def watch(build: Build, errors: tuple[type[Exception], ...], port: int = 0, open_browser: bool = True,
-          stop: threading.Event | None = None, interval: float = INTERVAL, title: str = "py-doc preview") -> int:
+def watch(
+    build: Build,
+    errors: tuple[type[Exception], ...],
+    port: int = 0,
+    open_browser: bool = True,
+    stop: threading.Event | None = None,
+    interval: float = INTERVAL,
+    title: str = "py-doc preview",
+) -> int:
     """Build, serve, and build again on every change, until Ctrl+C or ``stop``. Returns the exit status."""
     state, stop = State(title=title), stop or threading.Event()
 
diff --git a/tests/fake_vale.py b/tests/fake_vale.py
index a62c56d..7bf96c3 100644
--- a/tests/fake_vale.py
+++ b/tests/fake_vale.py
@@ -6,7 +6,7 @@
 import sys
 from pathlib import Path
 
-SCRIPT = '''#!{python}
+SCRIPT = """#!{python}
 import json, sys
 from pathlib import Path
 args = sys.argv[1:]
@@ -25,7 +25,7 @@
 files = [a for a in args if not a.startswith("-")]
 canned = json.loads(Path({canned!r}).read_text()) if Path({canned!r}).exists() else {{}}
 print(json.dumps({{f: canned.get(Path(f).name, []) for f in files}}))
-'''
+"""
 
 
 def install(folder: Path, monkeypatch, *, canned: dict | None = None, version="3.9.1", crash="", sync_code=0) -> Path:
@@ -37,7 +37,9 @@ def install(folder: Path, monkeypatch, *, canned: dict | None = None, version="3
     data.write_text(json.dumps(canned or {}))
     log = folder / "calls.log"
     script = folder / ("vale.bat" if sys.platform == "win32" else "vale")
-    body = SCRIPT.format(python=sys.executable, log=str(log), canned=str(data), version=version, crash=crash, sync_code=sync_code)
+    body = SCRIPT.format(
+        python=sys.executable, log=str(log), canned=str(data), version=version, crash=crash, sync_code=sync_code
+    )
     if sys.platform == "win32":
         (folder / "vale.py").write_text(body.split("\n", 1)[1])
         script.write_text(f'@"{sys.executable}" "%~dp0vale.py" %*\n')
@@ -48,5 +50,19 @@ def install(folder: Path, monkeypatch, *, canned: dict | None = None, version="3
     return log
 
 
-def alert(check="PyDoc.WeaselWords", line=1, message="'very' is a weasel word.", severity="suggestion", span=(3, 6), action=None):
-    return {"Check": check, "Line": line, "Message": message, "Severity": severity, "Span": list(span), "Action": action or {"Name": "", "Params": None}}
+def alert(
+    check="PyDoc.WeaselWords",
+    line=1,
+    message="'very' is a weasel word.",
+    severity="suggestion",
+    span=(3, 6),
+    action=None,
+):
+    return {
+        "Check": check,
+        "Line": line,
+        "Message": message,
+        "Severity": severity,
+        "Span": list(span),
+        "Action": action or {"Name": "", "Params": None},
+    }
diff --git a/tests/test_analysis.py b/tests/test_analysis.py
index d6ee41e..b592e39 100644
--- a/tests/test_analysis.py
+++ b/tests/test_analysis.py
@@ -15,12 +15,21 @@ class TestStats:
     def test_counts_prose_and_blocks(self):
         text = "---\ntitle: x y z\n---\n\n# Title\n\nOne two [three](a.md).\n\n```\nnot words here\n```\n\n| A | B |\n|---|---|\n| c | d |\n\n![alt](p.png)\n"
         stats = text_stats(text)
-        assert (stats.words, stats.headings, stats.code_blocks, stats.tables, stats.images, stats.links) == (9, 1, 1, 1, 1, 1)  # the alt text counts
+        assert (stats.words, stats.headings, stats.code_blocks, stats.tables, stats.images, stats.links) == (
+            9,
+            1,
+            1,
+            1,
+            1,
+            1,
+        )  # the alt text counts
 
     def test_the_command_reports_each_document_and_the_total(self, tmp_path, monkeypatch, capsys):
         (tmp_path / "a.md").write_text("# A\n\nOne two.\n", encoding="utf-8")
         (tmp_path / "b.md").write_text("# B\n\nThree.\n", encoding="utf-8")
-        (tmp_path / "py-doc.yml").write_text("documents:\n  guide: {sources: [a.md, b.md]}\n  notes: {sources: [b.md]}\n", encoding="utf-8")
+        (tmp_path / "py-doc.yml").write_text(
+            "documents:\n  guide: {sources: [a.md, b.md]}\n  notes: {sources: [b.md]}\n", encoding="utf-8"
+        )
         monkeypatch.chdir(tmp_path)
         assert main(["stats", "--format", "json", "--lint"]) == 0
         data = json.loads(capsys.readouterr().out)
diff --git a/tests/test_app.py b/tests/test_app.py
index 2f17ae9..823e722 100644
--- a/tests/test_app.py
+++ b/tests/test_app.py
@@ -1,207 +1,213 @@
-"""The unified py-doc command: build and the delegated commands."""
-
-from __future__ import annotations
-
-import pytest
-from docx_helpers import texts
-from py_doc.app import main
-
-
-pytestmark = pytest.mark.usefixtures("pandoc_runtime")
-
-
-@pytest.fixture
-def project(tmp_path, monkeypatch):
-    (tmp_path / "a.md").write_text("# Alpha\n\nrun in order to test\n", encoding="utf-8")
-    (tmp_path / "b.md").write_text("# Beta\n", encoding="utf-8")
-    (tmp_path / "py-doc.yml").write_text(
-        "documents:\n  alpha: {sources: [a.md]}\n  beta: {sources: [b.md], outputs: {docx: {}, pptx: {}}}\n",
-        encoding="utf-8",
-    )
-    monkeypatch.chdir(tmp_path)
-    return tmp_path
-
-
-class TestBuild:
-    def test_builds_every_document(self, project, capsys):
-        assert main(["build"]) == 0
-        assert texts(project / "build" / "alpha.docx")[0] == "Alpha"
-        assert (project / "build" / "beta.docx").exists() and (project / "build" / "beta.pptx").exists()
-        assert "2 of 2 document(s) built" in capsys.readouterr().err
-
-    def test_builds_only_the_named_documents(self, project):
-        assert main(["build", "beta"]) == 0
-        assert not (project / "build" / "alpha.docx").exists()
-
-    def test_format_option_limits_the_formats(self, project):
-        assert main(["build", "beta", "-f", "pptx"]) == 0
-        assert not (project / "build" / "beta.docx").exists() and (project / "build" / "beta.pptx").exists()
-
-    def test_config_is_found_in_a_parent_folder(self, project, monkeypatch):
-        (project / "sub").mkdir()
-        monkeypatch.chdir(project / "sub")
-        assert main(["build", "alpha"]) == 0
-        assert (project / "build" / "alpha.docx").exists()
-
-    def test_explicit_config(self, project, tmp_path, monkeypatch):
-        monkeypatch.chdir(tmp_path.parent)
-        assert main(["build", "-c", str(project / "py-doc.yml"), "alpha"]) == 0
-
-    def test_no_config_is_a_clear_error(self, tmp_path, monkeypatch, capsys):
-        empty = tmp_path / "empty"
-        empty.mkdir()
-        monkeypatch.chdir(empty)
-        monkeypatch.setattr("py_doc.app.find_config", lambda start: None)
-        assert main(["build"]) == 1
-        assert "No py-doc.yml found" in capsys.readouterr().err
-
-    def test_unknown_document_is_an_error_before_anything_is_built(self, project, capsys):
-        assert main(["build", "alpha", "nope"]) == 1
-        assert "Unknown document(s): nope. Defined: alpha, beta" in capsys.readouterr().err
-        assert not (project / "build").exists()
-
-    def test_bad_config_is_reported_with_its_place(self, project, capsys):
-        (project / "py-doc.yml").write_text("documents:\n  a: {}\n", encoding="utf-8")
-        assert main(["build"]) == 1
-        assert "documents.a.sources must be a list" in capsys.readouterr().err
-
-    def test_config_without_documents_is_an_error(self, project, capsys):
-        (project / "py-doc.yml").write_text("project: {name: x}\n", encoding="utf-8")
-        assert main(["build"]) == 1
-        assert "defines no documents" in capsys.readouterr().err
-
-    def test_one_failing_document_does_not_stop_the_others(self, project, capsys):
-        (project / "a.md").write_bytes(b"caf\xe9\n")
-        assert main(["build"]) == 1
-        err = capsys.readouterr().err
-        assert "alpha:" in err and "not valid UTF-8" in err
-        assert "1 of 2 document(s) built, 1 failed" in err
-        assert (project / "build" / "beta.docx").exists()
-
-    def test_missing_source_names_the_document(self, project, capsys):
-        (project / "b.md").unlink()
-        assert main(["build", "beta"]) == 1
-        assert "beta: Source for document 'beta' not found" in capsys.readouterr().err
-
-    def test_legacy_build_file_builds_without_a_config(self, project, capsys):
-        (project / "deck.yaml").write_text(
-            "meta: {title: Deck, version: 2.0.0}\n"
-            "cli: {output: out/Deck.pptx, verbose: false, keep-temps: false}\n"
-            "entries: [{file: a.md}, {file: b.md, section: Second, heading_offset: 1}]\n",
-            encoding="utf-8",
-        )
-        (project / "paper.yaml").write_text(
-            "meta: {title: Paper, version: 0.1.0}\n"
-            "cli: {emit-docx: true, output: Paper.docx, plantuml-jar-path: x.jar}\n"
-            "entries: [{file: a.md, heading_offset: 0, page_break: false}]\n",
-            encoding="utf-8",
-        )
-        assert main(["build", "--legacy", "deck.yaml"]) == 0
-        assert (project / "out" / "Deck-2_0_0.pptx").exists()
-        assert main(["build", "--legacy", "paper.yaml"]) == 0
-        assert "Alpha" in texts(project / "Paper-0_1_0.docx")
-        assert "cli.plantuml-jar-path was left out" in capsys.readouterr().err
-
-    def test_legacy_option_refuses_other_yaml(self, project, capsys):
-        assert main(["build", "--legacy", "py-doc.yml"]) == 1
-        assert "is not a createdocs build file" in capsys.readouterr().err
-
-    def test_quiet_hides_progress(self, project, capsys):
-        assert main(["build", "alpha", "-q"]) == 0
-        assert capsys.readouterr().err == ""
-
-
-class TestDelegation:
-    def test_docx(self, project):
-        assert main(["docx", "a.md", "-o", "x.docx"]) == 0
-        assert texts(project / "x.docx")[0] == "Alpha"
-
-    def test_slides(self, project):
-        assert main(["slides", "a.md"]) == 0
-        assert (project / "a.pptx").exists()
-
-    def test_lint_uses_the_project_configuration(self, project, capsys):
-        assert main(["lint", "a.md"]) == 0
-        assert "DOC002" in capsys.readouterr().out
-        (project / "py-doc.yml").write_text("lint:\n  rules: {DOC002: error}\n", encoding="utf-8")
-        assert main(["lint", "a.md"]) == 1
-
-    def test_failures_keep_their_exit_status(self, project):
-        assert main(["docx", "missing.md"]) == 1
-
-    def test_no_command_is_a_usage_error(self, capsys):
-        with pytest.raises(SystemExit) as exc:
-            main([])
-        assert exc.value.code == 2
-
-    def test_version(self, capsys):
-        import py_doc
-
-        with pytest.raises(SystemExit):
-            main(["--version"])
-        assert capsys.readouterr().out.strip() == f"py-doc {py_doc.__version__}"
-
-
-@pytest.mark.parametrize(
-    ("command", "usage", "shown"),
-    [
-        (["docx"], "usage: py-doc docx", "py-doc docx guide.md -t Template.docx"),
-        (["slides"], "usage: py-doc slides", "--split-level 1"),
-        (["lint"], "usage: py-doc lint", "py-doc lint docs README.md"),
-        (["build"], "usage: py-doc build", "one legacy createdocs build file"),
-        (["migrate"], "usage: py-doc migrate", "py-doc migrate docs --check"),
-        (["new"], "usage: py-doc new", "py-doc new --scan --start 100"),
-        ([], "usage: py-doc ", "`py-doc COMMAND --help`"),
-    ],
-)
-def test_the_help_names_the_command_and_shows_what_it_does(command, usage, shown, capsys):
-    with pytest.raises(SystemExit):
-        main([*command, "--help"])
-    out = capsys.readouterr().out
-    assert out.startswith(usage) and shown in out
-
-
-def test_the_old_commands_keep_their_own_name_in_the_help(capsys):
-    from py_doc.cli import run_docx
-    from py_doc.slides_cli import run_slides
-
-    for run, name in ((run_docx, "py-doc2docx"), (run_slides, "py-doc2slides")):
-        with pytest.raises(SystemExit):
-            run(["--help"], legacy=True)
-        assert capsys.readouterr().out.startswith(f"usage: {name}")
-
-
-class TestPipeline:
-    def test_lint_errors_stop_the_build_and_strict_stops_on_warnings(self, project, capsys):
-        (project / "a.md").write_text("# Alpha\n\n```\nnever closed\n", encoding="utf-8")
-        assert main(["build", "alpha", "--lint"]) == 1
-        assert "nothing was built" in capsys.readouterr().err and not (project / "build").exists()
-        (project / "a.md").write_text("# Alpha\n\nWe run in order to test.\n", encoding="utf-8")
-        assert main(["build", "alpha", "--lint"]) == 0
-        assert main(["build", "alpha", "--strict"]) == 1
-
-    def test_the_lint_report_and_the_steps_in_the_build_report(self, project):
-        import json
-
-        assert main(["build", "alpha", "--lint", "--lint-report", "out/lint.sarif", "--report", "out/report.json"]) == 0
-        sarif = json.loads((project / "out" / "lint.sarif").read_text(encoding="utf-8"))
-        assert sarif["version"] == "2.1.0" and sarif["runs"][0]["results"][0]["ruleId"] == "DOC002"
-        steps = json.loads((project / "out" / "report.json").read_text(encoding="utf-8"))["steps"]
-        assert [(s["step"], s["status"]) for s in steps] == [("lint", "ok"), ("documents", "ok"), ("verify", "ok")]
-
-    def test_build_settings_in_py_doc_yml(self, project, capsys):
-        with open(project / "py-doc.yml", "a", encoding="utf-8") as file:
-            file.write("build: {lint: strict, site: true}\n")
-        assert main(["build", "alpha"]) == 1  # strict: the wordy phrase is a warning
-        assert main(["build", "alpha", "--no-lint"]) == 1  # then the site: there is no site section
-        assert "has no site section" in capsys.readouterr().err
-        assert main(["build", "alpha", "--no-lint", "--no-site"]) == 0

-
-
-@pytest.mark.parametrize("words, usage", [(["help"], "usage: py-doc "), (["help", "build"], "usage: py-doc build"), (["lint", "help"], "usage: py-doc lint")])
-def test_help_as_a_word(words, usage, tmp_path, monkeypatch, capsys):
-    monkeypatch.chdir(tmp_path)
-    with pytest.raises(SystemExit) as stop:
-        main(words)
-    assert stop.value.code == 0 and usage in capsys.readouterr().out
-
+"""The unified py-doc command: build and the delegated commands."""
+
+from __future__ import annotations
+
+import pytest
+from docx_helpers import texts
+from py_doc.app import main
+
+
+pytestmark = pytest.mark.usefixtures("pandoc_runtime")
+
+
+@pytest.fixture
+def project(tmp_path, monkeypatch):
+    (tmp_path / "a.md").write_text("# Alpha\n\nrun in order to test\n", encoding="utf-8")
+    (tmp_path / "b.md").write_text("# Beta\n", encoding="utf-8")
+    (tmp_path / "py-doc.yml").write_text(
+        "documents:\n  alpha: {sources: [a.md]}\n  beta: {sources: [b.md], outputs: {docx: {}, pptx: {}}}\n",
+        encoding="utf-8",
+    )
+    monkeypatch.chdir(tmp_path)
+    return tmp_path
+
+
+class TestBuild:
+    def test_builds_every_document(self, project, capsys):
+        assert main(["build"]) == 0
+        assert texts(project / "build" / "alpha.docx")[0] == "Alpha"
+        assert (project / "build" / "beta.docx").exists() and (project / "build" / "beta.pptx").exists()
+        assert "2 of 2 document(s) built" in capsys.readouterr().err
+
+    def test_builds_only_the_named_documents(self, project):
+        assert main(["build", "beta"]) == 0
+        assert not (project / "build" / "alpha.docx").exists()
+
+    def test_format_option_limits_the_formats(self, project):
+        assert main(["build", "beta", "-f", "pptx"]) == 0
+        assert not (project / "build" / "beta.docx").exists() and (project / "build" / "beta.pptx").exists()
+
+    def test_config_is_found_in_a_parent_folder(self, project, monkeypatch):
+        (project / "sub").mkdir()
+        monkeypatch.chdir(project / "sub")
+        assert main(["build", "alpha"]) == 0
+        assert (project / "build" / "alpha.docx").exists()
+
+    def test_explicit_config(self, project, tmp_path, monkeypatch):
+        monkeypatch.chdir(tmp_path.parent)
+        assert main(["build", "-c", str(project / "py-doc.yml"), "alpha"]) == 0
+
+    def test_no_config_is_a_clear_error(self, tmp_path, monkeypatch, capsys):
+        empty = tmp_path / "empty"
+        empty.mkdir()
+        monkeypatch.chdir(empty)
+        monkeypatch.setattr("py_doc.app.find_config", lambda start: None)
+        assert main(["build"]) == 1
+        assert "No py-doc.yml found" in capsys.readouterr().err
+
+    def test_unknown_document_is_an_error_before_anything_is_built(self, project, capsys):
+        assert main(["build", "alpha", "nope"]) == 1
+        assert "Unknown document(s): nope. Defined: alpha, beta" in capsys.readouterr().err
+        assert not (project / "build").exists()
+
+    def test_bad_config_is_reported_with_its_place(self, project, capsys):
+        (project / "py-doc.yml").write_text("documents:\n  a: {}\n", encoding="utf-8")
+        assert main(["build"]) == 1
+        assert "documents.a.sources must be a list" in capsys.readouterr().err
+
+    def test_config_without_documents_is_an_error(self, project, capsys):
+        (project / "py-doc.yml").write_text("project: {name: x}\n", encoding="utf-8")
+        assert main(["build"]) == 1
+        assert "defines no documents" in capsys.readouterr().err
+
+    def test_one_failing_document_does_not_stop_the_others(self, project, capsys):
+        (project / "a.md").write_bytes(b"caf\xe9\n")
+        assert main(["build"]) == 1
+        err = capsys.readouterr().err
+        assert "alpha:" in err and "not valid UTF-8" in err
+        assert "1 of 2 document(s) built, 1 failed" in err
+        assert (project / "build" / "beta.docx").exists()
+
+    def test_missing_source_names_the_document(self, project, capsys):
+        (project / "b.md").unlink()
+        assert main(["build", "beta"]) == 1
+        assert "beta: Source for document 'beta' not found" in capsys.readouterr().err
+
+    def test_legacy_build_file_builds_without_a_config(self, project, capsys):
+        (project / "deck.yaml").write_text(
+            "meta: {title: Deck, version: 2.0.0}\n"
+            "cli: {output: out/Deck.pptx, verbose: false, keep-temps: false}\n"
+            "entries: [{file: a.md}, {file: b.md, section: Second, heading_offset: 1}]\n",
+            encoding="utf-8",
+        )
+        (project / "paper.yaml").write_text(
+            "meta: {title: Paper, version: 0.1.0}\n"
+            "cli: {emit-docx: true, output: Paper.docx, plantuml-jar-path: x.jar}\n"
+            "entries: [{file: a.md, heading_offset: 0, page_break: false}]\n",
+            encoding="utf-8",
+        )
+        assert main(["build", "--legacy", "deck.yaml"]) == 0
+        assert (project / "out" / "Deck-2_0_0.pptx").exists()
+        assert main(["build", "--legacy", "paper.yaml"]) == 0
+        assert "Alpha" in texts(project / "Paper-0_1_0.docx")
+        assert "cli.plantuml-jar-path was left out" in capsys.readouterr().err
+
+    def test_legacy_option_refuses_other_yaml(self, project, capsys):
+        assert main(["build", "--legacy", "py-doc.yml"]) == 1
+        assert "is not a createdocs build file" in capsys.readouterr().err
+
+    def test_quiet_hides_progress(self, project, capsys):
+        assert main(["build", "alpha", "-q"]) == 0
+        assert capsys.readouterr().err == ""
+
+
+class TestDelegation:
+    def test_docx(self, project):
+        assert main(["docx", "a.md", "-o", "x.docx"]) == 0
+        assert texts(project / "x.docx")[0] == "Alpha"
+
+    def test_slides(self, project):
+        assert main(["slides", "a.md"]) == 0
+        assert (project / "a.pptx").exists()
+
+    def test_lint_uses_the_project_configuration(self, project, capsys):
+        assert main(["lint", "a.md"]) == 0
+        assert "DOC002" in capsys.readouterr().out
+        (project / "py-doc.yml").write_text("lint:\n  rules: {DOC002: error}\n", encoding="utf-8")
+        assert main(["lint", "a.md"]) == 1
+
+    def test_failures_keep_their_exit_status(self, project):
+        assert main(["docx", "missing.md"]) == 1
+
+    def test_no_command_is_a_usage_error(self, capsys):
+        with pytest.raises(SystemExit) as exc:
+            main([])
+        assert exc.value.code == 2
+
+    def test_version(self, capsys):
+        import py_doc
+
+        with pytest.raises(SystemExit):
+            main(["--version"])
+        assert capsys.readouterr().out.strip() == f"py-doc {py_doc.__version__}"
+
+
+@pytest.mark.parametrize(
+    ("command", "usage", "shown"),
+    [
+        (["docx"], "usage: py-doc docx", "py-doc docx guide.md -t Template.docx"),
+        (["slides"], "usage: py-doc slides", "--split-level 1"),
+        (["lint"], "usage: py-doc lint", "py-doc lint docs README.md"),
+        (["build"], "usage: py-doc build", "one legacy createdocs build file"),
+        (["migrate"], "usage: py-doc migrate", "py-doc migrate docs --check"),
+        (["new"], "usage: py-doc new", "py-doc new --scan --start 100"),
+        ([], "usage: py-doc ", "`py-doc COMMAND --help`"),
+    ],
+)
+def test_the_help_names_the_command_and_shows_what_it_does(command, usage, shown, capsys):
+    with pytest.raises(SystemExit):
+        main([*command, "--help"])
+    out = capsys.readouterr().out
+    assert out.startswith(usage) and shown in out
+
+
+def test_the_old_commands_keep_their_own_name_in_the_help(capsys):
+    from py_doc.cli import run_docx
+    from py_doc.slides_cli import run_slides
+
+    for run, name in ((run_docx, "py-doc2docx"), (run_slides, "py-doc2slides")):
+        with pytest.raises(SystemExit):
+            run(["--help"], legacy=True)
+        assert capsys.readouterr().out.startswith(f"usage: {name}")
+
+
+class TestPipeline:
+    def test_lint_errors_stop_the_build_and_strict_stops_on_warnings(self, project, capsys):
+        (project / "a.md").write_text("# Alpha\n\n```\nnever closed\n", encoding="utf-8")
+        assert main(["build", "alpha", "--lint"]) == 1
+        assert "nothing was built" in capsys.readouterr().err and not (project / "build").exists()
+        (project / "a.md").write_text("# Alpha\n\nWe run in order to test.\n", encoding="utf-8")
+        assert main(["build", "alpha", "--lint"]) == 0
+        assert main(["build", "alpha", "--strict"]) == 1
+
+    def test_the_lint_report_and_the_steps_in_the_build_report(self, project):
+        import json
+
+        assert main(["build", "alpha", "--lint", "--lint-report", "out/lint.sarif", "--report", "out/report.json"]) == 0
+        sarif = json.loads((project / "out" / "lint.sarif").read_text(encoding="utf-8"))
+        assert sarif["version"] == "2.1.0" and sarif["runs"][0]["results"][0]["ruleId"] == "DOC002"
+        steps = json.loads((project / "out" / "report.json").read_text(encoding="utf-8"))["steps"]
+        assert [(s["step"], s["status"]) for s in steps] == [("lint", "ok"), ("documents", "ok"), ("verify", "ok")]
+
+    def test_build_settings_in_py_doc_yml(self, project, capsys):
+        with open(project / "py-doc.yml", "a", encoding="utf-8") as file:
+            file.write("build: {lint: strict, site: true}\n")
+        assert main(["build", "alpha"]) == 1  # strict: the wordy phrase is a warning
+        assert main(["build", "alpha", "--no-lint"]) == 1  # then the site: there is no site section
+        assert "has no site section" in capsys.readouterr().err
+        assert main(["build", "alpha", "--no-lint", "--no-site"]) == 0
+
+
+@pytest.mark.parametrize(
+    "words, usage",
+    [
+        (["help"], "usage: py-doc "),
+        (["help", "build"], "usage: py-doc build"),
+        (["lint", "help"], "usage: py-doc lint"),
+    ],
+)
+def test_help_as_a_word(words, usage, tmp_path, monkeypatch, capsys):
+    monkeypatch.chdir(tmp_path)
+    with pytest.raises(SystemExit) as stop:
+        main(words)
+    assert stop.value.code == 0 and usage in capsys.readouterr().out
diff --git a/tests/test_build.py b/tests/test_build.py
index cd7f8a9..dd9c249 100644
--- a/tests/test_build.py
+++ b/tests/test_build.py
@@ -16,7 +16,9 @@
 @pytest.fixture
 def project(tmp_path, pandoc_runtime):
     (tmp_path / "docs").mkdir()
-    (tmp_path / "docs" / "index.md").write_text("---\ntitle: From front matter\nauthor: Ann\n---\n# Intro\n\nHello.\n", encoding="utf-8")
+    (tmp_path / "docs" / "index.md").write_text(
+        "---\ntitle: From front matter\nauthor: Ann\n---\n# Intro\n\nHello.\n", encoding="utf-8"
+    )
     (tmp_path / "docs" / "part.md").write_text("# Part\n\n## Detail\n\ntext\n", encoding="utf-8")
 
     def make(yaml_text: str, name: str = "g", formats=None):
@@ -36,7 +38,9 @@ def headings(path) -> list[str]:
 
 
 def test_sources_are_joined_in_order_with_a_page_break_before_marked_ones(project, tmp_path):
-    [out] = project("documents:\n  g:\n    sources:\n      - docs/index.md\n      - {file: docs/part.md, page_break: true}\n")
+    [out] = project(
+        "documents:\n  g:\n    sources:\n      - docs/index.md\n      - {file: docs/part.md, page_break: true}\n"
+    )
     assert out == tmp_path / "build" / "g.docx"
     assert headings(out) == ["Intro", "Part", "Detail"]
     assert page_breaks(out) == 1
@@ -57,11 +61,16 @@ def test_page_break_on_the_first_source_adds_nothing(project):
 def test_heading_offset_and_title(project):
     [out] = project("documents:\n  g:\n    sources:\n      - {file: docs/part.md, heading_offset: 1, title: Renamed}\n")
     assert headings(out) == ["Renamed", "Detail"]
-    assert [p.style.name for p in Document(str(out)).paragraphs if p.style.name.startswith("Heading")] == ["Heading 2", "Heading 3"]
+    assert [p.style.name for p in Document(str(out)).paragraphs if p.style.name.startswith("Heading")] == [
+        "Heading 2",
+        "Heading 3",
+    ]
 
 
 def test_excluded_sources_are_skipped_and_all_excluded_is_an_error(project):
-    [out] = project("documents:\n  g:\n    sources:\n      - docs/index.md\n      - {file: docs/missing.md, include: false}\n")
+    [out] = project(
+        "documents:\n  g:\n    sources:\n      - docs/index.md\n      - {file: docs/missing.md, include: false}\n"
+    )
     assert "Hello." in texts(out)
     with pytest.raises(ConversionError, match="no sources"):
         project("documents:\n  g:\n    sources:\n      - {file: docs/index.md, include: false}\n")
@@ -94,7 +103,9 @@ def test_images_resolve_against_their_own_source_folder(project, tmp_path):
 
 
 def test_formats_listed_by_the_document_are_all_built(project, tmp_path):
-    written = project("documents:\n  g:\n    sources: [docs/index.md, docs/part.md]\n    outputs: {docx: {}, pptx: {path: deck/g.pptx}}\n")
+    written = project(
+        "documents:\n  g:\n    sources: [docs/index.md, docs/part.md]\n    outputs: {docx: {}, pptx: {path: deck/g.pptx}}\n"
+    )
     assert [p.name for p in written] == ["g.docx", "g.pptx"]
     assert titles(tmp_path / "deck" / "g.pptx")[0] == "From front matter"
 
diff --git a/tests/test_c4.py b/tests/test_c4.py
index 541f210..d6c6704 100644
--- a/tests/test_c4.py
+++ b/tests/test_c4.py
@@ -148,7 +148,11 @@ def test_the_model_matches_the_workspace(ws):
 def test_a_missing_field_is_named():
     with pytest.raises(WorkspaceError, match=r"model.softwareSystems\[0\].containers\[1\] has no field 'name'"):
         workspace_from_dict(
-            {"model": {"softwareSystems": [{"id": "1", "name": "S", "containers": [{"id": "2", "name": "A"}, {"id": "3"}]}]}}
+            {
+                "model": {
+                    "softwareSystems": [{"id": "1", "name": "S", "containers": [{"id": "2", "name": "A"}, {"id": "3"}]}]
+                }
+            }
         )
     with pytest.raises(WorkspaceError, match="no field 'model'"):
         workspace_from_dict({})
@@ -237,13 +241,20 @@ def test_output_is_stable_and_has_no_times(ws):
 
 def test_levels_and_systems_limit_the_pages(ws):
     assert sorted(pages(ws, levels=["context", "relationships"])) == ["01_context.md", "04_relationships.md"]
-    assert "Internet Banking System" not in pages(ws, systems=["Mainframe Banking System"])["01_context.md"].split("## Software systems")[1].split("|")[3]
+    assert (
+        "Internet Banking System"
+        not in pages(ws, systems=["Mainframe Banking System"])["01_context.md"]
+        .split("## Software systems")[1]
+        .split("|")[3]
+    )
     with pytest.raises(ValueError, match="Unknown level"):
         pages(ws, levels=["nope"])
 
 
 def test_templates_can_be_replaced(ws):
-    assert "Landscape of Big Bank plc." in pages(ws, templates={"context": "Landscape of {workspace}."})["01_context.md"]
+    assert (
+        "Landscape of Big Bank plc." in pages(ws, templates={"context": "Landscape of {workspace}."})["01_context.md"]
+    )
 
 
 def test_generated_pages_pass_the_linter(ws, tmp_path, capsys):
@@ -352,7 +363,10 @@ def test_a_staged_dsl_keeps_its_saved_layouts(project, box):
     run = [c for c in box.engine_calls if c[0] == "run"][0]
     staged = Path(next(a for a in run if a.startswith("type=bind")).split("source=")[1].split(",target")[0])
     assert staged != project.resolve() and (staged / "workspace.json").read_text() == '{"views": "with layouts"}'
-    assert "STRUCTURIZR_EDITABLE=false" in run and ["--user", "1000:1000"] == run[run.index("--user") : run.index("--user") + 2]
+    assert (
+        "STRUCTURIZR_EDITABLE=false" in run
+        and ["--user", "1000:1000"] == run[run.index("--user") : run.index("--user") + 2]
+    )
     stack.down()
 
 
@@ -569,8 +583,14 @@ def test_the_source_is_read_with_its_options(tmp_path):
 @pytest.mark.parametrize(
     ("body", "message"),
     [
-        ("      - structurizr: w.json\n        levels: [cake]\n", r"documents.arch.sources\[0\].levels has unknown level 'cake'"),
-        ("      - structurizr: w.json\n        diagrams: {engine: magic}\n", "diagrams.engine must be browser or source"),
+        (
+            "      - structurizr: w.json\n        levels: [cake]\n",
+            r"documents.arch.sources\[0\].levels has unknown level 'cake'",
+        ),
+        (
+            "      - structurizr: w.json\n        diagrams: {engine: magic}\n",
+            "diagrams.engine must be browser or source",
+        ),
         ("      - structurizr: w.json\n        diagrams: {format: gif}\n", "diagrams.format must be one of png, svg"),
         ("      - structurizr: w.json\n        page_brek: true\n", "page_brek"),
     ],
@@ -613,7 +633,10 @@ def test_the_source_engine_embeds_labelled_diagram_source(tmp_path, project, box
     )
     (page,) = expand(config.documents["arch"].sources, "arch", tmp_path, lambda: box, config.c4)
     text = page.file.read_text(encoding="utf-8")
-    assert "Diagram source (mermaid) of the view 'System Context for Internet Banking'" in text and "```mermaid\ngraph TD" in text
+    assert (
+        "Diagram source (mermaid) of the view 'System Context for Internet Banking'" in text
+        and "```mermaid\ngraph TD" in text
+    )
     assert not any(c[0] == "node" for c in box.calls)
 
 
@@ -751,7 +774,9 @@ def engine(self, args, **kwargs):
 
     def run(self, argv, **kwargs):
         assert argv[3] == "http://localhost:8080/workspace/1/diagrams"
-        assert argv[:2] == ["node", "-e"] and kwargs["network"] == "container:py-doc-c4-local"  # probed as localhost, the only name Local answers to
+        assert (
+            argv[:2] == ["node", "-e"] and kwargs["network"] == "container:py-doc-c4-local"
+        )  # probed as localhost, the only name Local answers to
         self.calls.append("probe")
         self.failures -= 1
         return ToolResult(1 if self.failures >= 0 else 0, "", "")
@@ -790,7 +815,15 @@ def test_the_wait_gives_up_after_the_limit_with_clean_logs(quick, tmp_path):
 
 def test_structurizr_bookkeeping_properties_are_left_out():
     ws = workspace_from_dict(
-        {"name": "w", "model": {"softwareSystems": [{"id": "1", "name": "S", "properties": {"structurizr.dsl.identifier": "s", "owner": "Team"}}]}, "views": {}}
+        {
+            "name": "w",
+            "model": {
+                "softwareSystems": [
+                    {"id": "1", "name": "S", "properties": {"structurizr.dsl.identifier": "s", "owner": "Team"}}
+                ]
+            },
+            "views": {},
+        }
     )
     (system,) = ws.elements.values()
     assert system.properties == {"owner": "Team"}
diff --git a/tests/test_compat.py b/tests/test_compat.py
index 238af6f..3c3a07e 100644
--- a/tests/test_compat.py
+++ b/tests/test_compat.py
@@ -85,7 +85,12 @@ def test_issue_has_the_old_shape(self, tmp_path):
         md.write_text("Fine.\n\nWe use dtls here.\n", encoding="utf-8")
         [issue] = DocLinter().lint_file(md)
         assert isinstance(issue, LintIssue)
-        assert (issue.file, issue.line_no, issue.category, issue.severity) == (Path(md).resolve(), 3, "Glossary", "warning")
+        assert (issue.file, issue.line_no, issue.category, issue.severity) == (
+            Path(md).resolve(),
+            3,
+            "Glossary",
+            "warning",
+        )
         assert repr(issue).startswith("[WARNING] a.md:3 [Glossary] ")
 
     def test_missing_file_gives_no_issues_like_before(self, tmp_path):
@@ -148,5 +153,7 @@ def test_real_legacy_entry_points_show_the_notice(self, tmp_path):
         empty = tmp_path / "empty"  # nothing to convert, so no container is needed
         empty.mkdir()
         for module in ("pydoc2docx", "pydoc2slides"):
-            result = subprocess.run([sys.executable, "-m", module, str(empty)], capture_output=True, text=True, check=False)
+            result = subprocess.run(
+                [sys.executable, "-m", module, str(empty)], capture_output=True, text=True, check=False
+            )
             assert result.returncode == 0 and "is now part of py-doc" in result.stderr, module
diff --git a/tests/test_config.py b/tests/test_config.py
index 05e0a83..1ad82cb 100644
--- a/tests/test_config.py
+++ b/tests/test_config.py
@@ -8,8 +8,17 @@
 from py_doc.lint.config import C4_RULES
 from py_doc.config import ConfigError, find_config, load_config, parse_config
 
-NEW_RULES = {"DOC005": "warning", "DOC006": "warning", "DOC007": "warning", "DOC008": "info", "DOC009": "info",
-             "DOC010": "info", "DOC011": "error", "DOC012": "warning", "DOC013": "info"}
+NEW_RULES = {
+    "DOC005": "warning",
+    "DOC006": "warning",
+    "DOC007": "warning",
+    "DOC008": "info",
+    "DOC009": "info",
+    "DOC010": "info",
+    "DOC011": "error",
+    "DOC012": "warning",
+    "DOC013": "info",
+}
 
 
 def write(tmp_path, text: str):
@@ -101,7 +110,10 @@ def test_metadata_is_mapped_to_document_properties(tmp_path):
         ("- a", "the configuration must be a mapping"),
         ("documents:\n  g: {}", "documents.g.sources must be a list"),
         ("documents:\n  g: {sources: []}", "documents.g.sources must be a list"),
-        ("documents:\n  g: {sources: [{page_brek: true, file: a.md}]}", "unknown key 'page_brek' in documents.g.sources[0]"),
+        (
+            "documents:\n  g: {sources: [{page_brek: true, file: a.md}]}",
+            "unknown key 'page_brek' in documents.g.sources[0]",
+        ),
         ("documents:\n  g: {sources: [{title: x}]}", "documents.g.sources[0] needs a 'file'"),
         ("documents:\n  g: {sources: [{file: a.md, heading_offset: x}]}", "heading_offset must be int"),
         ("documents:\n  g: {sources: [{file: a.md, heading_offset: true}]}", "heading_offset must be int"),
@@ -139,7 +151,10 @@ def load(self, tmp_path, body: str):
 
     def test_rule_severity_and_off(self, tmp_path):
         lint = self.load(tmp_path, "  rules:\n    DOC001: error\n    DOC002: off\n    DOC003: warning\n")
-        assert lint.severities == {"DOC001": "error", "DOC002": "warning", "DOC003": "warning", "DOC004": "error"} | NEW_RULES | C4_RULES
+        assert (
+            lint.severities
+            == {"DOC001": "error", "DOC002": "warning", "DOC003": "warning", "DOC004": "error"} | NEW_RULES | C4_RULES
+        )
         assert lint.disabled_rules == {"DOC002"}
 
     def test_glossary_and_phrases_extend_the_defaults(self, tmp_path):
@@ -160,7 +175,9 @@ def test_exclude_adds_to_the_default_directories(self, tmp_path):
 
 
 def test_the_content_and_build_sections(tmp_path):
-    config = load_config(write(tmp_path, "content: {generators: [{type: glossary, output: g.md}]}\nbuild: {lint: on}\n"))
+    config = load_config(
+        write(tmp_path, "content: {generators: [{type: glossary, output: g.md}]}\nbuild: {lint: on}\n")
+    )
     assert [(g.name, g.type) for g in config.generators] == [("g", "glossary")] and config.build.lint == "on"
     with pytest.raises(ConfigError, match="build.lint must be one of off, on, strict"):
         load_config(write(tmp_path, "build: {lint: loud}\n"))
@@ -183,10 +200,18 @@ def test_the_site_section(tmp_path):
 
 def test_the_site_downloads_and_targets(tmp_path):
     docs = "documents:\n  guide: {sources: [a.md]}\n"
-    config = load_config(write(tmp_path, docs + "site: {engine: mkdocs, downloads: [pdf, docx], targets: {github: mkdocs.yml, tarf: mkdocs.tarf.yml}}\n"))
+    config = load_config(
+        write(
+            tmp_path,
+            docs
+            + "site: {engine: mkdocs, downloads: [pdf, docx], targets: {github: mkdocs.yml, tarf: mkdocs.tarf.yml}}\n",
+        )
+    )
     assert config.site.downloads == ["pdf", "docx"]
     assert config.site.targets == {"github": "mkdocs.yml", "tarf": "mkdocs.tarf.yml"}
-    assert load_config(write(tmp_path, docs + "site: {engine: mkdocs, pages: {Blog: blog/index.md}}\n")).site.pages == {"Blog": "blog/index.md"}
+    assert load_config(write(tmp_path, docs + "site: {engine: mkdocs, pages: {Blog: blog/index.md}}\n")).site.pages == {
+        "Blog": "blog/index.md"
+    }
     with pytest.raises(ConfigError, match="site.downloads names 'epub'"):
         load_config(write(tmp_path, docs + "site: {engine: mkdocs, downloads: [epub]}\n"))
     with pytest.raises(ConfigError, match="site.targets needs engine: mkdocs"):
@@ -207,7 +232,9 @@ def test_parse_config_accepts_a_dict():
 def test_the_example_in_the_user_guide_loads(tmp_path):
     import re
 
-    readme = Path(__file__).parent.parent / "docs" / "guide" / "02_projects.md"  # the configuration example of the user guide
+    readme = (
+        Path(__file__).parent.parent / "docs" / "guide" / "02_projects.md"
+    )  # the configuration example of the user guide
     block = re.search(r"```yaml\n(project:.*?)```", readme.read_text(encoding="utf-8"), re.S).group(1)
     config = load_config(write(tmp_path, block))
     assert list(config.documents) == ["c4-guide", "api", "handbook"]
@@ -245,12 +272,16 @@ def test_bundles_combine_documents_and_build_beside_them(tmp_path):
     assert handbook.bundle == ["guide", "api"] and handbook.meta["title"] == "Handbook"
     assert [(s.file.name, s.page_break) for s in handbook.sources] == [("a.md", False), ("b.md", False), ("c.md", True)]
     assert handbook.variables == {"x": 1, "y": 2}
-    assert config.output_formats(handbook) == ["docx", "pdf"] and config.output_formats(config.documents["api"]) == ["pdf"]
+    assert config.output_formats(handbook) == ["docx", "pdf"] and config.output_formats(config.documents["api"]) == [
+        "pdf"
+    ]
     assert set(config.lint.documents) == {"guide", "api"}
     with pytest.raises(ConfigError, match="names 'gone', which is not under documents"):
         load_config(write(tmp_path, "documents:\n  guide: {sources: [a.md]}\nbundles:\n  b: {documents: [gone]}\n"))
     with pytest.raises(ConfigError, match="has the name of a document"):
-        load_config(write(tmp_path, "documents:\n  guide: {sources: [a.md]}\nbundles:\n  guide: {documents: [guide]}\n"))
+        load_config(
+            write(tmp_path, "documents:\n  guide: {sources: [a.md]}\nbundles:\n  guide: {documents: [guide]}\n")
+        )
 
 
 def test_site_groups(tmp_path):
diff --git a/tests/test_convert.py b/tests/test_convert.py
index d6174bd..0062836 100644
--- a/tests/test_convert.py
+++ b/tests/test_convert.py
@@ -14,7 +14,9 @@
 from py_doc.errors import ConversionError
 
 
-@pytest.mark.parametrize("option", ["engine", "keep_template_body", "keep_template_slides", "title_layout", "content_layout"])
+@pytest.mark.parametrize(
+    "option", ["engine", "keep_template_body", "keep_template_slides", "title_layout", "content_layout"]
+)
 def test_retired_options_are_refused_with_what_to_do(tmp_path, option):
     fmt = "pptx" if option in ("keep_template_slides", "title_layout", "content_layout") else "docx"
     data = {"documents": {"g": {"sources": ["a.md"], "outputs": {fmt: {option: "x"}}}}}
@@ -43,7 +45,11 @@ def test_a_dotx_template_is_accepted(tmp_path, pandoc_runtime):
 
 def test_a_potx_template_is_accepted(tmp_path, pandoc_runtime):
     template = tmp_path / "t.pptx"
-    template.write_bytes(subprocess.run(["pandoc", "--print-default-data-file", "reference.pptx"], capture_output=True, check=True).stdout)
+    template.write_bytes(
+        subprocess.run(
+            ["pandoc", "--print-default-data-file", "reference.pptx"], capture_output=True, check=True
+        ).stdout
+    )
     with zipfile.ZipFile(template) as z:
         data = {i.filename: z.read(i.filename) for i in z.infolist()}
     data["[Content_Types].xml"] = data["[Content_Types].xml"].replace(b"presentation.main+xml", b"template.main+xml")
@@ -105,10 +111,11 @@ def test_docx_convert_twin_produces_html(tmp_path, pandoc_runtime):
 
 def test_slides_convert_twin_produces_html_with_notes(tmp_path, pandoc_runtime):
     md = tmp_path / "talk.md"
-    md.write_text("# Title\n\n## First Slide\n\n- point\n\n<!-- notes: Remember to emphasize this -->\n", encoding="utf-8")
+    md.write_text(
+        "# Title\n\n## First Slide\n\n- point\n\n<!-- notes: Remember to emphasize this -->\n", encoding="utf-8"
+    )
     out = SlidesConverter().convert_twin(md, tmp_path / "talk.html")
     assert out.is_file()
     html_text = out.read_text(encoding="utf-8")
     assert "First Slide" in html_text
     assert "Remember to emphasize this" in html_text
-
diff --git a/tests/test_diagrams.py b/tests/test_diagrams.py
index fa24473..83782fc 100644
--- a/tests/test_diagrams.py
+++ b/tests/test_diagrams.py
@@ -75,7 +75,7 @@ def stub(tmp_path, monkeypatch, name: str, body: str) -> Path:
 
 class TestScan:
     def test_finds_diagram_fences_in_all_spellings(self):
-        text = "a\n```plantuml title=\"Ctx\"\nA -> B\n```\n\n~~~puml\nX\n~~~\n\n:::mermaid\ngraph TD\n:::\n\n::: mermaid\nflowchart\n:::\n"
+        text = 'a\n```plantuml title="Ctx"\nA -> B\n```\n\n~~~puml\nX\n~~~\n\n:::mermaid\ngraph TD\n:::\n\n::: mermaid\nflowchart\n:::\n'
         blocks = find_blocks(text)
         assert [(b.fence, b.line) for b in blocks] == [("plantuml", 2), ("puml", 6), ("mermaid", 10), ("mermaid", 14)]
         assert blocks[0].body == "A -> B" and blocks[0].options == {"title": "Ctx"}
@@ -158,10 +158,12 @@ class TestDot:
 
     def test_png_with_density_and_alt_text(self, tmp_path, host):
         _, runtime = host
-        rendered = render_parts(part(tmp_path, f"before\n\n```dot title=\"Flow\"\n{self.DOT}\n```\n\nafter\n"), "docx", runtime)
-        (name, path), = rendered.pictures.items()
+        rendered = render_parts(
+            part(tmp_path, f'before\n\n```dot title="Flow"\n{self.DOT}\n```\n\nafter\n'), "docx", runtime
+        )
+        ((name, path),) = rendered.pictures.items()
         assert name.startswith("diagrams/") and path.read_bytes().startswith(b"\x89PNG")
-        assert '![Flow](' + name + ')' in rendered.markdown and "digraph" not in rendered.markdown
+        assert "![Flow](" + name + ")" in rendered.markdown and "digraph" not in rendered.markdown
         from PIL import Image
 
         assert Image.open(path).info["dpi"][0] == pytest.approx(192, abs=1)
@@ -208,13 +210,19 @@ def test_keep_going_lists_every_failure(self, tmp_path, host):
         bad = "```dot\ndigraph { a -> \n```\n\n"
         with pytest.raises(DiagramError) as exc:
             render_parts(part(tmp_path, bad + bad), "docx", runtime, keep_going=True)
-        assert "2 diagram(s) failed" in str(exc.value) and "doc.md:1:" in str(exc.value) and "doc.md:5:" in str(exc.value)
+        assert (
+            "2 diagram(s) failed" in str(exc.value) and "doc.md:1:" in str(exc.value) and "doc.md:5:" in str(exc.value)
+        )
 
     @needs_pandoc
     def test_a_broken_diagram_stops_the_build_and_writes_nothing(self, tmp_path, host):
         _, runtime = host
-        (tmp_path / "g.md").write_text("# G\n\n```dot\ndigraph { a -> b }\n```\n\n```dot\ndigraph { a -> \n```\n", encoding="utf-8")
-        (tmp_path / "py-doc.yml").write_text("documents:\n  g:\n    sources: [g.md]\n    outputs:\n      docx: {}\n", encoding="utf-8")
+        (tmp_path / "g.md").write_text(
+            "# G\n\n```dot\ndigraph { a -> b }\n```\n\n```dot\ndigraph { a -> \n```\n", encoding="utf-8"
+        )
+        (tmp_path / "py-doc.yml").write_text(
+            "documents:\n  g:\n    sources: [g.md]\n    outputs:\n      docx: {}\n", encoding="utf-8"
+        )
         config = load_config(tmp_path / "py-doc.yml")
         with pytest.raises(DiagramError, match=r"g\.md:7"):
             build_document(config, config.documents["g"], runtime=runtime)
@@ -225,8 +233,10 @@ def test_the_picture_reaches_the_document(self, tmp_path, host):
         from docx import Document
 
         _, runtime = host
-        (tmp_path / "g.md").write_text(f"# G\n\n```dot title=\"Flow\"\n{self.DOT}\n```\n", encoding="utf-8")
-        (tmp_path / "py-doc.yml").write_text("documents:\n  g:\n    sources: [g.md]\n    outputs:\n      docx: {}\n      html: {}\n", encoding="utf-8")
+        (tmp_path / "g.md").write_text(f'# G\n\n```dot title="Flow"\n{self.DOT}\n```\n', encoding="utf-8")
+        (tmp_path / "py-doc.yml").write_text(
+            "documents:\n  g:\n    sources: [g.md]\n    outputs:\n      docx: {}\n      html: {}\n", encoding="utf-8"
+        )
         config = load_config(tmp_path / "py-doc.yml")
         docx, html = build_document(config, config.documents["g"], runtime=runtime)
         assert len(Document(str(docx)).inline_shapes) == 1
@@ -253,14 +263,25 @@ def test_a_diagram_has_one_caption_its_own_or_else_the_tools(tmp_path, pandoc_ru
     picture = png(tmp_path / "pic.png")
     monkeypatch.setattr(diagrams.render, "draw_cached", lambda *args, **kwargs: picture)
     (tmp_path / "g.md").write_text(text, encoding="utf-8")
-    (tmp_path / "py-doc.yml").write_text("documents:\n  g:\n    sources: [g.md]\n    outputs: {docx: {}, html: {}, pptx: {}}\n", encoding="utf-8")
+    (tmp_path / "py-doc.yml").write_text(
+        "documents:\n  g:\n    sources: [g.md]\n    outputs: {docx: {}, html: {}, pptx: {}}\n", encoding="utf-8"
+    )
     config = load_config(tmp_path / "py-doc.yml")
-    docx, html, pptx = sorted(build_document(config, config.documents["g"], runtime=lambda: pandoc_runtime), key=lambda p: p.suffix)
-    captions = [p.text for p in Document(str(docx)).paragraphs if p.style.name == "Caption" or p.text.startswith("Figure")]
+    docx, html, pptx = sorted(
+        build_document(config, config.documents["g"], runtime=lambda: pandoc_runtime), key=lambda p: p.suffix
+    )
+    captions = [
+        p.text for p in Document(str(docx)).paragraphs if p.style.name == "Caption" or p.text.startswith("Figure")
+    ]
     assert len(captions) == 1 and captions[0].endswith(expected)
     body = html.read_text(encoding="utf-8")
     assert re.findall(r"<figcaption[^>]*>(.*?)</figcaption>", body, re.S) == [expected] and "[[CAPTION" not in body
-    shown = [shape.text_frame.text for slide in Presentation(str(pptx)).slides for shape in slide.shapes if shape.has_text_frame]
+    shown = [
+        shape.text_frame.text
+        for slide in Presentation(str(pptx)).slides
+        for shape in slide.shapes
+        if shape.has_text_frame
+    ]
     assert shown.count(expected) == 1
 
 
@@ -276,7 +297,7 @@ def test_a_width_on_a_diagram_or_picture_is_a_share_of_the_text_width(tmp_path,
     section.page_width, section.left_margin, section.right_margin = Cm(21), Cm(2), Cm(2)
     template.save(tmp_path / "T.docx")
     (tmp_path / "g.md").write_text(
-        "# G\n\n```dot width=\"100%\"\ndigraph { a -> b }\n```\n\n![half](pic.png){width=50%}\n\n![natural](pic.png)\n",
+        '# G\n\n```dot width="100%"\ndigraph { a -> b }\n```\n\n![half](pic.png){width=50%}\n\n![natural](pic.png)\n',
         encoding="utf-8",
     )
     (tmp_path / "py-doc.yml").write_text(
@@ -304,7 +325,12 @@ def test_plantuml_gets_its_include_folder_and_the_text(self, tmp_path, host, mon
         _, runtime = host
         monkeypatch.setenv("STUB_LOG", str(tmp_path / "stub.log"))
         png_bytes = png(tmp_path / "x.png").read_bytes()
-        stub(tmp_path, monkeypatch, "plantuml", PNG_STUB + f"open(sys.argv[-1].rsplit('.', 1)[0] + '.png', 'wb').write({png_bytes!r})")
+        stub(
+            tmp_path,
+            monkeypatch,
+            "plantuml",
+            PNG_STUB + f"open(sys.argv[-1].rsplit('.', 1)[0] + '.png', 'wb').write({png_bytes!r})",
+        )
         text = "```plantuml\n@startuml\nA -> B\n@enduml\n```\n"
         rendered = render_parts(part(tmp_path, text), "pdf", runtime)
         call = json.loads((tmp_path / "stub.log").read_text(encoding="utf-8").splitlines()[0])
@@ -316,7 +342,12 @@ def test_plantuml_with_an_include_is_drawn_every_time(self, tmp_path, host, monk
         _, runtime = host
         monkeypatch.setenv("STUB_LOG", str(tmp_path / "stub.log"))
         png_bytes = png(tmp_path / "x.png").read_bytes()
-        stub(tmp_path, monkeypatch, "plantuml", PNG_STUB + f"open(sys.argv[-1].rsplit('.', 1)[0] + '.png', 'wb').write({png_bytes!r})")
+        stub(
+            tmp_path,
+            monkeypatch,
+            "plantuml",
+            PNG_STUB + f"open(sys.argv[-1].rsplit('.', 1)[0] + '.png', 'wb').write({png_bytes!r})",
+        )
         text = "```plantuml\n!include part.puml\nA -> B\n```\n"
         for _ in range(2):
             render_parts(part(tmp_path, text), "docx", runtime)
@@ -338,10 +369,18 @@ def test_the_orientation_marker_chooses_the_mermaid_width(self, tmp_path, host,
         _, runtime = host
         monkeypatch.setenv("STUB_LOG", str(tmp_path / "stub.log"))
         png_bytes = png(tmp_path / "x.png").read_bytes()
-        stub(tmp_path, monkeypatch, "mmdc", PNG_STUB + f"open(sys.argv[sys.argv.index('-o') + 1], 'wb').write({png_bytes!r})")
+        stub(
+            tmp_path,
+            monkeypatch,
+            "mmdc",
+            PNG_STUB + f"open(sys.argv[sys.argv.index('-o') + 1], 'wb').write({png_bytes!r})",
+        )
         text = "```mermaid\ngraph TD;A-->B\n```\n\n[[LANDSCAPE]]\n\n```mermaid\ngraph TD;A-->C\n```\n\n[[PORTRAIT]]\n\n```mermaid\ngraph TD;A-->D\n```\n"
         render_parts(part(tmp_path, text), "docx", runtime)
-        widths = [c["argv"][c["argv"].index("--size") + 1] for c in map(json.loads, (tmp_path / "stub.log").read_text(encoding="utf-8").splitlines())]
+        widths = [
+            c["argv"][c["argv"].index("--size") + 1]
+            for c in map(json.loads, (tmp_path / "stub.log").read_text(encoding="utf-8").splitlines())
+        ]
         assert widths == ["1200", "1800", "1200"]
 
     def test_the_container_runs_diagram_tools_without_a_network(self, tmp_path, monkeypatch):
@@ -369,7 +408,10 @@ def test_the_python_tools_write_svg(tmp_path, script):
     module = {"pikchr_render.py": "pypikchr", "railroad_render.py": "railroad"}[script]
     pytest.importorskip(module)
     source = tmp_path / "in.txt"
-    source.write_text('box "hi"' if module == "pypikchr" else 'Sequence\n  Terminal "SELECT"\n  Optional\n    Terminal "*"\n', encoding="utf-8")
+    source.write_text(
+        'box "hi"' if module == "pypikchr" else 'Sequence\n  Terminal "SELECT"\n  Optional\n    Terminal "*"\n',
+        encoding="utf-8",
+    )
     out = tmp_path / "out.svg"
     done = subprocess.run([sys.executable, str(TOOLS / script), str(source), str(out)], capture_output=True, text=True)
     assert done.returncode == 0, done.stderr
@@ -380,7 +422,11 @@ def test_a_pikchr_syntax_error_fails_loudly(tmp_path):
     pytest.importorskip("pypikchr")
     source = tmp_path / "in.txt"
     source.write_text("this is not pikchr (", encoding="utf-8")
-    done = subprocess.run([sys.executable, str(TOOLS / "pikchr_render.py"), str(source), str(tmp_path / "o.svg")], capture_output=True, text=True)
+    done = subprocess.run(
+        [sys.executable, str(TOOLS / "pikchr_render.py"), str(source), str(tmp_path / "o.svg")],
+        capture_output=True,
+        text=True,
+    )
     assert done.returncode != 0 and not (tmp_path / "o.svg").exists()
 
 
@@ -397,13 +443,17 @@ def test_the_svg_to_png_step_falls_back_to_librsvg_when_inkscape_writes_nothing(
     bin_dir = tmp_path / "bin"
     bin_dir.mkdir()
     (bin_dir / "inkscape").write_text("#!/bin/sh\nexit 0\n")  # finishes, writes nothing
-    (bin_dir / "rsvg-convert").write_text('#!/bin/sh\nwhile [ $# -gt 0 ]; do if [ "$1" = -o ]; then echo png > "$2"; fi; shift; done\n')
+    (bin_dir / "rsvg-convert").write_text(
+        '#!/bin/sh\nwhile [ $# -gt 0 ]; do if [ "$1" = -o ]; then echo png > "$2"; fi; shift; done\n'
+    )
     for tool in bin_dir.iterdir():
         tool.chmod(0o755)
     target = tmp_path / "diagram.png"
     done = subprocess.run(
         ["sh", "-c", _SVG_TO_PNG, "x", str(tmp_path / "diagram.svg"), str(target)],
-        env={**os.environ, "PATH": f"{bin_dir}:{os.environ['PATH']}"}, capture_output=True, text=True,
+        env={**os.environ, "PATH": f"{bin_dir}:{os.environ['PATH']}"},
+        capture_output=True,
+        text=True,
     )
     assert done.returncode == 0 and target.read_text() == "png\n" and "librsvg" in done.stderr
 
@@ -437,7 +487,9 @@ def test_the_diagrams_own_front_matter_wins_key_by_key(self):
         from py_doc.diagrams.render import with_mermaid_config
 
         own = "---\ntitle: Flow\nconfig:\n  theme: forest\n  flowchart: {curve: basis}\n---\nflowchart LR\n  A --> B\n"
-        text = with_mermaid_config(own, {"theme": "neutral", "look": "classic", "flowchart": {"curve": "linear", "padding": 20}})
+        text = with_mermaid_config(
+            own, {"theme": "neutral", "look": "classic", "flowchart": {"curve": "linear", "padding": 20}}
+        )
         assert self.front(text) == {
             "title": "Flow",
             "config": {"theme": "forest", "look": "classic", "flowchart": {"curve": "basis", "padding": 20}},
@@ -459,7 +511,12 @@ def draw(runtime, renderer, text, kind, landscape, source_dir, info=None):
             return png(tmp_path / f"{len(texts)}.png")
 
         monkeypatch.setattr("py_doc.diagrams.render.draw_cached", draw)
-        render_parts(part(tmp_path, "```mermaid\ngraph LR\n```\n\n```dot\ndigraph {}\n```\n"), "docx", lambda: None, mermaid={"look": "classic"})
+        render_parts(
+            part(tmp_path, "```mermaid\ngraph LR\n```\n\n```dot\ndigraph {}\n```\n"),
+            "docx",
+            lambda: None,
+            mermaid={"look": "classic"},
+        )
         assert texts[0][0] == "mermaid" and texts[0][1].startswith('---\n{"config": {"look": "classic"}}\n---\n')
         assert texts[1] == ("dot", "digraph {}")
 
diff --git a/tests/test_directives.py b/tests/test_directives.py
index 43b25f9..87d6452 100644
--- a/tests/test_directives.py
+++ b/tests/test_directives.py
@@ -153,13 +153,16 @@ def test_errors_are_conversion_errors():
 class TestBuild:
     def config(self, tmp_path, extra=""):
         (tmp_path / "py-doc.yml").write_text(
-            "documents:\n  g:\n    sources: [main.md]\n    variables: {v: from-file}\n    conditions: {a: true}\n" + extra,
+            "documents:\n  g:\n    sources: [main.md]\n    variables: {v: from-file}\n    conditions: {a: true}\n"
+            + extra,
             encoding="utf-8",
         )
         return load_config(tmp_path / "py-doc.yml").documents["g"]
 
     def merge_document(self, doc, variables=None, conditions=None):
-        return join_sources(doc.sources, {**doc.variables, **(variables or {})}, {**doc.conditions, **(conditions or {})}, doc.id)
+        return join_sources(
+            doc.sources, {**doc.variables, **(variables or {})}, {**doc.conditions, **(conditions or {})}, doc.id
+        )
 
     def text_of(self, joined):
         return " ".join(line for line in joined.markdown.splitlines() if line and not line.startswith("#"))
diff --git a/tests/test_docx_import.py b/tests/test_docx_import.py
index 29d5ba3..8c65d7a 100644
--- a/tests/test_docx_import.py
+++ b/tests/test_docx_import.py
@@ -77,8 +77,10 @@ def sample(tmp_path) -> Path:
     run_text(p, " and ")
     run_text(p, "italic", italic=True)
     run_text(p, " with a_b* star.")
-    link = parse_xml(f'<w:hyperlink {nsdecls("w", "r")} r:id="{doc.part.relate_to("https://example.com", RT.HYPERLINK, is_external=True)}">'
-                     "<w:r><w:t>a link</w:t></w:r></w:hyperlink>")
+    link = parse_xml(
+        f'<w:hyperlink {nsdecls("w", "r")} r:id="{doc.part.relate_to("https://example.com", RT.HYPERLINK, is_external=True)}">'
+        "<w:r><w:t>a link</w:t></w:r></w:hyperlink>"
+    )
     p._p.append(link)
     doc.add_heading("Details", level=3)
     doc.add_paragraph("one", style="List Bullet")
@@ -205,8 +207,10 @@ def test_tracked_changes_keep_insertions_and_drop_deletions(tmp_path):
     doc.add_heading("T", 1)
     p = doc.add_paragraph("Keep ")
     p._p.append(parse_xml(f'<w:ins {nsdecls("w")} w:id="1" w:author="a"><w:r><w:t>added </w:t></w:r></w:ins>'))
-    p._p.append(parse_xml(f'<w:del {nsdecls("w")} w:id="2" w:author="a"><w:r><w:delText>removed </w:delText></w:r></w:del>'))
-    p._p.append(parse_xml(f'<w:r {nsdecls("w")}><w:t>end</w:t></w:r>'))
+    p._p.append(
+        parse_xml(f'<w:del {nsdecls("w")} w:id="2" w:author="a"><w:r><w:delText>removed </w:delText></w:r></w:del>')
+    )
+    p._p.append(parse_xml(f"<w:r {nsdecls('w')}><w:t>end</w:t></w:r>"))
     path = tmp_path / "track.docx"
     doc.save(path)
     assert "Keep added end" in read(import_docx(path, tmp_path / "out"))
diff --git a/tests/test_examples.py b/tests/test_examples.py
index ad72996..3f25d04 100644
--- a/tests/test_examples.py
+++ b/tests/test_examples.py
@@ -27,7 +27,9 @@
 )
 
 
-needs_xelatex = pytest.mark.skipif(not tex_packages_found("ulem.sty", "tcolorbox.sty"), reason="xelatex or one of its packages is not installed")
+needs_xelatex = pytest.mark.skipif(
+    not tex_packages_found("ulem.sty", "tcolorbox.sty"), reason="xelatex or one of its packages is not installed"
+)
 # The examples keep their Graphviz diagrams (the fixture strips the other kinds), so building them runs dot
 needs_dot = pytest.mark.skipif(shutil.which("dot") is None, reason="Graphviz dot is not installed")
 
@@ -36,7 +38,9 @@
 def examples(tmp_path, monkeypatch):
     """A copy of the examples without the diagrams that need tools the host does not have."""
     target = tmp_path / "examples"
-    shutil.copytree(EXAMPLES, target, ignore=shutil.ignore_patterns("build", ".py-doc", ".structurizr"))  # not what a local build left
+    shutil.copytree(
+        EXAMPLES, target, ignore=shutil.ignore_patterns("build", ".py-doc", ".structurizr")
+    )  # not what a local build left
     for path in (target / "docs").rglob("*.md"):
         path.write_text(NO_TOOLS.sub("", path.read_text(encoding="utf-8")), encoding="utf-8")
     monkeypatch.chdir(target)
@@ -45,7 +49,15 @@ def examples(tmp_path, monkeypatch):
 
 def test_the_config_loads_and_names_every_part():
     config = load_config(EXAMPLES / "py-doc.yml")
-    assert sorted(config.documents) == ["api-reference", "architecture", "datasheet", "deck", "guide", "interfaces", "release-notes"]
+    assert sorted(config.documents) == [
+        "api-reference",
+        "architecture",
+        "datasheet",
+        "deck",
+        "guide",
+        "interfaces",
+        "release-notes",
+    ]
     assert config.documents["architecture"].sources[1].structurizr is not None
     assert config.lint.vale.rules["PyDoc.SentenceLength"].options == {"max": 35}
     assert config.lint.structure
@@ -63,7 +75,17 @@ def test_the_datasheet_template_passes_with_its_own_prefix_and_marker(capsys):
 
 
 def test_the_draft_template_differs_from_the_base_one(capsys):
-    assert main(["template", "diff", str(EXAMPLES / "templates" / "sensor.docx"), str(EXAMPLES / "templates" / "sensor_Draft.docx")]) == 0
+    assert (
+        main(
+            [
+                "template",
+                "diff",
+                str(EXAMPLES / "templates" / "sensor.docx"),
+                str(EXAMPLES / "templates" / "sensor_Draft.docx"),
+            ]
+        )
+        == 0
+    )
 
 
 def test_the_documents_lint_clean(monkeypatch, capsys):
@@ -106,7 +128,9 @@ def test_the_guide_builds_as_word_and_html(examples, pandoc_runtime):
     text = "\n".join(p.text for p in document.paragraphs)
     assert "Sensor Node Guide" in text and "version 1.0" in text and "internal use" in text
     assert "Customers see only the public build." not in text
-    assert [p.text for p in document.paragraphs if p.style.name == "Title"] == ["Sensor Node Guide"], "the title page is not repeated"
+    assert [p.text for p in document.paragraphs if p.style.name == "Title"] == ["Sensor Node Guide"], (
+        "the title page is not repeated"
+    )
     assert any(p.style.name == "Lead Paragraph" and p.text.startswith("The SN-100") for p in document.paragraphs)
     assert "DRAFT" in document.sections[0].header.paragraphs[0].text, "status: Draft chooses sensor_Draft.docx"
     assert "TOC" in document.element.xml, "toc: true adds a contents list"
@@ -141,7 +165,9 @@ def test_the_guide_builds_as_pdf_with_task_lists_and_captions(examples, pandoc_r
     pdf = examples / "build" / "guide.pdf"
     assert pdf.read_bytes().startswith(b"%PDF")
     if shutil.which("pdftotext"):
-        text = subprocess.run(["pdftotext", "-enc", "UTF-8", str(pdf), "-"], capture_output=True, encoding="utf-8", check=True).stdout
+        text = subprocess.run(
+            ["pdftotext", "-enc", "UTF-8", str(pdf), "-"], capture_output=True, encoding="utf-8", check=True
+        ).stdout
         assert "[[" not in text, "no marker is printed in the PDF"
         assert "Data flow through the node" in text and "Figure 1" in text
 
@@ -158,7 +184,12 @@ def test_the_datasheet_builds_with_its_own_placeholders_and_a_version_in_the_nam
 
 def test_the_release_notes_take_their_version_from_git(examples, pandoc_runtime):
     def git(*args):
-        subprocess.run(["git", "-c", "user.name=t", "-c", "user.email=t@example.com", *args], cwd=examples, check=True, capture_output=True)
+        subprocess.run(
+            ["git", "-c", "user.name=t", "-c", "user.email=t@example.com", *args],
+            cwd=examples,
+            check=True,
+            capture_output=True,
+        )
 
     git("init", "-q")
     git("add", "-A")
@@ -241,26 +272,37 @@ def test_the_word_sample_imports_and_builds_again(examples, pandoc_runtime, tmp_
     out = tmp_path / "imported"
     assert main(["import", "word/design_review.docx", "-o", str(out)]) == 0
     text = (out / "design_review.md").read_text(encoding="utf-8")
-    assert "title: Design review" in text and "- Confirm the sampling interval" in text and "| Sampling interval | Firmware |" in text
+    assert (
+        "title: Design review" in text
+        and "- Confirm the sampling interval" in text
+        and "| Sampling interval | Firmware |" in text
+    )
     assert "[[CAPTION:Figure]] The agreed layout" in text
     assert main(["docx", str(out / "design_review.md")]) == 0
     with zipfile.ZipFile(out / "design_review.docx") as archive:
         assert any(n.startswith("word/media/") for n in archive.namelist())
 
 
-@pytest.mark.skipif(not os.environ.get("PY_DOC_STRUCTURIZR_CLI"), reason="set PY_DOC_STRUCTURIZR_CLI to a structurizr-cli to run it")
+@pytest.mark.skipif(
+    not os.environ.get("PY_DOC_STRUCTURIZR_CLI"), reason="set PY_DOC_STRUCTURIZR_CLI to a structurizr-cli to run it"
+)
 def test_the_real_structurizr_cli_reads_the_dsl_into_the_same_model(tmp_path):
     """#96: the DSL through the real structurizr-cli gives the model the hand-made JSON describes."""
     from py_doc.c4.model import load_workspace
     from py_doc.c4.structurizr import workspace_json
 
     shutil.copytree(EXAMPLES / "architecture", tmp_path / "architecture", ignore=shutil.ignore_patterns(".structurizr"))
-    exported = workspace_json(tmp_path / "architecture" / "workspace.dsl", tmp_path / "cache", cli=os.environ["PY_DOC_STRUCTURIZR_CLI"])
+    exported = workspace_json(
+        tmp_path / "architecture" / "workspace.dsl", tmp_path / "cache", cli=os.environ["PY_DOC_STRUCTURIZR_CLI"]
+    )
     from_cli = load_workspace(exported)
     by_hand = load_workspace(EXAMPLES / "architecture" / "workspace.json")
     assert {e.name for e in from_cli.elements.values()} == {e.name for e in by_hand.elements.values()}
+
     def described(ws):
-        return {(ws.elements[r.source_id].name, ws.elements[r.destination_id].name, r.description) for r in ws.relationships}
+        return {
+            (ws.elements[r.source_id].name, ws.elements[r.destination_id].name, r.description) for r in ws.relationships
+        }
 
     # Structurizr adds implied relationships and those of deployment instances, so the CLI's model has more
     assert described(by_hand) <= described(from_cli)
diff --git a/tests/test_front_matter.py b/tests/test_front_matter.py
index c389d40..9986111 100644
--- a/tests/test_front_matter.py
+++ b/tests/test_front_matter.py
@@ -31,7 +31,9 @@ def test_aliases_map_to_the_standard_keys():
     assert (result.document_id, result.keywords, result.title) == ("X-1", "a, b", "Cased")
 
 
-@pytest.mark.parametrize(("value", "expected"), [("2026-10-05", "2026-10-05"), ("2026-10-05 09:30:00", "2026-10-05T09:30:00")])
+@pytest.mark.parametrize(
+    ("value", "expected"), [("2026-10-05", "2026-10-05"), ("2026-10-05 09:30:00", "2026-10-05T09:30:00")]
+)
 def test_dates_are_written_in_iso_form(value, expected):
     assert meta(f"---\ndate: {value}\n---\n").date == expected
 
diff --git a/tests/test_generators.py b/tests/test_generators.py
index 28caca8..cf60f04 100644
--- a/tests/test_generators.py
+++ b/tests/test_generators.py
@@ -18,7 +18,9 @@ def project(tmp_path, generators: str, documents: str = "documents:\n  guide: {s
         "| ID | Text |\n|---|---|\n| FR-001 | Works |\n\nSee FR-001 and FR-002.\n",
         encoding="utf-8",
     )
-    (tmp_path / "py-doc.yml").write_text(documents + "content:\n  generators:\n" + textwrap.indent(generators, "    "), encoding="utf-8")
+    (tmp_path / "py-doc.yml").write_text(
+        documents + "content:\n  generators:\n" + textwrap.indent(generators, "    "), encoding="utf-8"
+    )
     return load_config(tmp_path / "py-doc.yml")
 
 
@@ -56,16 +58,24 @@ def test_glossary_from_a_file(self, tmp_path):
         assert text.index("| Alpha | First. |") < text.index("| Zeta | Last. |")
 
     def test_documents_index_and_toc(self, tmp_path):
-        text = generated(tmp_path, "- {type: documents, output: out.md}\n- {type: toc, document: guide, output: toc.md}\n")
+        text = generated(
+            tmp_path, "- {type: documents, output: out.md}\n- {type: toc, document: guide, output: toc.md}\n"
+        )
         assert "| [Guide](intro.md) | GD-7 | 2.0 | Draft |" in text
-        assert (tmp_path / "toc.md").read_text(encoding="utf-8").splitlines()[2:] == ["- [Intro](intro.md#intro)", "  - [Scope](intro.md#scope)"]
+        assert (tmp_path / "toc.md").read_text(encoding="utf-8").splitlines()[2:] == [
+            "- [Intro](intro.md#intro)",
+            "  - [Scope](intro.md#scope)",
+        ]
 
     def test_adr_index(self, tmp_path):
         (tmp_path / "adr").mkdir()
         (tmp_path / "adr" / "0001-a.md").write_text("# Use A\n\n## Status\n\nAccepted\n", encoding="utf-8")
         (tmp_path / "adr" / "0002-b.md").write_text("---\nstatus: Superseded\n---\n\n# Use B\n", encoding="utf-8")
         text = generated(tmp_path, "- {type: adr-index, source: adr, output: out.md}\n")
-        assert "| 0001 | [Use A](adr/0001-a.md) | Accepted |  |" in text and "| 0002 | [Use B](adr/0002-b.md) | Superseded |  |" in text
+        assert (
+            "| 0001 | [Use A](adr/0001-a.md) | Accepted |  |" in text
+            and "| 0002 | [Use B](adr/0002-b.md) | Superseded |  |" in text
+        )
 
     def test_requirements_traceability(self, tmp_path):
         text = generated(tmp_path, "- {type: requirements, sources: ['*.md'], output: out.md}\n")
@@ -83,9 +93,14 @@ def test_openapi_and_asyncapi(self, tmp_path):
             encoding="utf-8",
         )
         text = generated(
-            tmp_path, "- {type: openapi, engine: summary, source: o.yml, output: out.md}\n- {type: asyncapi, engine: summary, source: a.yml, output: a.md}\n"
+            tmp_path,
+            "- {type: openapi, engine: summary, source: o.yml, output: out.md}\n- {type: asyncapi, engine: summary, source: a.yml, output: a.md}\n",
+        )
+        assert (
+            "| `GET` | `/pets` | List pets |" in text
+            and "| `POST` | `/pets` | addPet |" in text
+            and "- `Pet`: A pet" in text
         )
-        assert "| `GET` | `/pets` | List pets |" in text and "| `POST` | `/pets` | addPet |" in text and "- `Pet`: A pet" in text
         assert "| `pets/added` | subscribe | PetAdded | New pet |" in (tmp_path / "a.md").read_text(encoding="utf-8")
         with pytest.raises(GeneratorError, match="not an OpenAPI description"):
             generated(tmp_path, "- {type: openapi, engine: summary, source: a.yml, output: out.md}\n")
@@ -114,9 +129,14 @@ def test_command_output_is_the_markdown(self, tmp_path):
             generated(tmp_path, f"- {{type: command, run: {failing}, output: out.md}}\n")
 
     def test_a_python_function_of_your_own(self, tmp_path, monkeypatch):
-        (tmp_path / "mygen.py").write_text("def make(spec, project):\n    return f'# {spec.name} from {project.name}'\n", encoding="utf-8")
+        (tmp_path / "mygen.py").write_text(
+            "def make(spec, project):\n    return f'# {spec.name} from {project.name}'\n", encoding="utf-8"
+        )
         monkeypatch.syspath_prepend(str(tmp_path))
-        text = generated(tmp_path, "- {type: python, callable: 'mygen:make', name: custom, output: out.md}\n", )
+        text = generated(
+            tmp_path,
+            "- {type: python, callable: 'mygen:make', name: custom, output: out.md}\n",
+        )
         assert text == "# custom from None\n"
 
 
@@ -140,7 +160,7 @@ def test_html_headings_and_asides_become_markdown(self):
         raw = (
             '<h1 id="pets-api">Pets API v1</h1>\n\n> Scroll down for code samples, example requests and responses.\n\n'
             '<h2 id="pets-api-default">Default &amp; more</h2>\n\n<aside class="success">\nThis operation does not require authentication\n</aside>\n\n'
-            "```yaml\n# not a heading\n```\n\n# Schemas\n\n<a id=\"schemapet\"></a>\n\n* <a href=\"https://x.org/v1\">https://x.org/v1</a>\n"
+            '```yaml\n# not a heading\n```\n\n# Schemas\n\n<a id="schemapet"></a>\n\n* <a href="https://x.org/v1">https://x.org/v1</a>\n'
         )
         assert clean_markdown(raw, heading_offset=1, title="Pets reference", nest=True) == (
             "## Pets reference\n\n#### Default & more\n\n> [!NOTE]\n> This operation does not require authentication\n\n"
@@ -157,7 +177,10 @@ def test_engine_and_options_are_checked(self, tmp_path):
             project(tmp_path, "- {type: asyncapi, validate: false, source: o.yml, output: out.md}\n")
 
 
-@pytest.mark.skipif(not all(shutil.which(tool) for tool in ("redocly", "widdershins")), reason="Redocly CLI and Widdershins are not installed")
+@pytest.mark.skipif(
+    not all(shutil.which(tool) for tool in ("redocly", "widdershins")),
+    reason="Redocly CLI and Widdershins are not installed",
+)
 def test_openapi_reference_with_the_real_tools(tmp_path, pandoc_runtime):
     from pathlib import Path
 
diff --git a/tests/test_heading_numbers.py b/tests/test_heading_numbers.py
index 9b446a1..c4ae3b6 100644
--- a/tests/test_heading_numbers.py
+++ b/tests/test_heading_numbers.py
@@ -91,7 +91,9 @@ def test_the_options_are_checked(tmp_path):
     )
     config = load_config(tmp_path / "py-doc.yml")
     assert config.documents["d"].outputs["docx"].options["heading_numbers"] == "strip"
-    (tmp_path / "py-doc.yml").write_text("documents:\n  d:\n    sources: [a.md]\n    outputs:\n      docx: {heading_numbers: maybe}\n", encoding="utf-8")
+    (tmp_path / "py-doc.yml").write_text(
+        "documents:\n  d:\n    sources: [a.md]\n    outputs:\n      docx: {heading_numbers: maybe}\n", encoding="utf-8"
+    )
     with pytest.raises(ConfigError, match="heading_numbers must be one of auto, strip, keep"):
         load_config(tmp_path / "py-doc.yml")
 
diff --git a/tests/test_lint.py b/tests/test_lint.py
index 6a3f52b..b55b167 100644
--- a/tests/test_lint.py
+++ b/tests/test_lint.py
@@ -96,7 +96,10 @@ def test_email_addresses_are_skipped(self):
         assert lint("Write to api@example.com.\n") == []
 
     def test_html_and_comments_are_skipped(self):
-        assert lint('<!-- a dtls comment -->\n\n<div class="json">\napi\n</div>\n\nInline <span class="api">ok</span>\n') == []
+        assert (
+            lint('<!-- a dtls comment -->\n\n<div class="json">\napi\n</div>\n\nInline <span class="api">ok</span>\n')
+            == []
+        )
 
     def test_front_matter_is_skipped(self):
         assert lint("---\ntitle: api and json notes\n---\n\n# Notes\n") == []
@@ -158,9 +161,7 @@ def test_same_line_definition_then_use_is_clean(self):
 
     def test_use_before_the_definition_is_reported_with_the_definition_line(self):
         issues = lint("The PSK is used.\n\nPre-Shared Key (PSK) comes later.\n")
-        assert [(i.line, i.message) for i in issues] == [
-            (1, "Acronym 'PSK' is used before it is defined on line 3.")
-        ]
+        assert [(i.line, i.message) for i in issues] == [(1, "Acronym 'PSK' is used before it is defined on line 3.")]
 
     def test_reverse_form_defines_the_acronym(self):
         assert lint("PSK (Pre-Shared Key) is defined.\n\nThe PSK is used.\n") == []
@@ -228,7 +229,9 @@ def test_issues_are_ordered_by_line_then_rule(self):
 
     def test_issue_text_form_has_file_line_severity_rule_and_message(self):
         (issue,) = DocLinter().lint_text("a dtls b\n", file="docs/a.md")
-        assert str(issue).startswith(str(Path("docs/a.md")) + ":1: warning DOC001 [Glossary] Incorrect term capitalization 'dtls'.")
+        assert str(issue).startswith(
+            str(Path("docs/a.md")) + ":1: warning DOC001 [Glossary] Incorrect term capitalization 'dtls'."
+        )
 
     def test_crlf_and_byte_order_mark_do_not_change_line_numbers(self, tmp_path):
         path = tmp_path / "a.md"
diff --git a/tests/test_lint_cli.py b/tests/test_lint_cli.py
index 460e8db..7e6a7d4 100644
--- a/tests/test_lint_cli.py
+++ b/tests/test_lint_cli.py
@@ -167,7 +167,10 @@ def test_default_target_is_the_working_directory(self, tree, monkeypatch, capsys
 
     def test_installed_module_runs_as_a_script(self, tree):
         result = subprocess.run(
-            [sys.executable, "-m", "py_doc.lint.cli", str(tree), "--strict"], capture_output=True, text=True, check=False
+            [sys.executable, "-m", "py_doc.lint.cli", str(tree), "--strict"],
+            capture_output=True,
+            text=True,
+            check=False,
         )
         assert result.returncode == 1
         assert "setup.md:3: warning DOC001" in result.stdout
diff --git a/tests/test_lint_rules.py b/tests/test_lint_rules.py
index 709a209..f892ee1 100644
--- a/tests/test_lint_rules.py
+++ b/tests/test_lint_rules.py
@@ -45,7 +45,9 @@ def test_long_sentences_and_headings(self):
         assert rules(text, config=config) == [(1, "DOC009"), (3, "DOC008")]
 
     def test_the_limits_come_from_py_doc_yml(self, tmp_path):
-        (tmp_path / "py-doc.yml").write_text("lint:\n  limits: {sentence_words: 12, heading_length: 30}\n", encoding="utf-8")
+        (tmp_path / "py-doc.yml").write_text(
+            "lint:\n  limits: {sentence_words: 12, heading_length: 30}\n", encoding="utf-8"
+        )
         lint = load_config(tmp_path / "py-doc.yml").lint
         assert (lint.sentence_words, lint.heading_length) == (12, 30)
 
@@ -88,10 +90,15 @@ def test_document_scope_counts_a_definition_in_an_earlier_file(self, tmp_path):
 
     def test_the_options_come_from_py_doc_yml(self, tmp_path):
         (tmp_path / "py-doc.yml").write_text(
-            "lint:\n  acronyms: {require_definition: false, scope: document, suggestion: Spell it out}\n", encoding="utf-8"
+            "lint:\n  acronyms: {require_definition: false, scope: document, suggestion: Spell it out}\n",
+            encoding="utf-8",
         )
         lint = load_config(tmp_path / "py-doc.yml").lint
-        assert (lint.acronym_require_definition, lint.acronym_scope, lint.acronym_suggestion) == (False, "document", "Spell it out")
+        assert (lint.acronym_require_definition, lint.acronym_scope, lint.acronym_suggestion) == (
+            False,
+            "document",
+            "Spell it out",
+        )
 
 
 class TestQualityChecks:
diff --git a/tests/test_logging_policy.py b/tests/test_logging_policy.py
index e863fe7..0b15102 100644
--- a/tests/test_logging_policy.py
+++ b/tests/test_logging_policy.py
@@ -36,7 +36,9 @@ def test_nothing_imports_colorama_or_configures_logging_itself():
         text = path.read_text(encoding="utf-8")
         if re.search(r"^\s*(import|from)\s+colorama", text, re.M):
             offenders.append(f"{path.name}: colorama")
-        if path.name not in ("_logging.py", "report.py") and re.search(r"logging\.basicConfig|setup_logging\(|addHandler\(", text):
+        if path.name not in ("_logging.py", "report.py") and re.search(
+            r"logging\.basicConfig|setup_logging\(|addHandler\(", text
+        ):
             offenders.append(f"{path.name}: configures logging")
     assert offenders == []
 
@@ -54,8 +56,30 @@ def test_library_modules_do_not_print():
 
 @pytest.mark.parametrize(
     "command",
-    [["docx"], ["slides"], ["lint"], ["build"], ["migrate"], ["doctor"], ["import", "x"], ["c4", "check"], ["c4", "export"], ["template", "check", "x"], ["template", "show", "x"]]
-    + [["init"], ["new"], ["poster"], ["site", "init"], ["site", "generate"], ["site", "build"], ["c4", "up"], ["c4", "down"], ["c4", "status"]]
+    [
+        ["docx"],
+        ["slides"],
+        ["lint"],
+        ["build"],
+        ["migrate"],
+        ["doctor"],
+        ["import", "x"],
+        ["c4", "check"],
+        ["c4", "export"],
+        ["template", "check", "x"],
+        ["template", "show", "x"],
+    ]
+    + [
+        ["init"],
+        ["new"],
+        ["poster"],
+        ["site", "init"],
+        ["site", "generate"],
+        ["site", "build"],
+        ["c4", "up"],
+        ["c4", "down"],
+        ["c4", "status"],
+    ]
     + [["tools", action] for action in ("build", "status", "prune", "lock", "save", "load")],
 )
 def test_every_command_takes_quiet_and_verbose(command, capsys):
diff --git a/tests/test_markdownlint.py b/tests/test_markdownlint.py
index 85d3226..667e7c4 100644
--- a/tests/test_markdownlint.py
+++ b/tests/test_markdownlint.py
@@ -28,7 +28,12 @@ def test_findings_are_parsed_from_the_tool_output():
         "Summary: 2 issues\n"
     )
     found = parse_findings(output, Path("/base"))
-    assert found[0] == (Path("/base/sub/a.md"), 1, "MD022", 'Headings should be surrounded by blank lines [Expected: 1] [Context: "# T"] (blanks-around-headings)')
+    assert found[0] == (
+        Path("/base/sub/a.md"),
+        1,
+        "MD022",
+        'Headings should be surrounded by blank lines [Expected: 1] [Context: "# T"] (blanks-around-headings)',
+    )
     assert found[1][:3] == (Path("/base/a.md"), 4, "MD004")
 
 
@@ -49,9 +54,14 @@ def docs(tmp_path):
 
 @needs_tool
 def test_inline_config_and_severity(docs, runtime):
-    settings = MarkdownlintSettings(inline={"default": True, "MD004": {"style": "dash"}, "MD022": False}, severity="error")
+    settings = MarkdownlintSettings(
+        inline={"default": True, "MD004": {"style": "dash"}, "MD022": False}, severity="error"
+    )
     issues = run_markdownlint([docs / "a.md"], settings, runtime)
-    assert {(i.rule, i.line, i.severity, i.category) for i in issues} == {("MD004", 4, "error", "Markdown"), ("MD004", 5, "error", "Markdown")}
+    assert {(i.rule, i.line, i.severity, i.category) for i in issues} == {
+        ("MD004", 4, "error", "Markdown"),
+        ("MD004", 5, "error", "Markdown"),
+    }
     assert not any(i.rule == "MD022" for i in issues)
     assert issues and all(i.file == docs / "a.md" for i in issues)
 
@@ -97,7 +107,8 @@ class TestCommand:
     def setup(self, docs, tmp_path, extra):
         (tmp_path / "py-doc.yml").write_text(
             "lint:\n  rules: {DOC001: off, DOC002: off, DOC003: off}\n  markdownlint:\n    config: {default: false, MD004: {style: dash}}\n"
-            + extra + "documents:\n  d: {sources: [docs/a.md]}\n",
+            + extra
+            + "documents:\n  d: {sources: [docs/a.md]}\n",
             encoding="utf-8",
         )
 
@@ -113,12 +124,22 @@ def test_strict_and_error_severity_change_the_status(self, docs, tmp_path, runti
         monkeypatch.chdir(tmp_path)
         assert main(["lint", "docs", "--strict"]) == 1
         self.setup(docs, tmp_path, "")
-        text = (tmp_path / "py-doc.yml").read_text().replace("MD004: {style: dash}}", "MD004: {style: dash}}\n    severity: error")
+        text = (
+            (tmp_path / "py-doc.yml")
+            .read_text()
+            .replace("MD004: {style: dash}}", "MD004: {style: dash}}\n    severity: error")
+        )
         (tmp_path / "py-doc.yml").write_text(text, encoding="utf-8")
         assert main(["lint", "docs"]) == 1
 
-    def test_structure_and_markdownlint_findings_share_the_exit_status(self, docs, tmp_path, runtime, monkeypatch, capsys):
-        self.setup(docs, tmp_path, "  structure:\n    - {id: s/star, type: regex-line, severity: error, pattern: '^\\* ', message: no stars}\n")
+    def test_structure_and_markdownlint_findings_share_the_exit_status(
+        self, docs, tmp_path, runtime, monkeypatch, capsys
+    ):
+        self.setup(
+            docs,
+            tmp_path,
+            "  structure:\n    - {id: s/star, type: regex-line, severity: error, pattern: '^\\* ', message: no stars}\n",
+        )
         monkeypatch.chdir(tmp_path)
         assert main(["lint", "docs"]) == 1
         out = capsys.readouterr().out
diff --git a/tests/test_migrate.py b/tests/test_migrate.py
index 88a9c76..7365e5b 100644
--- a/tests/test_migrate.py
+++ b/tests/test_migrate.py
@@ -155,7 +155,10 @@ def test_pdf_only_document_gets_a_pdf_output_and_no_word_file(tmp_path):
 
 def test_html_keeps_its_stylesheet(tmp_path):
     write(tmp_path / "a.md", "# A\n")
-    write(tmp_path / "a.yaml", "cli: {emit-docx: true, emit-html: true, output: out/a.docx, css: s.css}\nentries: [{file: a.md}]\n")
+    write(
+        tmp_path / "a.yaml",
+        "cli: {emit-docx: true, emit-html: true, output: out/a.docx, css: s.css}\nentries: [{file: a.md}]\n",
+    )
     outputs = migrate([tmp_path], tmp_path).config["documents"]["a"]["outputs"]
     assert outputs == {
         "docx": {"path": "out/a.docx", "name": "{name}-{version_safe}"},
@@ -249,7 +252,9 @@ def test_check_reports_and_writes_nothing(self, repo, monkeypatch, capsys):
     def test_repeated_findings_are_grouped(self, repo, monkeypatch, capsys):
         for index in range(4):
             write(repo / "docs" / f"x{index}" / "x.md", "# X\n")
-            write(repo / "docs" / f"x{index}" / "x.yaml", "cli: {emit-md: true, output: x.md}\nentries: [{file: x.md}]\n")
+            write(
+                repo / "docs" / f"x{index}" / "x.yaml", "cli: {emit-md: true, output: x.md}\nentries: [{file: x.md}]\n"
+            )
         monkeypatch.chdir(repo)
         _, out, _ = self.run(monkeypatch, capsys, "docs", "--check")
         assert "4 files: processed Markdown output is not supported yet" in out
diff --git a/tests/test_new.py b/tests/test_new.py
index 12ea678..46d53dc 100644
--- a/tests/test_new.py
+++ b/tests/test_new.py
@@ -21,10 +21,12 @@ def repo(tmp_path, monkeypatch):
     old = tmp_path / "docs" / "notes"
     old.mkdir(parents=True)
     (old / "G460-TN-012-pipelines.yaml").write_text(
-        'meta:\n  title: "Pipelines"\n  document_number: "G460-TN-012"\ncli:\n  emit-docx: true\nentries:\n  - file: a.md\n', encoding="utf-8"
+        'meta:\n  title: "Pipelines"\n  document_number: "G460-TN-012"\ncli:\n  emit-docx: true\nentries:\n  - file: a.md\n',
+        encoding="utf-8",
     )
     (old / "G460-OV-001-overview.yaml").write_text(
-        'meta:\n  title: "Overview"\n  document_number: "G460-OV-001"\ncli:\n  output: o.pptx\nentries:\n  - file: b.md\n', encoding="utf-8"
+        'meta:\n  title: "Overview"\n  document_number: "G460-OV-001"\ncli:\n  output: o.pptx\nentries:\n  - file: b.md\n',
+        encoding="utf-8",
     )
     monkeypatch.chdir(old)
     monkeypatch.setattr(new, "_git_name", lambda: "Ann Author")
@@ -52,7 +54,11 @@ def test_the_first_run_makes_the_register_from_the_existing_build_files(repo):
     assert data["documents"] == [
         {"number": "G460-OV-001", "title": "Overview", "file": "docs/notes/G460-OV-001-overview.yaml"},
         {"number": "G460-TN-012", "title": "Pipelines", "file": "docs/notes/G460-TN-012-pipelines.yaml"},
-        {"number": "G460-TN-013", "title": "Build and Release", "file": "docs/notes/G460-TN-013-Build-and-Release.yaml"},
+        {
+            "number": "G460-TN-013",
+            "title": "Build and Release",
+            "file": "docs/notes/G460-TN-013-Build-and-Release.yaml",
+        },
     ]
     assert [p.name for p in written] == ["G460-TN-013-Build-and-Release.yaml", "G460-TN-013-Build-and-Release.md"]
 
@@ -101,7 +107,11 @@ def test_the_register_is_found_from_a_subfolder_and_numbers_never_repeat(repo, m
 
 @pytest.mark.parametrize(
     ("args", "message"),
-    [(["--type", "TN"], "A title is needed"), (["--title", "x", "--type", "T-N"], "letters and digits"), (["--title", "x", "--format", "pdf"], "invalid choice")],
+    [
+        (["--type", "TN"], "A title is needed"),
+        (["--title", "x", "--type", "T-N"], "letters and digits"),
+        (["--title", "x", "--format", "pdf"], "invalid choice"),
+    ],
 )
 def test_mistakes_are_refused_and_nothing_is_written(repo, args, message, capsys):
     with pytest.raises((new.NewError, SystemExit)):
@@ -119,7 +129,11 @@ def test_an_existing_file_is_not_replaced(repo):
 def test_the_command_reports_what_it_did(repo, capsys):
     assert main(["new", "-y", "--title", "Cmd", "--type", "TN", "--prefix", "G460"]) == 0
     out = capsys.readouterr().out
-    assert "with 2 existing number(s)" in out and "number    G460-TN-013" in out and "py-doc build --legacy G460-TN-013-Cmd.yaml" in out
+    assert (
+        "with 2 existing number(s)" in out
+        and "number    G460-TN-013" in out
+        and "py-doc build --legacy G460-TN-013-Cmd.yaml" in out
+    )
     assert main(["new", "-y"]) == 1
     assert "A title is needed" in capsys.readouterr().err
 
@@ -128,7 +142,9 @@ def test_scan_adds_new_build_files_and_keeps_clashing_numbers(repo, capsys):
     make(["--title", "First", "--type", "TN", "--prefix", "G460"])
     other = repo / "docs" / "other"
     other.mkdir()
-    (other / "copy.yaml").write_text('meta:\n  title: "Copy"\n  document_number: "G460-TN-012"\nentries:\n  - file: c.md\n', encoding="utf-8")
+    (other / "copy.yaml").write_text(
+        'meta:\n  title: "Copy"\n  document_number: "G460-TN-012"\nentries:\n  - file: c.md\n', encoding="utf-8"
+    )
     assert main(["new", "--scan"]) == 0
     out = capsys.readouterr().out
     assert "added     G460-TN-012  docs/other/copy.yaml" in out
@@ -158,7 +174,9 @@ def test_a_bad_start_is_refused(repo, capsys):
         make(["--title", "x"])
 
 
-LISTED = "prefix: G460\nprefixes: [G460, G470]\ntypes: [TN, OV]\nclassifications: [Confidential, Internal]\ndocuments: []\n"
+LISTED = (
+    "prefix: G460\nprefixes: [G460, G470]\ntypes: [TN, OV]\nclassifications: [Confidential, Internal]\ndocuments: []\n"
+)
 
 
 def test_listed_values_are_the_only_ones_allowed_and_keep_the_registers_spelling(repo):
@@ -250,7 +268,11 @@ def test_an_existing_file_takes_its_front_matter_title_and_options_still_win(rep
     ("name", "text", "message"),
     [
         ("numbered.md", "---\ndocument_number: X-001\n---\n# A\n", "already has the document number X-001"),
-        ("a.md", "# Already used\n", "a.md is already a source of docs/notes/G460-TN-012-pipelines.yaml, number G460-TN-012"),
+        (
+            "a.md",
+            "# Already used\n",
+            "a.md is already a source of docs/notes/G460-TN-012-pipelines.yaml, number G460-TN-012",
+        ),
         ("notes.txt", "text\n", "is not a Markdown file"),
     ],
 )
diff --git a/tests/test_pandoc.py b/tests/test_pandoc.py
index c6dea38..5dfe46a 100644
--- a/tests/test_pandoc.py
+++ b/tests/test_pandoc.py
@@ -20,7 +20,9 @@
 from py_doc.runtime import Runtime
 
 needs_pandoc = pytest.mark.skipif(shutil.which("pandoc") is None, reason="pandoc is not installed")
-needs_xelatex = pytest.mark.skipif(not tex_packages_found("ulem.sty", "tcolorbox.sty"), reason="xelatex or one of its packages is not installed")
+needs_xelatex = pytest.mark.skipif(
+    not tex_packages_found("ulem.sty", "tcolorbox.sty"), reason="xelatex or one of its packages is not installed"
+)
 
 
 def png(path: Path) -> Path:
@@ -29,7 +31,10 @@ def chunk(kind: bytes, data: bytes) -> bytes:
 
     rows = b"".join(b"\x00" + b"\xff\x00\x00" * 4 for _ in range(4))
     path.write_bytes(
-        b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", struct.pack(">IIBBBBB", 4, 4, 8, 2, 0, 0, 0)) + chunk(b"IDAT", zlib.compress(rows)) + chunk(b"IEND", b"")
+        b"\x89PNG\r\n\x1a\n"
+        + chunk(b"IHDR", struct.pack(">IIBBBBB", 4, 4, 8, 2, 0, 0, 0))
+        + chunk(b"IDAT", zlib.compress(rows))
+        + chunk(b"IEND", b"")
     )
     return path
 
@@ -337,7 +342,7 @@ def test_marker_filter_makes_captions_and_drops_word_only_markers(tmp_path):
     md.write_text(
         "[[STYLE:Lead Paragraph]] A lead\n\n"
         "[[CAPTION:Figure]] The logo\n![Logo](logo.png)\n\n"
-        "[[CAPTION:Figure]] A diagram\n\n::: {style=\"text-align:center;\"}\n![dot diagram](d.png)\n:::\n\n"
+        '[[CAPTION:Figure]] A diagram\n\n::: {style="text-align:center;"}\n![dot diagram](d.png)\n:::\n\n'
         "[[CAPTION:Table]] Requirements\n\n| A | B |\n|---|---|\n| 1 | 2 |\n\n"
         "[[LANDSCAPE]]\n\n"
         "| C | D |\n|---|---|\n| 3 | 4 |\n\n[[CAPTION:Table]] After the table\n\n"
@@ -354,7 +359,10 @@ def test_marker_filter_makes_captions_and_drops_word_only_markers(tmp_path):
     assert "[[" not in html
     assert "A lead" in html
     for caption in ("The logo", "A diagram", "The code"):
-        assert f"<figcaption>{caption}</figcaption>" in html or f"<figcaption aria-hidden=\"true\">{caption}</figcaption>" in html
+        assert (
+            f"<figcaption>{caption}</figcaption>" in html
+            or f'<figcaption aria-hidden="true">{caption}</figcaption>' in html
+        )
     assert "<caption>Requirements</caption>" in html and "<caption>After the table</caption>" in html
     assert "Alone" in html
 
diff --git a/tests/test_poster.py b/tests/test_poster.py
index 71a703e..ccaed88 100644
--- a/tests/test_poster.py
+++ b/tests/test_poster.py
@@ -135,9 +135,12 @@ def test_the_page_has_every_part_of_the_poster(tmp_path, drawn):
     assert "1. Valve: <span>when it closes</span>" in page
     assert '<p class="caption">Fig. 1 The valve states.</p>' in page
     assert 'class="cards" style="grid-template-columns:repeat(2,minmax(0,1fr))"' in page
-    assert 'border-top:4px solid #2e6b3a' in page
+    assert "border-top:4px solid #2e6b3a" in page
     assert "<blockquote>" in page
-    assert '<div class="lcd"><div class="scr"><div>C 0012.340m3</div><div>Gas ON</div></div><div class="cap">Credit, supply on</div>' in page
+    assert (
+        '<div class="lcd"><div class="scr"><div>C 0012.340m3</div><div>Gas ON</div></div><div class="cap">Credit, supply on</div>'
+        in page
+    )
     assert '<div class="fig-title">Day</div>' in page and 'class="bar" style="min-height:64px"' in page
     assert '<div class="node" style="background:#a3322b">CLOSED</div>' in page
     assert '<div class="cell fill">Scheduled wake‑up</div>' in page
@@ -164,7 +167,13 @@ def test_a_tool_that_draws_only_png_gives_a_png(tmp_path, drawn):
 
 
 def test_a_mermaid_diagram_with_its_own_theme_keeps_it(tmp_path, drawn):
-    build(write(tmp_path, "## A\n\n```mermaid\n%%{init: {}}%%\ngraph LR; A-->B\n```\n\n```mermaid\n---\nconfig: {look: classic}\n---\ngraph LR; C-->D\n```\n"), lambda: object())
+    build(
+        write(
+            tmp_path,
+            "## A\n\n```mermaid\n%%{init: {}}%%\ngraph LR; A-->B\n```\n\n```mermaid\n---\nconfig: {look: classic}\n---\ngraph LR; C-->D\n```\n",
+        ),
+        lambda: object(),
+    )
     assert drawn[0][1] == "%%{init: {}}%%\ngraph LR; A-->B"
     assert drawn[1][1] == "---\nconfig: {look: classic}\n---\ngraph LR; C-->D"
 
@@ -221,7 +230,9 @@ def test_the_command_writes_the_page_next_to_the_markdown(tmp_path, drawn, monke
     assert (tmp_path / "out.html").is_file()
 
 
-@pytest.mark.parametrize("spelling", ["./poster.md", "sub/../poster.md"] + ([".\\poster.md"] if os.name == "nt" else []))
+@pytest.mark.parametrize(
+    "spelling", ["./poster.md", "sub/../poster.md"] + ([".\\poster.md"] if os.name == "nt" else [])
+)
 def test_a_file_is_found_however_its_path_is_written(tmp_path, drawn, monkeypatch, spelling):
     monkeypatch.setattr("py_doc.poster_cli.connect", lambda settings: object())
     write(tmp_path)
@@ -261,7 +272,9 @@ def test_the_example_posters_build(drawn, monkeypatch, name, title):
     page, ctx = build(EXAMPLES / f"{name}.md", lambda: object())
     assert f"<title>{title}</title>" in page
     assert ctx.failed == 0
-    assert "image not found" not in page and "](" not in page.split("</style>", 1)[1], "every picture and link is embedded or rendered"
+    assert "image not found" not in page and "](" not in page.split("</style>", 1)[1], (
+        "every picture and link is embedded or rendered"
+    )
 
 
 def test_an_example_poster_built_on_its_own_has_the_layout_it_was_written_for(drawn):
@@ -389,7 +402,9 @@ def test_settings_win_over_the_front_matter_and_the_defaults_come_last(tmp_path,
     text = "---\ntheme: dark\n---\n## A\n\nText.\n"
     assert "--page:#ffffff;" in build(write(tmp_path, text), lambda: object(), settings={"theme": "print"})[0]
     assert "--page:#141923;" in build(write(tmp_path, text), lambda: object(), defaults={"theme": "print"})[0]
-    assert "--page:#ffffff;" in build(write(tmp_path, "## A\n\nText.\n"), lambda: object(), defaults={"theme": "print"})[0]
+    assert (
+        "--page:#ffffff;" in build(write(tmp_path, "## A\n\nText.\n"), lambda: object(), defaults={"theme": "print"})[0]
+    )
 
 
 @pytest.mark.parametrize(
@@ -440,7 +455,9 @@ def test_the_poster_section_takes_every_poster_setting(tmp_path):
         parse_config({"poster": {"columns": 2.5}}, tmp_path)
     with pytest.raises(ConfigError, match="unknown key 'middle' in poster.footer"):
         parse_config({"poster": {"footer": {"middle": "x"}}}, tmp_path)
-    config = parse_config({"poster": {"theme": "brand.yml", "logo": "logo.svg", "footer": {"logos": ["a.png"]}}}, tmp_path)
+    config = parse_config(
+        {"poster": {"theme": "brand.yml", "logo": "logo.svg", "footer": {"logos": ["a.png"]}}}, tmp_path
+    )
     assert config.poster["theme"] == tmp_path / "brand.yml" and config.poster["logo"] == tmp_path / "logo.svg"
     assert config.poster["footer"]["logos"] == [tmp_path / "a.png"]
     assert parse_config({"poster": {"theme": "dark"}}, tmp_path).poster["theme"] == "dark"
@@ -457,7 +474,10 @@ def project(tmp_path, posters, defaults=None):
 
 
 def test_a_poster_of_py_doc_yml_has_its_source_output_and_settings(tmp_path):
-    config = parse_config({"posters": {"sn100": {"source": "p.md", "orientation": "landscape", "colours": {"primary": "#123456"}}}}, tmp_path)
+    config = parse_config(
+        {"posters": {"sn100": {"source": "p.md", "orientation": "landscape", "colours": {"primary": "#123456"}}}},
+        tmp_path,
+    )
     poster = config.posters["sn100"]
     assert (poster.source, poster.output) == (tmp_path / "p.md", tmp_path / "build" / "sn100.html")
     assert poster.settings == {"orientation": "landscape", "colours": {"primary": "#123456"}}
@@ -470,7 +490,9 @@ def test_a_poster_of_py_doc_yml_has_its_source_output_and_settings(tmp_path):
 def test_every_poster_of_py_doc_yml_is_built_with_its_entry_over_the_front_matter(tmp_path, drawn, monkeypatch, capsys):
     monkeypatch.setattr("py_doc.poster_cli.connect", lambda settings: object())
     monkeypatch.chdir(tmp_path)
-    write(tmp_path, "---\norientation: portrait\ncolours: {primary: '#111111', accent: '#222222'}\n---\n## A\n\nText.\n")
+    write(
+        tmp_path, "---\norientation: portrait\ncolours: {primary: '#111111', accent: '#222222'}\n---\n## A\n\nText.\n"
+    )
     project(
         tmp_path,
         {"wall": {"source": "poster.md", "output": "out/wall.html", "orientation": "landscape", "colours": {"primary": "#333333"}},
@@ -485,7 +507,10 @@ def test_every_poster_of_py_doc_yml_is_built_with_its_entry_over_the_front_matte
     assert 'class="poster portrait"' in desk and "--primary:#111111;" in desk
     assert main(["poster", "desk"]) == 0
     assert main(["poster", "nothing"]) == 1
-    assert "is not a Markdown file or a poster of py-doc.yml. The posters of py-doc.yml are: wall, desk" in capsys.readouterr().err
+    assert (
+        "is not a Markdown file or a poster of py-doc.yml. The posters of py-doc.yml are: wall, desk"
+        in capsys.readouterr().err
+    )
     assert main(["poster", "-o", "x.html"]) == 1
 
 
@@ -512,7 +537,7 @@ def test_includes_conditions_and_variables_from_the_settings(tmp_path, drawn):
     text = "---\nvariables: {name: text}\nconditions: {internal: true}\n---\n## A\n\n[[INCLUDE: part.md]]\n\n[[INCLUDE-CODE: code.py]]\n\n[[NOT: internal]]\nPublic.\n[[ENDIF]]\n"
     page, _ = build(write(tmp_path, text), lambda: object())
     assert "Included text." in page and "Public." not in page
-    assert '<pre><code class="language-python">print(\'hi\')' in page
+    assert "<pre><code class=\"language-python\">print('hi')" in page
 
 
 def test_a_missing_include_is_an_error_with_the_file(tmp_path):
@@ -550,7 +575,10 @@ def test_captions_callouts_and_word_markers(tmp_path, drawn):
     )
     page, _ = build(write(tmp_path, text), lambda: object())
     assert '<p class="caption"><strong>Figure 1:</strong> The valve.</p>' in page
-    assert '<blockquote class="callout warning"><p class="callout-title">Warning</p><p>Disconnect the battery first.</p>' in page
+    assert (
+        '<blockquote class="callout warning"><p class="callout-title">Warning</p><p>Disconnect the battery first.</p>'
+        in page
+    )
     assert '<blockquote class="callout tip">\n<p><strong>Tip:</strong> use the app.</p>' in page
     assert "<blockquote>\n<p>A plain quote.</p>" in page
     assert "<p>Lead text.</p>" in page
@@ -604,15 +632,26 @@ def test_every_kind_of_section_takes_a_style_and_a_colour(tmp_path, drawn):
         "## In short {.summary style=line colour=navy}\n\nThe point.\n\n### Then\n\nMore.\n\n"
         "## Sources {.references style=list colour=grey}\n\n1. A paper.\n"
     )
-    page = build(write(tmp_path, "---\npalette: {teal: '#0f5e5e', coral: '#e8684a'}\n---\n" + text), lambda: object())[0]
+    page = build(write(tmp_path, "---\npalette: {teal: '#0f5e5e', coral: '#e8684a'}\n---\n" + text), lambda: object())[
+        0
+    ]
     body = page.split("<main>", 1)[1]
     assert '<div class="stats s-tiles" style="--c:#0f5e5e">' in body
     assert '<div class="abstract s-quote" style="--c:#e8684a"><p>Because.' in body
-    assert '<section class="s-card" style="--c:#b4540a"><h2>1. A</h2>' in body and '<section class="s-line"><h2>2. B</h2>' in body
+    assert (
+        '<section class="s-card" style="--c:#b4540a"><h2>1. A</h2>' in body
+        and '<section class="s-line"><h2>2. B</h2>' in body
+    )
     assert '<div class="summary s-line" style="--c:#2a3150"><div class="banner">The point.</div>' in body
     assert '<div class="refs s-list" style="--c:#4a4f5c"><b>Sources</b>' in body
     css = page.split("<style>", 1)[1]
-    for rule in ("section.s-card{", ".stats.s-tiles .stat{background:var(--c,var(--primary))", ".abstract.s-quote{", ".summary.s-line .block{", ".refs.s-list ol"):
+    for rule in (
+        "section.s-card{",
+        ".stats.s-tiles .stat{background:var(--c,var(--primary))",
+        ".abstract.s-quote{",
+        ".summary.s-line .block{",
+        ".refs.s-list ol",
+    ):
         assert rule in css, rule
 
 
@@ -655,7 +694,9 @@ def test_an_unknown_heading_attribute_is_a_warning(tmp_path, drawn, caplog):
 def test_the_header_aligns_and_puts_the_logo_on_either_side_or_none(tmp_path, drawn):
     (tmp_path / "logo.png").write_bytes(PNG)
     base = "logo: logo.png\n"
-    page, _ = build(write(tmp_path, f"---\n{base}header: {{align: left, logo: right}}\n---\n## A\n\nText.\n"), lambda: object())
+    page, _ = build(
+        write(tmp_path, f"---\n{base}header: {{align: left, logo: right}}\n---\n## A\n\nText.\n"), lambda: object()
+    )
     assert '<header class="align-left logo-right"><img alt="Logo"' in page
     page, _ = build(write(tmp_path, f"---\n{base}header: {{logo: none}}\n---\n## A\n\nText.\n"), lambda: object())
     assert '<header class="align-centre"><h1>' in page
@@ -667,7 +708,9 @@ def test_the_footer_has_three_texts_logos_and_a_qr_code(tmp_path, drawn):
     (tmp_path / "a.png").write_bytes(PNG)
     text = "---\nfooter: {left: '**SN-100**', centre: Middle, right: Right, logos: [a.png], qr: 'https://example.com/sn100', qr-label: Scan me}\n---\n## A\n\nText.\n"
     page, _ = build(write(tmp_path, text), lambda: object())
-    assert '<b class="fl"><strong>SN-100</strong></b><span class="fc">Middle</span><span class="fr">Right</span>' in page
+    assert (
+        '<b class="fl"><strong>SN-100</strong></b><span class="fc">Middle</span><span class="fr">Right</span>' in page
+    )
     assert '<div class="logos"><img alt="Logo" src="data:image/png;base64,' in page
     assert '<div class="fqr"><svg' in page and "<span>Scan me</span>" in page
     with pytest.raises(PosterError, match="footer logo not found"):
@@ -693,7 +736,9 @@ def test_stats_show_a_trend_whose_colour_follows_its_direction_or_verdict(tmp_pa
 
 def test_a_timeline_is_a_row_or_a_column_of_milestones(tmp_path, drawn):
     code = "Jan 2026 | Design | frozen | coral\nMar 2026 | Pilot"
-    page, _ = build(write(tmp_path, f"## A\n\n```timeline\n{code}\n```\n\n```timeline vertical\n{code}\n```\n"), lambda: object())
+    page, _ = build(
+        write(tmp_path, f"## A\n\n```timeline\n{code}\n```\n\n```timeline vertical\n{code}\n```\n"), lambda: object()
+    )
     assert '<i style="background:coral"></i><b>Jan 2026</b><span>Design</span><small>frozen</small>' in page
     assert '<i style="background:#4a7fc1"></i><b>Mar 2026</b><span>Pilot</span></div>' in page  # the accent by default
     assert '<div class="timeline vertical">' in page
@@ -715,11 +760,20 @@ def chart_svg(tmp_path, options, rows="series: Measured, Target\nQ1 | 2.9 | 2.5\
 
 
 def test_a_line_chart_takes_min_step_values_markers_area_dashed_and_an_axis_title(tmp_path, drawn):
-    svg = chart_svg(tmp_path, 'type=line min=2 max=3 step=0.25 values=last unit=" V" area=yes markers=no dashed=Target axis="Cell (V)"')
-    assert [label for label in re.findall(r'text-anchor="end"[^>]*>([\d.]+)</text>', svg)] == ["2", "2.25", "2.5", "2.75", "3"]
+    svg = chart_svg(
+        tmp_path,
+        'type=line min=2 max=3 step=0.25 values=last unit=" V" area=yes markers=no dashed=Target axis="Cell (V)"',
+    )
+    assert [label for label in re.findall(r'text-anchor="end"[^>]*>([\d.]+)</text>', svg)] == [
+        "2",
+        "2.25",
+        "2.5",
+        "2.75",
+        "3",
+    ]
     assert re.findall(r">([\d.]+ V)</text>", svg) == ["2.6 V", "2.5 V"], "only the last value of each series"
     assert "<circle" not in svg and svg.count("<polygon") == 2 and svg.count('stroke-dasharray="10 6"') == 1
-    assert 'rotate(-90' in svg and ">Cell (V)</text>" in svg
+    assert "rotate(-90" in svg and ">Cell (V)</text>" in svg
     labels = re.findall(r'y="([\d.]+)" text-anchor="middle"[^>]*>(2\.\d) V</text>', svg)
     assert float(labels[1][0]) - float(labels[0][0]) >= 16, "two labels at one point do not overlap"
     svg = chart_svg(tmp_path, "type=line")
@@ -727,7 +781,14 @@ def test_a_line_chart_takes_min_step_values_markers_area_dashed_and_an_axis_titl
 
 
 def test_column_and_bar_values_can_be_left_out_and_their_axis_named(tmp_path, drawn):
-    assert re.findall(r">([\d.]+)</text>", chart_svg(tmp_path, "type=column values=none step=1")) == ["0", "1", "2", "3", "4", "5"]
+    assert re.findall(r">([\d.]+)</text>", chart_svg(tmp_path, "type=column values=none step=1")) == [
+        "0",
+        "1",
+        "2",
+        "3",
+        "4",
+        "5",
+    ]
     svg = chart_svg(tmp_path, 'type=bar values=last axis="Charge (uC)"')
     assert re.findall(r">([\d.]+)</text>", svg) == ["2.6", "2.5"] and ">Charge (uC)</text>" in svg
 
@@ -768,16 +829,24 @@ def test_steps_are_numbered_from_start_in_columns_with_their_colours(tmp_path, d
     code = "```steps cols=2 start=3\nFit the gateway | Before any node\nJoin | | coral\n```"
     page, _ = build(write(tmp_path, f"## A\n\n{code}\n"), lambda: object())
     assert '<ol class="steps" start="3" style="grid-template-columns:repeat(2,minmax(0,1fr))">' in page
-    assert '<b class="num" style="background:#2a3150">3</b><div><div class="ch">Fit the gateway</div><div class="ct">Before any node</div>' in page
+    assert (
+        '<b class="num" style="background:#2a3150">3</b><div><div class="ch">Fit the gateway</div><div class="ct">Before any node</div>'
+        in page
+    )
     assert '<b class="num" style="background:coral">4</b><div><div class="ch">Join</div></div>' in page
 
 
 def test_a_gallery_embeds_its_pictures_with_captions_cropped_to_one_height(tmp_path, drawn):
     (tmp_path / "a.png").write_bytes(PNG)
     (tmp_path / "b.svg").write_bytes(SVG)
-    page, _ = build(write(tmp_path, "## A\n\n```gallery height=160\na.png | The *gateway*\nb.svg\n```\n"), lambda: object())
+    page, _ = build(
+        write(tmp_path, "## A\n\n```gallery height=160\na.png | The *gateway*\nb.svg\n```\n"), lambda: object()
+    )
     assert '<div class="gallery" style="grid-template-columns:repeat(2,minmax(0,1fr))">' in page
-    assert '<img alt="The gateway" src="data:image/png;base64,' in page and "<figcaption>The <em>gateway</em></figcaption>" in page
+    assert (
+        '<img alt="The gateway" src="data:image/png;base64,' in page
+        and "<figcaption>The <em>gateway</em></figcaption>" in page
+    )
     assert 'src="data:image/svg+xml;base64,' in page and 'alt="b"' in page
     assert page.count('style="height:160px;object-fit:cover"') == 2
 
@@ -803,41 +872,65 @@ def block(tmp_path, code):
 
 def test_progress_bars_fill_towards_their_targets_and_say_when_they_are_met(tmp_path, drawn):
     html = block(tmp_path, '```progress unit=" nodes"\nJoined | 48 | 50\nLabelled | 1,200 | 1,000\n```')
-    assert '<span>Joined</span><b>48 nodes of 50 nodes</b>' in html and 'width:96.0%;background:#4a7fc1' in html
-    assert '<b>1,200 nodes of 1,000 nodes &#10003;</b>' in html and 'width:100.0%;background:#2e6b3a' in html, "capped, and met"
-    html = block(tmp_path, "```progress better=lower show=percent\nReturn rate | 0.51 | 0.50\nDead on arrival | 0.1 | 0.5\n```")
-    assert '<b>102 %</b>' in html and 'background:#a3322b' in html, "over a ceiling is bad news"
-    assert '<b>20 % &#10003;</b>' in html
+    assert "<span>Joined</span><b>48 nodes of 50 nodes</b>" in html and "width:96.0%;background:#4a7fc1" in html
+    assert "<b>1,200 nodes of 1,000 nodes &#10003;</b>" in html and "width:100.0%;background:#2e6b3a" in html, (
+        "capped, and met"
+    )
+    html = block(
+        tmp_path, "```progress better=lower show=percent\nReturn rate | 0.51 | 0.50\nDead on arrival | 0.1 | 0.5\n```"
+    )
+    assert "<b>102 %</b>" in html and "background:#a3322b" in html, "over a ceiling is bad news"
+    assert "<b>20 % &#10003;</b>" in html
 
 
 def test_a_checklist_has_done_open_and_failed_items(tmp_path, drawn):
-    html = block(tmp_path, "```checklist cols=2\n[x] Signal -95 dBm or better\n[ ] Label photo\n[!] First reading within *2 min*\n```")
+    html = block(
+        tmp_path,
+        "```checklist cols=2\n[x] Signal -95 dBm or better\n[ ] Label photo\n[!] First reading within *2 min*\n```",
+    )
     assert '<ul class="checklist" style="grid-template-columns:repeat(2,minmax(0,1fr))">' in html
     assert '<li class="done"><span class="box">&#10003;</span><span>Signal -95 dBm or better</span></li>' in html
     assert '<li class="open"><span class="box"></span><span>Label photo</span></li>' in html
-    assert '<li class="failed"><span class="box">&#10007;</span><span>First reading within <em>2 min</em></span></li>' in html
+    assert (
+        '<li class="failed"><span class="box">&#10007;</span><span>First reading within <em>2 min</em></span></li>'
+        in html
+    )
 
 
 def test_compare_puts_a_header_over_matched_rows_and_stresses_the_last_column(tmp_path, drawn):
-    html = block(tmp_path, "```compare\n| Firmware 2.0 | Firmware 2.1\nJoin | 11 s | 4 s\nMessages a day | 1,440 | 610\n```")
-    assert 'grid-template-columns:minmax(0,1.2fr) repeat(2,minmax(0,1fr))' in html
+    html = block(
+        tmp_path, "```compare\n| Firmware 2.0 | Firmware 2.1\nJoin | 11 s | 4 s\nMessages a day | 1,440 | 610\n```"
+    )
+    assert "grid-template-columns:minmax(0,1.2fr) repeat(2,minmax(0,1fr))" in html
     assert '<div class="cmp-h">Firmware 2.0</div><div class="cmp-h last">Firmware 2.1</div>' in html
     assert '<div class="cmp-l">Join</div><div class="cmp-v">11 s</div><div class="cmp-v last">4 s</div>' in html
 
 
 def test_people_have_their_photo_or_their_initials(tmp_path, drawn):
     (tmp_path / "jp.png").write_bytes(PNG)
-    html = block(tmp_path, "```people\nJaya Patel | Product engineering | jp@example.com | jp.png\nRuth Osei-Mensah | Field support\n```")
+    html = block(
+        tmp_path,
+        "```people\nJaya Patel | Product engineering | jp@example.com | jp.png\nRuth Osei-Mensah | Field support\n```",
+    )
     assert '<div class="person"><img alt="Jaya Patel" src="data:image/png;base64,' in html
     assert '<div class="ch">Jaya Patel</div><div>Product engineering</div><div>jp@example.com</div>' in html
-    assert '<b style="background:#2a3150">RO</b><div><div class="ch">Ruth Osei-Mensah</div><div>Field support</div></div>' in html
+    assert (
+        '<b style="background:#2a3150">RO</b><div><div class="ch">Ruth Osei-Mensah</div><div>Field support</div></div>'
+        in html
+    )
     assert 'style="grid-template-columns:repeat(2,minmax(0,1fr))"' in html
 
 
 def test_highlights_show_figures_in_large_type_in_their_colours(tmp_path, drawn):
     html = block(tmp_path, "```highlight\n0 | Failed updates | in 200 pilot nodes | good\n4 s | Typical join\n```")
-    assert '<div class="hl" style="border-color:#2e6b3a"><b style="color:#2e6b3a">0</b><span>Failed updates</span><small>in 200 pilot nodes</small></div>' in html
-    assert '<div class="hl" style="border-color:#4a7fc1"><b style="color:#4a7fc1">4 s</b><span>Typical join</span></div>' in html
+    assert (
+        '<div class="hl" style="border-color:#2e6b3a"><b style="color:#2e6b3a">0</b><span>Failed updates</span><small>in 200 pilot nodes</small></div>'
+        in html
+    )
+    assert (
+        '<div class="hl" style="border-color:#4a7fc1"><b style="color:#4a7fc1">4 s</b><span>Typical join</span></div>'
+        in html
+    )
 
 
 @pytest.mark.parametrize(
@@ -867,18 +960,30 @@ def test_lcd_screens_in_columns_and_rows(tmp_path, drawn, info, columns):
 
 
 def test_two_lcd_screens_sit_side_by_side_as_before(tmp_path, drawn):
-    page, _ = build(write(tmp_path, "## A\n\n```lcd\nJOINED GW-2\n-- Good signal\n\nT 21.4 C\n-- First reading\n```\n"), lambda: object())
+    page, _ = build(
+        write(tmp_path, "## A\n\n```lcd\nJOINED GW-2\n-- Good signal\n\nT 21.4 C\n-- First reading\n```\n"),
+        lambda: object(),
+    )
     assert '<div class="lcds" style="grid-template-columns:repeat(2,minmax(0,1fr))">' in page
 
 
 def test_a_qr_block_draws_the_code_with_its_label(tmp_path, drawn):
-    page, _ = build(write(tmp_path, '## A\n\n```qr size=200 label="The manual"\nhttps://example.com/manual\n```\n'), lambda: object())
+    page, _ = build(
+        write(tmp_path, '## A\n\n```qr size=200 label="The manual"\nhttps://example.com/manual\n```\n'),
+        lambda: object(),
+    )
     assert '<div class="qr"><svg' in page and '<div class="cap">The manual</div>' in page
     assert 'stroke="#2a3150"' in page
 
 
 def test_references_are_a_list_above_the_footer(tmp_path, drawn):
-    page, _ = build(write(tmp_path, "## A\n\nText [1].\n\n## References {.references}\n\n1. SN-100 datasheet, SN-DS-001.\n1. MQTT 5.0, OASIS.\n"), lambda: object())
+    page, _ = build(
+        write(
+            tmp_path,
+            "## A\n\nText [1].\n\n## References {.references}\n\n1. SN-100 datasheet, SN-DS-001.\n1. MQTT 5.0, OASIS.\n",
+        ),
+        lambda: object(),
+    )
     refs = page.split('<div class="refs s-columns">', 1)[1]
     assert refs.startswith("<b>References</b><ol>") and "<li>MQTT 5.0, OASIS.</li>" in refs
     assert refs.index("</ol>") < refs.index("<footer>")
@@ -903,7 +1008,9 @@ def test_the_old_and_new_footer_keys_combine(tmp_path, drawn):
 @pytest.mark.parametrize("orientation", ["portrait", "landscape"])
 def test_the_poster_is_never_taller_than_its_page(tmp_path, drawn, paper, orientation):
     """A poster even a fraction of a millimetre taller than the page prints a second, empty page."""
-    page, _ = build(write(tmp_path, f"---\npaper: {paper}\norientation: {orientation}\n---\n## A\n\nText.\n"), lambda: object())
+    page, _ = build(
+        write(tmp_path, f"---\npaper: {paper}\norientation: {orientation}\n---\n## A\n\nText.\n"), lambda: object()
+    )
     ratio = float(re.search(r"R=([\d.]+)", page)[1])
     width, height = (int(x) for x in re.search(r"size:(\d+)mm (\d+)mm", page).groups())
     assert width * ratio <= height and height - width * ratio < 0.1  # under a tenth of a millimetre short
@@ -919,7 +1026,9 @@ def __init__(self, output=b"%PDF-1.7\n%fake\n"):
         self.calls, self.output = [], output
 
     def run(self, argv, *, mounts=(), workdir=None, env=None, timeout=None, **_):
-        self.calls.append({"argv": argv, "mounts": mounts, "env": env, "page": Path(argv[2]).read_text(encoding="utf-8")})
+        self.calls.append(
+            {"argv": argv, "mounts": mounts, "env": env, "page": Path(argv[2]).read_text(encoding="utf-8")}
+        )
         Path(argv[3]).write_bytes(self.output)
 
 
@@ -961,7 +1070,9 @@ def test_the_pdf_setting_and_the_pdf_option(tmp_path, drawn, monkeypatch, capsys
 def test_the_pdf_gets_the_web_fonts_the_page_only_links(tmp_path, drawn, monkeypatch):
     pages, asked = [], []
     monkeypatch.setattr("py_doc.poster.print_pdf", lambda runtime, page, pdf: pages.append(page))
-    monkeypatch.setattr("py_doc.poster.web_faces", lambda sheet, where, **kw: asked.append(kw) or "@font-face{font-family:X}")
+    monkeypatch.setattr(
+        "py_doc.poster.web_faces", lambda sheet, where, **kw: asked.append(kw) or "@font-face{font-family:X}"
+    )
     source = write(tmp_path, "## A\n\nText.\n")
     write_poster(source, tmp_path / "p.html", lambda: object(), pdf=True)
     page = (tmp_path / "p.html").read_text(encoding="utf-8")
@@ -996,15 +1107,18 @@ def test_the_footer_shows_the_document_and_version_in_small_type(tmp_path, drawn
 
 
 def test_the_document_number_and_version_of_the_front_matter_are_the_defaults(tmp_path, drawn):
-    page, _ = build(write(tmp_path, "---\ndocument_number: SN-PO-004\nversion: '3.0'\n---\n## A\n\nText.\n"), lambda: object())
+    page, _ = build(
+        write(tmp_path, "---\ndocument_number: SN-PO-004\nversion: '3.0'\n---\n## A\n\nText.\n"), lambda: object()
+    )
     assert '<div class="docinfo"><span>SN-PO-004</span><span>Version 3.0</span></div>' in page
-    page, _ = build(write(tmp_path, "---\nversion: '3.0'\nfooter: {version: 3.1}\n---\n## A\n\nText.\n"), lambda: object())
+    page, _ = build(
+        write(tmp_path, "---\nversion: '3.0'\nfooter: {version: 3.1}\n---\n## A\n\nText.\n"), lambda: object()
+    )
     assert '<div class="docinfo"><span>Version 3.1</span></div>' in page  # the footer's own wins
     page, _ = build(write(tmp_path, "## A\n\nText.\n"), lambda: object())
     assert 'class="docinfo"' not in page
 
 
-
 def test_version_git_is_the_git_describe_of_the_poster_folder(tmp_path, drawn, monkeypatch):
     asked = []
     monkeypatch.setattr("py_doc.poster.git_version", lambda folder: asked.append(folder) or "v2.1-3-g1a2b3c4")
@@ -1021,9 +1135,12 @@ def test_version_git_outside_a_repository_is_an_error(tmp_path, drawn, monkeypat
         build(write(tmp_path, "---\nversion: git\n---\n## A\n\nText.\n"), lambda: object())
 
 
-
 def test_the_project_mermaid_settings_go_under_the_theme_colours(tmp_path, drawn):
-    build(write(tmp_path, "## A\n\n```mermaid\ngraph LR\n```\n"), lambda: object(), mermaid={"look": "classic", "theme": "neutral"})
+    build(
+        write(tmp_path, "## A\n\n```mermaid\ngraph LR\n```\n"),
+        lambda: object(),
+        mermaid={"look": "classic", "theme": "neutral"},
+    )
     config = json.loads(drawn[0][1].split("\n")[1])["config"]
     assert config["look"] == "classic" and config["theme"] == "base"  # the poster theme's colours win
     assert config["themeVariables"]["primaryColor"]
@@ -1050,7 +1167,10 @@ def build_document(config, doc, formats, *args, **kwargs):
 def build_project(tmp_path, documents=True):
     write(tmp_path, "## A\n\nText.\n")
     (tmp_path / "guide.md").write_text("# Guide\n\nText.\n", encoding="utf-8")
-    data = {"posters": {"wall": {"source": "poster.md"}, "desk": {"source": "poster.md", "pdf": True}}, "reports": {"path": "build/report.json"}}
+    data = {
+        "posters": {"wall": {"source": "poster.md"}, "desk": {"source": "poster.md", "pdf": True}},
+        "reports": {"path": "build/report.json"},
+    }
     if documents:
         data["documents"] = {"guide": {"sources": ["guide.md"]}}
     (tmp_path / "py-doc.yml").write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
@@ -1068,14 +1188,20 @@ def test_build_makes_the_documents_then_every_poster(tmp_path, drawn, documents,
     assert {"step": "posters", "status": "ok", "detail": "2 of 2 built"} in report["steps"]
     outputs = {o["path"]: o["format"] for d in report["documents"] for o in d["outputs"]}
     assert outputs == {"build/wall.html": "html", "build/desk.html": "html", "build/desk.pdf": "pdf"}
-    jsonschema.validate(report, json.loads((Path(py_doc.__file__).parent / "report.schema.json").read_text(encoding="utf-8")))
+    jsonschema.validate(
+        report, json.loads((Path(py_doc.__file__).parent / "report.schema.json").read_text(encoding="utf-8"))
+    )
 
 
 def test_build_names_documents_or_posters(tmp_path, drawn, documents, monkeypatch, capsys):
     monkeypatch.chdir(tmp_path)
     build_project(tmp_path)
     assert main(["build", "wall"]) == 0
-    assert documents == [] and (tmp_path / "build" / "wall.html").is_file() and not (tmp_path / "build" / "desk.html").exists()
+    assert (
+        documents == []
+        and (tmp_path / "build" / "wall.html").is_file()
+        and not (tmp_path / "build" / "desk.html").exists()
+    )
     assert main(["build", "guide"]) == 0
     assert [name for name, _ in documents] == ["guide"] and not (tmp_path / "build" / "desk.html").exists()
     assert main(["build", "nothing"]) == 1
@@ -1173,7 +1299,9 @@ def urlopen(request, timeout=None):
 
 def font_theme(tmp_path, extra=""):
     (tmp_path / "theme.yml").write_text(
-        "fonts:\n  body: \"'Brand Sans', Arial, sans-serif\"\n  stylesheet: https://fonts.example.com/css?family=Brand\n" + extra, encoding="utf-8"
+        "fonts:\n  body: \"'Brand Sans', Arial, sans-serif\"\n  stylesheet: https://fonts.example.com/css?family=Brand\n"
+        + extra,
+        encoding="utf-8",
     )
 
 
@@ -1181,12 +1309,18 @@ def test_a_theme_s_font_files_are_embedded(tmp_path, drawn):
     (tmp_path / "fonts").mkdir()
     (tmp_path / "fonts" / "Brand-Bold.woff2").write_bytes(WOFF2)
     (tmp_path / "theme.yml").write_text(
-        "fonts:\n  heading: \"'Brand', Arial, sans-serif\"\n  files:\n    - {family: Brand, file: fonts/Brand-Bold.woff2, weight: 700}\n", encoding="utf-8"
+        "fonts:\n  heading: \"'Brand', Arial, sans-serif\"\n  files:\n    - {family: Brand, file: fonts/Brand-Bold.woff2, weight: 700}\n",
+        encoding="utf-8",
     )
     page, _ = build(write(tmp_path, "---\ntheme: theme.yml\n---\n## A\n\nText.\n"), lambda: object())
     data = base64.b64encode(WOFF2).decode()
-    assert f"@font-face{{font-family:'Brand';font-weight:700;font-style:normal;font-display:swap;src:url(data:font/woff2;base64,{data}) format('woff2')}}" in page
-    assert '<link rel="stylesheet" href="https://fonts.googleapis.com/' in page  # the default stylesheet is still linked
+    assert (
+        f"@font-face{{font-family:'Brand';font-weight:700;font-style:normal;font-display:swap;src:url(data:font/woff2;base64,{data}) format('woff2')}}"
+        in page
+    )
+    assert (
+        '<link rel="stylesheet" href="https://fonts.googleapis.com/' in page
+    )  # the default stylesheet is still linked
 
 
 def test_font_files_named_in_py_doc_yml_are_from_py_doc_yml(tmp_path):
@@ -1201,7 +1335,7 @@ def test_font_files_named_in_py_doc_yml_are_from_py_doc_yml(tmp_path):
     [
         ("files: x", "fonts.files must be a list"),
         ("files:\n    - {file: a.woff2}", r"fonts.files\[1\] needs a family and a file"),
-        ("files:\n    - {family: \"A'; }\", file: a.woff2}", "has a character a font name cannot have"),
+        ('files:\n    - {family: "A\'; }", file: a.woff2}', "has a character a font name cannot have"),
         ("files:\n    - {family: A, file: a.woff2, weight: bold}", "weight must be 100 to 900"),
         ("files:\n    - {family: A, file: a.woff2, style: oblique}", "style must be normal or italic"),
         ("files:\n    - {family: A, file: a.png}", "is not a font file"),
@@ -1277,7 +1411,10 @@ def test_embed_fonts_is_true_false_or_a_list_of_subsets(tmp_path):
     for bad in ("yes", [], ["Latin!"], [3]):
         with pytest.raises(ConfigError, match="poster.embed_fonts must be true, false or a list of subsets"):
             parse_config({"poster": {"embed_fonts": bad}}, tmp_path)
-    assert parse_config({"poster": {"embed_fonts": ["latin", "latin-ext"]}}, tmp_path).poster["embed_fonts"] == ["latin", "latin-ext"]
+    assert parse_config({"poster": {"embed_fonts": ["latin", "latin-ext"]}}, tmp_path).poster["embed_fonts"] == [
+        "latin",
+        "latin-ext",
+    ]
 
 
 SUBSET_CSS = """/* cyrillic */
@@ -1303,14 +1440,18 @@ def test_embed_fonts_with_subsets_keeps_and_downloads_only_those(tmp_path, drawn
     pages["https://fonts.example.com/css?family=Brand"] = SUBSET_CSS.encode()
     pages["https://fonts.example.com/brand-cyrillic.woff2"] = b"cyrillic"
     font_theme(tmp_path)
-    page, _ = build(write(tmp_path, "---\ntheme: theme.yml\nembed_fonts: [latin]\n---\n## A\n\nText.\n"), lambda: object())
+    page, _ = build(
+        write(tmp_path, "---\ntheme: theme.yml\nembed_fonts: [latin]\n---\n## A\n\nText.\n"), lambda: object()
+    )
     assert "brand-cyrillic" not in " ".join(asked) and base64.b64encode(b"cyrillic").decode() not in page
     assert page.count("@font-face") == 2  # the latin face, and the one with no subset named
     assert "<link" not in page
 
 
 def test_figures_and_tables_are_numbered_down_the_poster_includes_too(tmp_path, drawn):
-    (tmp_path / "part.md").write_text("[[CAPTION:Table]] Pins\n\n| Pin | Use |\n|---|---|\n| 1 | Power |\n", encoding="utf-8")
+    (tmp_path / "part.md").write_text(
+        "[[CAPTION:Table]] Pins\n\n| Pin | Use |\n|---|---|\n| 1 | Power |\n", encoding="utf-8"
+    )
     text = "## A\n\n[[CAPTION:Figure]] One\n\n[[CAPTION:Table]] First\n\n## B\n\n[[INCLUDE: part.md]]\n\n[[CAPTION:figure]] Two\n"
     page, _ = build(write(tmp_path, text), lambda: object())
     captions = re.findall(r'<p class="caption"><strong>(\w+ \d+):</strong> (\w+)</p>', page)
@@ -1318,7 +1459,9 @@ def test_figures_and_tables_are_numbered_down_the_poster_includes_too(tmp_path,
 
 
 def test_a_flow_section_may_go_on_in_the_next_column(tmp_path, drawn, caplog):
-    page, _ = build(write(tmp_path, "## A {.flow}\n\nOne.\n\n## B {.wide .flow}\n\nTwo.\n\n## C\n\nThree.\n"), lambda: object())
+    page, _ = build(
+        write(tmp_path, "## A {.flow}\n\nOne.\n\n## B {.wide .flow}\n\nTwo.\n\n## C\n\nThree.\n"), lambda: object()
+    )
     assert '<section class="breakable s-bar"><h2>A</h2>' in page and '<section class="wide s-bar"><h2>B</h2>' in page
     assert "is wide, so .flow and cols= are ignored" in caplog.text
     assert 'section.continued h2::after{content:" (continued)"' in page and "classList.add('continued')" in page
@@ -1380,10 +1523,14 @@ def test_one_font_file_for_several_weights_is_embedded_once():
     from py_doc.poster_fonts import merge_weights
 
     rule = "/* latin */\n@font-face {{\n  font-family: 'Mono';\n  font-weight: {w};\n  src: url(https://f.example/mono.woff2) format('woff2');\n}}\n"
-    css = merge_weights(rule.format(w=500) + rule.format(w=600) + rule.format(w=700).replace("mono.woff2", "mono-bold.woff2"))
+    css = merge_weights(
+        rule.format(w=500) + rule.format(w=600) + rule.format(w=700).replace("mono.woff2", "mono-bold.woff2")
+    )
     assert css.count("@font-face") == 2 and css.count("mono.woff2") == 1
     assert "font-weight:500 600;" in css and "font-weight:700;" in css
-    assert merge_weights("@font-face { font-weight: bold; src: url(https://f.example/a.woff2); }").count("bold") == 1  # left alone
+    assert (
+        merge_weights("@font-face { font-weight: bold; src: url(https://f.example/a.woff2); }").count("bold") == 1
+    )  # left alone
 
 
 # --- py-doc poster --watch ------------------------------------------------------------------------
diff --git a/tests/test_poster_barcode.py b/tests/test_poster_barcode.py
index e362ad3..4b14efa 100644
--- a/tests/test_poster_barcode.py
+++ b/tests/test_poster_barcode.py
@@ -48,7 +48,14 @@ def test_mistakes_say_what_is_wrong(self, kind, data, message):
             checked(kind, data)
 
     def test_types_and_their_other_names(self):
-        assert [kind_of(k) for k in (None, "EAN-13", "upc", "itf", "39", "128")] == ["code128", "ean13", "upca", "itf14", "code39", "code128"]
+        assert [kind_of(k) for k in (None, "EAN-13", "upc", "itf", "39", "128")] == [
+            "code128",
+            "ean13",
+            "upca",
+            "itf14",
+            "code39",
+            "code128",
+        ]
         with pytest.raises(BarcodeError, match="type must be one of code128, code39"):
             kind_of("pdf417")
 
@@ -59,7 +66,10 @@ def test_the_text_under_the_bars(self):
         assert human_text("ean13", "5012345678900") == "5 012345 678900"
         assert human_text("upca", "036000291452") == "0 36000 29145 2"
         assert human_text("itf14", "15400141288763") == "1 54 00141 28876 3"
-        assert human_text("code39", "SN-100", check=True).startswith("*SN-100") and human_text("code39", "SN-100") == "*SN-100*"
+        assert (
+            human_text("code39", "SN-100", check=True).startswith("*SN-100")
+            and human_text("code39", "SN-100") == "*SN-100*"
+        )
 
 
 class TestDrawing:
@@ -70,7 +80,11 @@ def test_guard_bars_are_longer_on_ean_and_upc(self):
         heights = {float(h) for h in __import__("re").findall(r'<rect [^>]*height="([\d.]+)"', svg)}
         assert len(heights) == 2 and min(heights) == 80  # bars and the longer guards
         assert 'fill="#123456"' in svg and 'width="300"' in svg
-        assert [t for t in __import__("re").findall(r">(\d+)</text>", svg)] == ["5", "012345", "678900"]  # placed as on products
+        assert [t for t in __import__("re").findall(r">(\d+)</text>", svg)] == [
+            "5",
+            "012345",
+            "678900",
+        ]  # placed as on products
 
     def test_itf14_has_bearer_bars_and_text_can_be_left_out(self):
         svg = barcode_svg("itf14", "15400141288763", "#000", text=False)
@@ -116,7 +130,14 @@ def test_block_mistakes_name_the_poster(self, tmp_path, body, message):
 
 @pytest.mark.parametrize(
     "kind, data",
-    [("code128", "SN-100 A7/b"), ("code39", "SN-100"), ("ean13", "501234567890"), ("ean8", "9638507"), ("upca", "03600029145"), ("itf14", "1540014128876")],
+    [
+        ("code128", "SN-100 A7/b"),
+        ("code39", "SN-100"),
+        ("ean13", "501234567890"),
+        ("ean8", "9638507"),
+        ("upca", "03600029145"),
+        ("itf14", "1540014128876"),
+    ],
 )
 def test_a_reader_gets_back_what_was_encoded(kind, data):
     from PIL import Image
diff --git a/tests/test_poster_browser.py b/tests/test_poster_browser.py
index a2bfef8..74b236f 100644
--- a/tests/test_poster_browser.py
+++ b/tests/test_poster_browser.py
@@ -95,16 +95,23 @@ def test_a_flow_section_goes_on_in_the_next_columns_with_its_blocks_in_order(bro
     assert blocks == [f"P{n}. The node"[:12] for n in range(1, 13)] + ["Table 1: Pin", "Pin Use 1 Po"]
     heights = [col["height"] for col in columns]
     assert max(heights) < 0.5 * sum(heights), "the long section is shared out"
-    assert page.evaluate("() => getComputedStyle(document.querySelector('section.continued h2'), '::after').content") == '" (continued)"'
+    assert (
+        page.evaluate("() => getComputedStyle(document.querySelector('section.continued h2'), '::after').content")
+        == '" (continued)"'
+    )
 
 
 def test_a_caption_is_never_parted_from_its_table(browser, tmp_path):
-    body = section("Long", 7, "{.flow}").replace("P4.", "[[CAPTION:Table]] Pins\n\n| Pin |\n|---|\n| 1 |\n\nP4.") + section("B", 1)
+    body = section("Long", 7, "{.flow}").replace(
+        "P4.", "[[CAPTION:Table]] Pins\n\n| Pin |\n|---|\n| 1 |\n\nP4."
+    ) + section("B", 1)
     page = open_poster(browser, tmp_path, body)
     for col in layout(page):
         for name, _, blocks in col["sections"]:
             if "Table 1: Pin" in blocks:
-                assert blocks[blocks.index("Table 1: Pin") + 1] == "Pin 1", "the table follows its caption in one column"
+                assert blocks[blocks.index("Table 1: Pin") + 1] == "Pin 1", (
+                    "the table follows its caption in one column"
+                )
 
 
 def test_balancing_again_gives_the_same_layout(browser, tmp_path):
@@ -120,4 +127,6 @@ def test_the_poster_fits_its_paper_and_scales_to_the_window(browser, tmp_path):
         "() => { const p = document.querySelector('.poster'); return [+p.dataset.w, p.scrollHeight, +p.style.height.slice(0, -2) / +p.dataset.w]; }"
     )
     assert height <= width * ratio + 1 and abs(ratio - 1.4141) < 0.001, "one A3 page, no taller"
-    assert page.evaluate("() => +getComputedStyle(document.querySelector('.poster')).zoom") == pytest.approx(1400 / width, rel=0.01)
+    assert page.evaluate("() => +getComputedStyle(document.querySelector('.poster')).zoom") == pytest.approx(
+        1400 / width, rel=0.01
+    )
diff --git a/tests/test_poster_qr.py b/tests/test_poster_qr.py
index 75c029d..6c66a55 100644
--- a/tests/test_poster_qr.py
+++ b/tests/test_poster_qr.py
@@ -24,9 +24,12 @@ def test_text_and_urls_are_as_written(self):
         assert payload("text", "Two\nlines") == "Two\nlines"
 
     def test_a_contact_card(self):
-        card = payload("vcard", "name: Jane van der Berg\norg: Example; Instruments\ntel: +44 1234 567890\ntel: +44 1234 567891\n"
-                                "mobile: +44 7700 900123\nemail: jane@example.com\nurl: https://example.com\n"
-                                "address: 1 High Street, Leeds, LS1 1AA, UK\nnote: Ask for Jane, or the desk")
+        card = payload(
+            "vcard",
+            "name: Jane van der Berg\norg: Example; Instruments\ntel: +44 1234 567890\ntel: +44 1234 567891\n"
+            "mobile: +44 7700 900123\nemail: jane@example.com\nurl: https://example.com\n"
+            "address: 1 High Street, Leeds, LS1 1AA, UK\nnote: Ask for Jane, or the desk",
+        )
         assert card.split("\r\n") == [
             "BEGIN:VCARD", "VERSION:3.0", "N:Berg;Jane van der;;;", "FN:Jane van der Berg", "ORG:Example\\; Instruments",
             "TEL;TYPE=WORK,VOICE:+44 1234 567890", "TEL;TYPE=WORK,VOICE:+44 1234 567891", "TEL;TYPE=CELL:+44 7700 900123",
@@ -35,13 +38,20 @@ def test_a_contact_card(self):
         ]  # fmt: skip
 
     def test_an_event_with_times_and_an_all_day_one(self):
-        event = payload("event", "title: Commissioning, day 1\nstart: 2026-11-03 09:00\nend: 2026-11-03 17:30\nlocation: Site B")
+        event = payload(
+            "event", "title: Commissioning, day 1\nstart: 2026-11-03 09:00\nend: 2026-11-03 17:30\nlocation: Site B"
+        )
         lines = event.split("\r\n")
-        assert lines[:3] == ["BEGIN:VCALENDAR", "VERSION:2.0", "PRODID:-//py-doc//poster//EN"] and lines[-2:] == ["END:VEVENT", "END:VCALENDAR"]
+        assert lines[:3] == ["BEGIN:VCALENDAR", "VERSION:2.0", "PRODID:-//py-doc//poster//EN"] and lines[-2:] == [
+            "END:VEVENT",
+            "END:VCALENDAR",
+        ]
         assert "DTSTART:20261103T090000" in lines and "DTEND:20261103T173000" in lines
         assert "SUMMARY:Commissioning\\, day 1" in lines and "LOCATION:Site B" in lines
         all_day = payload("event", "title: Open day\nstart: 2026-11-03\nend: 2026-11-04").split("\r\n")
-        assert "DTSTART;VALUE=DATE:20261103" in all_day and "DTEND;VALUE=DATE:20261105" in all_day  # the day after the last
+        assert (
+            "DTSTART;VALUE=DATE:20261103" in all_day and "DTEND;VALUE=DATE:20261105" in all_day
+        )  # the day after the last
         one_hour = payload("event", "title: Call\nstart: 2026-11-03 09:00Z").split("\r\n")
         assert "DTSTART:20261103T090000Z" in one_hour and "DTEND:20261103T100000Z" in one_hour
 
@@ -50,7 +60,7 @@ def test_the_same_event_is_the_same_code(self):
         assert payload("event", text) == payload("event", text)
 
     def test_wifi_email_phone_sms_and_geo(self):
-        assert payload("wifi", "ssid: Site;Guest\npassword: p:a\"ss") == 'WIFI:T:WPA;S:Site\\;Guest;P:p\\:a\\"ss;;'
+        assert payload("wifi", 'ssid: Site;Guest\npassword: p:a"ss') == 'WIFI:T:WPA;S:Site\\;Guest;P:p\\:a\\"ss;;'
         assert payload("wifi", "ssid: Open\nhidden: yes") == "WIFI:T:nopass;S:Open;H:true;;"
         assert payload("email", "to: help@example.com\nsubject: Unit 7 & 8\nbody: Hello there") == (
             "mailto:help@example.com?subject=Unit%207%20%26%208&body=Hello%20there"
@@ -72,7 +82,11 @@ def test_text_already_in_the_standard_form_is_kept(self):
             ("event", "title: T", "needs a 'start:' line"),
             ("event", "title: T\nstart: 3 November", "start must be YYYY-MM-DD"),
             ("event", "title: T\nstart: 2026-11-03 10:00\nend: 2026-11-03 09:00", "end is before start"),
-            ("event", "title: T\nstart: 2026-11-03\nend: 2026-11-03 09:00", "must both be dates, or both dates and times"),
+            (
+                "event",
+                "title: T\nstart: 2026-11-03\nend: 2026-11-03 09:00",
+                "must both be dates, or both dates and times",
+            ),
             ("wifi", "ssid: S\nsecurity: WPA", "needs a 'password:' line"),
             ("wifi", "ssid: S\nsecurity: magic\npassword: x", "security must be WPA, WEP or none"),
             ("phone", "number: call me", "is not a phone number"),
@@ -86,7 +100,15 @@ def test_mistakes_say_what_is_wrong(self, kind, text, message):
             payload(kind, text)
 
     def test_types_and_their_other_names(self):
-        assert [kind_of(k) for k in (None, "contact", "vcf", "ical", "calendar", "tel", "mailto")] == ["url", "vcard", "vcard", "event", "event", "phone", "email"]
+        assert [kind_of(k) for k in (None, "contact", "vcf", "ical", "calendar", "tel", "mailto")] == [
+            "url",
+            "vcard",
+            "vcard",
+            "event",
+            "event",
+            "phone",
+            "email",
+        ]
         with pytest.raises(QrError, match="type must be one of url, text, vcard"):
             kind_of("barcode")
 
diff --git a/tests/test_pptx_import.py b/tests/test_pptx_import.py
index 0fc2253..7f8ee9d 100644
--- a/tests/test_pptx_import.py
+++ b/tests/test_pptx_import.py
@@ -93,7 +93,9 @@ def test_a_deck_becomes_markdown_with_front_matter_headings_and_lists(deck, tmp_
     result = import_pptx(deck, tmp_path / "out")
     text = result.markdown.read_text(encoding="utf-8")
     assert result.markdown.name == "sensor_review.md"
-    assert text.startswith("---\ntitle: Sensor review\nsubtitle: What we found\nauthor: A. Writer\nversion: '2.0'\n---\n")
+    assert text.startswith(
+        "---\ntitle: Sensor review\nsubtitle: What we found\nauthor: A. Writer\nversion: '2.0'\n---\n"
+    )
     assert "# Findings\n" in text and "## Readings\n" in text
     assert "- Temperature\n  - Within 0.5 C\n- Humidity" in text
     assert "::: notes\nSay why the drift matters.\n:::" in text
diff --git a/tests/test_pptx_pandoc.py b/tests/test_pptx_pandoc.py
index 1e1b180..86b1b0d 100644
--- a/tests/test_pptx_pandoc.py
+++ b/tests/test_pptx_pandoc.py
@@ -49,7 +49,8 @@ def build(options="", sample=SAMPLE, template=None):
         (tmp_path / "d.md").write_text(sample, encoding="utf-8")
         tpl = f"template: {template}, " if template else ""
         (tmp_path / "py-doc.yml").write_text(
-            f"documents:\n  deck:\n    sources: [d.md]\n    outputs:\n      pptx: {{{tpl}{options}}}\n", encoding="utf-8"
+            f"documents:\n  deck:\n    sources: [d.md]\n    outputs:\n      pptx: {{{tpl}{options}}}\n",
+            encoding="utf-8",
         )
         config = load_config(tmp_path / "py-doc.yml")
         (out,) = build_document(config, config.documents["deck"], ["pptx"], runtime=runtime)
@@ -60,7 +61,11 @@ def build(options="", sample=SAMPLE, template=None):
 
 def reference(tmp_path: Path) -> Path:
     path = tmp_path / "ref.pptx"
-    path.write_bytes(subprocess.run(["pandoc", "--print-default-data-file", "reference.pptx"], capture_output=True, check=True).stdout)
+    path.write_bytes(
+        subprocess.run(
+            ["pandoc", "--print-default-data-file", "reference.pptx"], capture_output=True, check=True
+        ).stdout
+    )
     return path
 
 
diff --git a/tests/test_report.py b/tests/test_report.py
index 75abe70..c8079ac 100644
--- a/tests/test_report.py
+++ b/tests/test_report.py
@@ -107,7 +107,9 @@ def test_diagrams_are_listed_with_cache_hits(tmp_path, run):
     run(text, "--report", "one.json", "--timestamps")
     run(text, "--report", "two.json", "--timestamps")
     first, second = (load(tmp_path / n)["diagrams"][0] for n in ("one.json", "two.json"))
-    assert (first["type"], first["file"], first["line"], first["status"]) == ("graphviz", "a.md", 3, "ok") or first["type"] == "dot"
+    assert (first["type"], first["file"], first["line"], first["status"]) == ("graphviz", "a.md", 3, "ok") or first[
+        "type"
+    ] == "dot"
     assert (first["cached"], second["cached"]) == (False, True)
     assert "seconds" in first
     assert "dot" in load(tmp_path / "two.json")["tools"]
diff --git a/tests/test_runtime.py b/tests/test_runtime.py
index 5a5b38d..4e48971 100644
--- a/tests/test_runtime.py
+++ b/tests/test_runtime.py
@@ -237,6 +237,8 @@ def test_the_runner_refuses_to_start_on_an_unsupported_platform(monkeypatch):
 
 def test_docker_missing_inside_wsl_says_how_to_install_it():
     runtime = Runtime(IMAGE, platform_name="windows")
-    result = ToolResult(1, "", "<3>WSL (823 - Relay) ERROR: CreateProcessCommon:875: execvpe(docker) failed: No such file or directory")
+    result = ToolResult(
+        1, "", "<3>WSL (823 - Relay) ERROR: CreateProcessCommon:875: execvpe(docker) failed: No such file or directory"
+    )
     with pytest.raises(EnvironmentProblem, match="not installed inside the WSL distro"):
         runtime._raise_environment(result, running=True)
diff --git a/tests/test_setup.py b/tests/test_setup.py
index 657ad7f..e32a1f3 100644
--- a/tests/test_setup.py
+++ b/tests/test_setup.py
@@ -36,13 +36,22 @@ def scripts(self) -> list[str]:
 @pytest.fixture
 def windows(tmp_path, monkeypatch):
     engine = install(tmp_path, monkeypatch)
-    runtime = Runtime("tools:test", docker=["definitely-not-docker-xyz"], wsl_exe=engine.wsl, wsl_distro="Ubuntu", platform_name="windows")
+    runtime = Runtime(
+        "tools:test",
+        docker=["definitely-not-docker-xyz"],
+        wsl_exe=engine.wsl,
+        wsl_distro="Ubuntu",
+        platform_name="windows",
+    )
     return engine, runtime
 
 
 def settle(monkeypatch, runtime):
     monkeypatch.setattr("py_doc.tools_cli.make_runtime", lambda settings: runtime)
-    monkeypatch.setattr("py_doc.tools_cli.settings_from_config", lambda path: __import__("py_doc.runtime", fromlist=["RuntimeSettings"]).RuntimeSettings())
+    monkeypatch.setattr(
+        "py_doc.tools_cli.settings_from_config",
+        lambda path: __import__("py_doc.runtime", fromlist=["RuntimeSettings"]).RuntimeSettings(),
+    )
 
 
 def test_the_script_adds_the_user_and_turns_on_systemd_only_in_wsl():
@@ -87,7 +96,10 @@ def test_a_windows_setup_runs_as_root_in_the_distro_then_restarts_it(windows, mo
     engine, runtime = windows
     settle(monkeypatch, runtime)
     recorder = Recorder()
-    assert run_setup(["--yes"], run=recorder) in (0, 2)  # the fake docker stays missing, so the check at the end may fail
+    assert run_setup(["--yes"], run=recorder) in (
+        0,
+        2,
+    )  # the fake docker stays missing, so the check at the end may fail
     commands = [call[0] for call in recorder.calls]
     root = next(c for c in commands if "--user" in c and c[-2:] == ["bash", "-s"])
     assert root[root.index("-d") + 1] == "Ubuntu" and root[root.index("--user") + 1] == "root"
diff --git a/tests/test_site.py b/tests/test_site.py
index d64d8e2..265b907 100644
--- a/tests/test_site.py
+++ b/tests/test_site.py
@@ -47,7 +47,9 @@ def test_a_scaffold_never_replaces_a_file(tmp_path):
 
 
 def test_an_existing_mkdocs_yml_with_python_tags_is_read(tmp_path):
-    (tmp_path / "mkdocs.yml").write_text("docs_dir: pages\nmarkdown_extensions:\n  - x: !!python/name:foo.bar\n", encoding="utf-8")
+    (tmp_path / "mkdocs.yml").write_text(
+        "docs_dir: pages\nmarkdown_extensions:\n  - x: !!python/name:foo.bar\n", encoding="utf-8"
+    )
     engine = engine_for("mkdocs", tmp_path)
     assert engine.content == tmp_path / "pages"
     assert "INHERIT" in engine.check()[0]
@@ -56,10 +58,14 @@ def test_an_existing_mkdocs_yml_with_python_tags_is_read(tmp_path):
 def test_the_mkdocs_navigation_has_a_section_per_document(tmp_path):
     engine = engine_for("mkdocs", tmp_path)
     engine.scaffold("x")
-    nav = engine.write_nav([
-        NavSection("Guide", "guide", [NavPage("Overview", "guide/overview.md"), NavPage("Design", "guide/design.md")]),
-        NavSection("Notes", "notes", [NavPage("Release notes", "notes/notes.md")]),
-    ])
+    nav = engine.write_nav(
+        [
+            NavSection(
+                "Guide", "guide", [NavPage("Overview", "guide/overview.md"), NavPage("Design", "guide/design.md")]
+            ),
+            NavSection("Notes", "notes", [NavPage("Release notes", "notes/notes.md")]),
+        ]
+    )
     data = yaml.safe_load(nav.read_text(encoding="utf-8"))
     assert data["nav"] == [
         {"Home": "index.md"},
@@ -71,16 +77,26 @@ def test_the_mkdocs_navigation_has_a_section_per_document(tmp_path):
 def test_hand_written_pages_follow_the_documents_in_the_navigation(tmp_path):
     engine = engine_for("mkdocs", tmp_path)
     engine.scaffold("x")
-    nav = engine.write_nav([NavSection("Guide", "guide", [NavPage("Overview", "guide/overview.md")])], {"Blog": "blog/index.md"})
-    assert yaml.safe_load(nav.read_text(encoding="utf-8"))["nav"][-2:] == [{"Overview": "guide/overview.md"}, {"Blog": "blog/index.md"}]
+    nav = engine.write_nav(
+        [NavSection("Guide", "guide", [NavPage("Overview", "guide/overview.md")])], {"Blog": "blog/index.md"}
+    )
+    assert yaml.safe_load(nav.read_text(encoding="utf-8"))["nav"][-2:] == [
+        {"Overview": "guide/overview.md"},
+        {"Blog": "blog/index.md"},
+    ]
     sidebar = engine_for("starlight", tmp_path / "astro").write_nav([], {"Blog": "blog/index.md", "About": "about.md"})
-    assert json.loads(sidebar.read_text(encoding="utf-8")) == [{"label": "Blog", "link": "/blog/"}, {"label": "About", "link": "/about/"}]
+    assert json.loads(sidebar.read_text(encoding="utf-8")) == [
+        {"label": "Blog", "link": "/blog/"},
+        {"label": "About", "link": "/about/"},
+    ]
 
 
 def test_a_target_config_inherits_the_navigation_through_mkdocs_yml(tmp_path):
     engine = engine_for("mkdocs", tmp_path)
     engine.scaffold("x")
-    (tmp_path / "mkdocs.tarf.yml").write_text("INHERIT: mkdocs.yml\nsite_url: https://tarf.example/\nsite_dir: build-tarf\n", encoding="utf-8")
+    (tmp_path / "mkdocs.tarf.yml").write_text(
+        "INHERIT: mkdocs.yml\nsite_url: https://tarf.example/\nsite_dir: build-tarf\n", encoding="utf-8"
+    )
     assert engine.check("mkdocs.tarf.yml") == []
     assert engine.site_dir("mkdocs.tarf.yml") == tmp_path / "build-tarf" and engine.site_dir() == tmp_path / "build"
     (tmp_path / "mkdocs.alone.yml").write_text("site_name: alone\n", encoding="utf-8")
@@ -97,9 +113,13 @@ def test_a_new_starlight_site_passes_the_sidebar_to_starlight(tmp_path):
     assert engine.exists() and engine.check() == []
     package = json.loads((tmp_path / "package.json").read_text(encoding="utf-8"))
     assert "@astrojs/starlight" in package["dependencies"] and package["scripts"]["build"] == "astro build"
-    assert "import sidebar from './src/py-doc-sidebar.json'" in (tmp_path / "astro.config.mjs").read_text(encoding="utf-8")
+    assert "import sidebar from './src/py-doc-sidebar.json'" in (tmp_path / "astro.config.mjs").read_text(
+        encoding="utf-8"
+    )
     engine.write_nav([NavSection("Guide", "guide", [])])
-    assert json.loads((tmp_path / STARLIGHT_SIDEBAR).read_text(encoding="utf-8")) == [{"label": "Guide", "items": [{"autogenerate": {"directory": "guide"}}]}]
+    assert json.loads((tmp_path / STARLIGHT_SIDEBAR).read_text(encoding="utf-8")) == [
+        {"label": "Guide", "items": [{"autogenerate": {"directory": "guide"}}]}
+    ]
 
 
 def test_a_starlight_site_without_the_sidebar_is_told_how(tmp_path):
@@ -153,7 +173,10 @@ def project(tmp_path):
         "Energy $E = mc^2$ and\n\n$$t = C/I$$\n\n> [!NOTE]\n> Read this first.\n\n![The board](images/board.png)\n\n[[CAPTION:Table]] Pins\n\n| Pin | Use |\n|---|---|\n| 1 | Power |\n",
         encoding="utf-8",
     )
-    (docs / "02_design.md").write_text("# Design\n\n## Flow\n\nBack to the [overview](01_overview.md).\n\n::: {.pagebreak}\n:::\n\nDone.\n", encoding="utf-8")
+    (docs / "02_design.md").write_text(
+        "# Design\n\n## Flow\n\nBack to the [overview](01_overview.md).\n\n::: {.pagebreak}\n:::\n\nDone.\n",
+        encoding="utf-8",
+    )
     (tmp_path / "py-doc.yml").write_text(
         "project: {name: Sensor}\ndocuments:\n  guide:\n    sources: [docs/01_overview.md, {file: docs/02_design.md, heading_offset: 1, page_break: true}]\n"
         "    variables: {version: '1.0'}\nsite: {engine: ENGINE}\n",
@@ -189,14 +212,23 @@ def test_mkdocs_pages_have_admonitions_links_pictures_and_captions(project, pand
     nav = yaml.safe_load((project / "site" / MKDOCS_NAV).read_text(encoding="utf-8"))["nav"]
     assert nav[-1] == {"Sensor guide": [{"Overview": "guide/01-overview.md"}, {"Design": "guide/02-design.md"}]}
     assert set(json.loads((project / "site" / MANIFEST).read_text(encoding="utf-8"))["files"]) == {
-        "docs/guide/01-overview.md", "docs/guide/02-design.md", f"docs/guide/media/{picture.name}", "docs/guide/.gitignore",
+        "docs/guide/01-overview.md",
+        "docs/guide/02-design.md",
+        f"docs/guide/media/{picture.name}",
+        "docs/guide/.gitignore",
     }
 
 
 @needs_sh
 def test_the_first_page_links_the_built_downloads(project, pandoc_runtime, caplog):
-    text = (project / "py-doc.yml").read_text(encoding="utf-8").replace("site: {engine: ENGINE}", "site: {engine: ENGINE, downloads: [pdf, docx]}")
-    text = text.replace("    variables: {version: '1.0'}\n", "    variables: {version: '1.0'}\n    outputs: {docx: {}, pdf: {}}\n")
+    text = (
+        (project / "py-doc.yml")
+        .read_text(encoding="utf-8")
+        .replace("site: {engine: ENGINE}", "site: {engine: ENGINE, downloads: [pdf, docx]}")
+    )
+    text = text.replace(
+        "    variables: {version: '1.0'}\n", "    variables: {version: '1.0'}\n    outputs: {docx: {}, pdf: {}}\n"
+    )
     (project / "py-doc.yml").write_text(text, encoding="utf-8")
     (project / "build").mkdir()
     (project / "build" / "guide.pdf").write_bytes(b"%PDF-1.7 test")
@@ -208,7 +240,10 @@ def test_the_first_page_links_the_built_downloads(project, pandoc_runtime, caplo
     assert (docs / "downloads" / "guide.pdf").read_bytes() == b"%PDF-1.7 test"
     assert "Download" not in (docs / "02-design.md").read_text(encoding="utf-8"), "only the first page links them"
     assert "guide.docx is not there" in caplog.text and "py-doc build guide" in caplog.text
-    assert "docs/guide/downloads/guide.pdf" in json.loads((project / "site" / MANIFEST).read_text(encoding="utf-8"))["files"]
+    assert (
+        "docs/guide/downloads/guide.pdf"
+        in json.loads((project / "site" / MANIFEST).read_text(encoding="utf-8"))["files"]
+    )
 
 
 @needs_sh
@@ -216,7 +251,9 @@ def test_starlight_pages_have_asides_an_order_and_no_repeated_title(project, pan
     config, runtime = _site(project, "starlight", pandoc_runtime)
     generate_site(config, runtime)
     overview = (project / "site" / "src" / "content" / "docs" / "guide" / "01-overview.md").read_text(encoding="utf-8")
-    assert overview.startswith("---\ntitle: Overview\nsidebar:\n  order: 1\n---\n\nVersion 1.0. See [the design](/guide/02-design/#flow).")
+    assert overview.startswith(
+        "---\ntitle: Overview\nsidebar:\n  order: 1\n---\n\nVersion 1.0. See [the design](/guide/02-design/#flow)."
+    )
     assert ":::note\nRead this first.\n:::" in overview
 
 
@@ -235,19 +272,26 @@ def test_a_page_py_doc_did_not_write_is_left_alone(project, pandoc_runtime):
 def test_a_page_whose_source_is_gone_is_removed(project, pandoc_runtime):
     config, runtime = _site(project, "mkdocs", pandoc_runtime)
     generate_site(config, runtime)
-    text = (project / "py-doc.yml").read_text(encoding="utf-8").replace(", {file: docs/02_design.md, heading_offset: 1, page_break: true}", "")
+    text = (
+        (project / "py-doc.yml")
+        .read_text(encoding="utf-8")
+        .replace(", {file: docs/02_design.md, heading_offset: 1, page_break: true}", "")
+    )
     (project / "py-doc.yml").write_text(text, encoding="utf-8")
     generate_site(load_config(project / "py-doc.yml"), runtime)
     assert not (project / "site" / "docs" / "guide" / "02-design.md").exists()
     assert (project / "site" / "docs" / "index.md").is_file(), "a page py-doc did not write stays"
 
 
-
 def _with_posters(project, engine_name):
     (project / "posters").mkdir()
     (project / "posters" / "launch.md").write_text("---\ntitle: Launch & go\n---\n## A\n\nText.\n", encoding="utf-8")
     (project / "posters" / "plain.md").write_text("## B\n\nText.\n", encoding="utf-8")
-    text = (project / "py-doc.yml").read_text(encoding="utf-8").replace("site: {engine: ENGINE}", "site: {engine: ENGINE, posters: [launch, plain]}")
+    text = (
+        (project / "py-doc.yml")
+        .read_text(encoding="utf-8")
+        .replace("site: {engine: ENGINE}", "site: {engine: ENGINE, posters: [launch, plain]}")
+    )
     text += "posters:\n  launch: {source: posters/launch.md}\n  plain: {source: posters/plain.md}\n  other: {source: posters/plain.md}\n"
     (project / "py-doc.yml").write_text(text.replace("ENGINE", engine_name), encoding="utf-8")
     (project / "build").mkdir()
@@ -283,7 +327,10 @@ def test_starlight_serves_the_posters_from_public(project, pandoc_runtime):
     generate_site(config, runtime)
     assert (project / "site" / "public" / "posters" / "plain.html").is_file()
     index = (project / "site" / "src" / "content" / "docs" / "posters" / "index.md").read_text(encoding="utf-8")
-    assert index == "---\ntitle: Posters\n---\n\n- [Launch & go](/posters/launch.html) · [PDF](/posters/launch.pdf)\n- [plain](/posters/plain.html)\n"
+    assert (
+        index
+        == "---\ntitle: Posters\n---\n\n- [Launch & go](/posters/launch.html) · [PDF](/posters/launch.pdf)\n- [plain](/posters/plain.html)\n"
+    )
     sidebar = json.loads((project / "site" / STARLIGHT_SIDEBAR).read_text(encoding="utf-8"))
     assert sidebar[-1] == {"label": "Posters", "link": "/posters/"}
 
@@ -294,7 +341,8 @@ def test_site_posters_must_be_posters_of_py_doc_yml(tmp_path):
         load_config(tmp_path / "py-doc.yml")
     (tmp_path / "p.md").write_text("## A\n", encoding="utf-8")
     (tmp_path / "py-doc.yml").write_text(
-        "documents: {posters: {sources: [p.md]}}\nposters: {a: {source: p.md}}\nsite: {engine: mkdocs, posters: [a]}\n", encoding="utf-8"
+        "documents: {posters: {sources: [p.md]}}\nposters: {a: {source: p.md}}\nsite: {engine: mkdocs, posters: [a]}\n",
+        encoding="utf-8",
     )
     with pytest.raises(ConfigError, match="a document of the site has that name"):
         load_config(tmp_path / "py-doc.yml")
@@ -328,33 +376,64 @@ def _page(slug_: str, title: str) -> Page:
 
 
 def test_the_navigation_nests_by_folder_with_the_index_page_first():
-    items = nav_items([_page("index", "Primers"), _page("cloud/kafka", "Kafka"), _page("cloud/index", "Cloud and messaging"),
-                       _page("iot-and-embedded/mqtt", "MQTT"), _page("cloud/deep/x", "X")])
+    items = nav_items(
+        [
+            _page("index", "Primers"),
+            _page("cloud/kafka", "Kafka"),
+            _page("cloud/index", "Cloud and messaging"),
+            _page("iot-and-embedded/mqtt", "MQTT"),
+            _page("cloud/deep/x", "X"),
+        ]
+    )
     assert items[0] == NavPage("Primers", "primers/index.md")
     cloud, iot = items[1:]
     assert cloud.title == "Cloud and messaging" and cloud.folder == "primers/cloud"
-    assert cloud.pages[:2] == [NavPage("Cloud and messaging", "primers/cloud/index.md"), NavPage("Kafka", "primers/cloud/kafka.md")]
+    assert cloud.pages[:2] == [
+        NavPage("Cloud and messaging", "primers/cloud/index.md"),
+        NavPage("Kafka", "primers/cloud/kafka.md"),
+    ]
     assert cloud.pages[2] == NavSection("Deep", "primers/cloud/deep", [NavPage("X", "primers/cloud/deep/x.md")])
     assert iot.title == "Iot and embedded", "a folder without an index page is named after the folder"
 
 
 def test_nested_navigation_for_mkdocs_and_starlight(tmp_path):
-    section = NavSection("Primers", "primers", nav_items([_page("index", "Primers"), _page("cloud/index", "Cloud"), _page("cloud/kafka", "Kafka")]))
+    section = NavSection(
+        "Primers",
+        "primers",
+        nav_items([_page("index", "Primers"), _page("cloud/index", "Cloud"), _page("cloud/kafka", "Kafka")]),
+    )
     engine = engine_for("mkdocs", tmp_path)
     nav = yaml.safe_load(engine.write_nav([section]).read_text(encoding="utf-8"))["nav"]
-    assert nav == [{"Primers": [{"Primers": "primers/index.md"}, {"Cloud": [{"Cloud": "primers/cloud/index.md"}, {"Kafka": "primers/cloud/kafka.md"}]}]}]
+    assert nav == [
+        {
+            "Primers": [
+                {"Primers": "primers/index.md"},
+                {"Cloud": [{"Cloud": "primers/cloud/index.md"}, {"Kafka": "primers/cloud/kafka.md"}]},
+            ]
+        }
+    ]
     sidebar = json.loads(engine_for("starlight", tmp_path / "astro").write_nav([section]).read_text(encoding="utf-8"))
-    assert sidebar == [{"label": "Primers", "items": [
-        {"slug": "primers"}, {"label": "Cloud", "items": [{"slug": "primers/cloud"}, {"slug": "primers/cloud/kafka"}]},
-    ]}]
+    assert sidebar == [
+        {
+            "label": "Primers",
+            "items": [
+                {"slug": "primers"},
+                {"label": "Cloud", "items": [{"slug": "primers/cloud"}, {"slug": "primers/cloud/kafka"}]},
+            ],
+        }
+    ]
 
 
 def test_a_site_path_must_stay_below_the_document_folder(tmp_path):
     for bad in ("../x", "/x", "a//b", "."):
-        (tmp_path / "py-doc.yml").write_text(f"documents:\n  a: {{sources: [{{file: a.md, site_path: '{bad}'}}]}}\n", encoding="utf-8")
+        (tmp_path / "py-doc.yml").write_text(
+            f"documents:\n  a: {{sources: [{{file: a.md, site_path: '{bad}'}}]}}\n", encoding="utf-8"
+        )
         with pytest.raises(ConfigError, match="site_path"):
             load_config(tmp_path / "py-doc.yml")
-    (tmp_path / "py-doc.yml").write_text("documents:\n  a: {sources: [{file: a.md, site_path: cloud/Kafka.md}]}\n", encoding="utf-8")
+    (tmp_path / "py-doc.yml").write_text(
+        "documents:\n  a: {sources: [{file: a.md, site_path: cloud/Kafka.md}]}\n", encoding="utf-8"
+    )
     assert load_config(tmp_path / "py-doc.yml").documents["a"].sources[0].site_path == "cloud/Kafka"
 
 
@@ -370,25 +449,36 @@ def test_pages_keep_their_folders_and_the_nav_nests(nested, pandoc_runtime):
     assert f"](media/{picture.name})" in kafka, "a picture goes beside its page"
     assert "[Kafka](../cloud/kafka.md)" in (docs / "architecture" / "c4.md").read_text(encoding="utf-8")
     nav = yaml.safe_load((nested / "site" / MKDOCS_NAV).read_text(encoding="utf-8"))["nav"]
-    assert nav[-1] == {"Primers": [
-        {"Primers": "primers/index.md"},
-        {"Cloud and messaging": [{"Cloud and messaging": "primers/cloud/index.md"}, {"Kafka": "primers/cloud/kafka.md"}]},
-        {"Architecture": [{"C4": "primers/architecture/c4.md"}]},
-    ]}
+    assert nav[-1] == {
+        "Primers": [
+            {"Primers": "primers/index.md"},
+            {
+                "Cloud and messaging": [
+                    {"Cloud and messaging": "primers/cloud/index.md"},
+                    {"Kafka": "primers/cloud/kafka.md"},
+                ]
+            },
+            {"Architecture": [{"C4": "primers/architecture/c4.md"}]},
+        ]
+    }
 
 
 @needs_sh
 def test_starlight_links_reach_pages_in_folders(nested, pandoc_runtime):
     config, runtime = _site(nested, "starlight", pandoc_runtime)
     generate_site(config, runtime)
-    kafka = (nested / "site" / "src" / "content" / "docs" / "primers" / "cloud" / "kafka.md").read_text(encoding="utf-8")
+    kafka = (nested / "site" / "src" / "content" / "docs" / "primers" / "cloud" / "kafka.md").read_text(
+        encoding="utf-8"
+    )
     assert "[C4](/primers/architecture/c4/)" in kafka and "[the primers](/primers/)" in kafka
 
 
 @needs_sh
 def test_a_site_path_moves_a_page_and_a_clash_is_reported(nested, pandoc_runtime):
     text = (nested / "py-doc.yml").read_text(encoding="utf-8")
-    moved = text.replace("- content/primers/architecture/c4.md", "- {file: content/primers/architecture/c4.md, site_path: cloud/c4}")
+    moved = text.replace(
+        "- content/primers/architecture/c4.md", "- {file: content/primers/architecture/c4.md, site_path: cloud/c4}"
+    )
     (nested / "py-doc.yml").write_text(moved, encoding="utf-8")
     config, runtime = _site(nested, "mkdocs", pandoc_runtime)
     generate_site(config, runtime)
@@ -402,7 +492,9 @@ def test_a_site_path_moves_a_page_and_a_clash_is_reported(nested, pandoc_runtime
 
 
 def test_a_site_must_be_made_first(project):
-    (project / "py-doc.yml").write_text((project / "py-doc.yml").read_text(encoding="utf-8").replace("ENGINE", "mkdocs"), encoding="utf-8")
+    (project / "py-doc.yml").write_text(
+        (project / "py-doc.yml").read_text(encoding="utf-8").replace("ENGINE", "mkdocs"), encoding="utf-8"
+    )
     with pytest.raises(ConversionError, match="py-doc site init"):
         generate_site(load_config(project / "py-doc.yml"), lambda: None)
 
@@ -411,7 +503,9 @@ def test_a_site_must_be_made_first(project):
 
 
 def test_site_init_makes_the_site_named_in_py_doc_yml(project, monkeypatch, capsys):
-    (project / "py-doc.yml").write_text((project / "py-doc.yml").read_text(encoding="utf-8").replace("ENGINE", "starlight"), encoding="utf-8")
+    (project / "py-doc.yml").write_text(
+        (project / "py-doc.yml").read_text(encoding="utf-8").replace("ENGINE", "starlight"), encoding="utf-8"
+    )
     monkeypatch.chdir(project)
     assert main(["site", "init"]) == 0
     assert (project / "site" / "astro.config.mjs").is_file() and "Next: py-doc site build" in capsys.readouterr().out
@@ -423,7 +517,12 @@ def test_site_init_makes_the_site_named_in_py_doc_yml(project, monkeypatch, caps
 def test_site_build_checks_the_targets_before_building(project, monkeypatch, capsys):
     text = (project / "py-doc.yml").read_text(encoding="utf-8")
     monkeypatch.chdir(project)
-    (project / "py-doc.yml").write_text(text.replace("site: {engine: ENGINE}", "site: {engine: mkdocs, targets: {github: mkdocs.yml, tarf: mkdocs.tarf.yml}}"), encoding="utf-8")
+    (project / "py-doc.yml").write_text(
+        text.replace(
+            "site: {engine: ENGINE}", "site: {engine: mkdocs, targets: {github: mkdocs.yml, tarf: mkdocs.tarf.yml}}"
+        ),
+        encoding="utf-8",
+    )
     engine_for("mkdocs", project / "site").scaffold("x")
     (project / "site" / "mkdocs.tarf.yml").write_text("INHERIT: mkdocs.yml\n", encoding="utf-8")
     assert main(["site", "build", "--target", "other"]) == 1
diff --git a/tests/test_slides_cli.py b/tests/test_slides_cli.py
index 60797e5..10781ef 100644
--- a/tests/test_slides_cli.py
+++ b/tests/test_slides_cli.py
@@ -53,7 +53,11 @@ def test_split_level_out_of_range_is_a_usage_error(deck_md, monkeypatch):
 @pytest.mark.parametrize("flag", ["-t", "--template", "-r", "--reference"])
 def test_template_and_its_old_names(flag, deck_md, tmp_path, monkeypatch):
     template = tmp_path / "t.pptx"
-    template.write_bytes(subprocess.run(["pandoc", "--print-default-data-file", "reference.pptx"], capture_output=True, check=True).stdout)
+    template.write_bytes(
+        subprocess.run(
+            ["pandoc", "--print-default-data-file", "reference.pptx"], capture_output=True, check=True
+        ).stdout
+    )
     prs = Presentation(str(template))
     prs.slide_width = Inches(8)
     prs.save(str(template))
diff --git a/tests/test_structure.py b/tests/test_structure.py
index 7592ced..95d42e7 100644
--- a/tests/test_structure.py
+++ b/tests/test_structure.py
@@ -37,7 +37,13 @@ def test_code_and_inline_code_are_not_searched(self):
         assert found("```\n[[X]]\n```\n\nuse `[[X]]` here\n\n[[X]]\n", rule) == [(7, "r/hr", "warning")]
 
     def test_scope_prefix_and_exclude(self):
-        rule = {"id": "r/q", "type": "regex-line", "pattern": r"\*\*Note\*\*", "scope_prefix": ">", "exclude_pattern": "ok"}
+        rule = {
+            "id": "r/q",
+            "type": "regex-line",
+            "pattern": r"\*\*Note\*\*",
+            "scope_prefix": ">",
+            "exclude_pattern": "ok",
+        }
         assert found("> **Note** x\n**Note** y\n> **Note** ok\n", rule) == [(1, "r/q", "warning")]
 
     def test_disabled_rules_do_nothing(self):
@@ -51,7 +57,13 @@ def test_loose_list(self):
 
     def test_broken_link_path_include_and_anchor_skipping(self, tmp_path):
         (tmp_path / "there.md").write_text("x", encoding="utf-8")
-        rule = {"id": "r/link", "type": "path-exists", "severity": "error", "pattern": r"\[[^\]]*\]\(([^)\s]+)\)", "message": "{target}"}
+        rule = {
+            "id": "r/link",
+            "type": "path-exists",
+            "severity": "error",
+            "pattern": r"\[[^\]]*\]\(([^)\s]+)\)",
+            "message": "{target}",
+        }
         text = "[a](there.md) [b](gone.md#x) [c](https://x.org/a) [d](#top) [e](the%20re.md)\n"
         issues = check_file(tmp_path / "a.md", text, rules(rule))
         assert [i.message for i in issues] == ["gone.md", "the re.md"]
@@ -61,9 +73,18 @@ def test_balanced_markers(self):
             "id": "r/if", "type": "balanced-markers", "severity": "error", "open_pattern": r"\[\[IF:[^\]]*\]\]",
             "close_pattern": r"\[\[ENDIF\]\]", "unmatched_open_message": "open {marker}", "unmatched_close_message": "close",
         }  # fmt: skip
-        assert found("[[IF: a]]\n[[ENDIF]]\n[[ENDIF]]\n[[IF: b]]\n", rule) == [(3, "r/if", "error"), (4, "r/if", "error")]
-
-    CAPTION = {"id": "r/cap", "type": "requires-caption", "block": "table", "required_pattern": r"\[\[CAPTION:Table\]\]", "message": "caption"}
+        assert found("[[IF: a]]\n[[ENDIF]]\n[[ENDIF]]\n[[IF: b]]\n", rule) == [
+            (3, "r/if", "error"),
+            (4, "r/if", "error"),
+        ]
+
+    CAPTION = {
+        "id": "r/cap",
+        "type": "requires-caption",
+        "block": "table",
+        "required_pattern": r"\[\[CAPTION:Table\]\]",
+        "message": "caption",
+    }
 
     def test_table_needs_a_caption_on_the_next_line(self):
         table = "| a |\n|---|\n| 1 |\n"
@@ -106,11 +127,25 @@ def test_pandoc_identifiers(self):
 
     @pytest.mark.skipif(shutil.which("pandoc") is None, reason="pandoc is not installed")
     @pytest.mark.parametrize(
-        "heading", ["Daily Volume Profile (R6029)", "11000/0 - Daily", "`Code` and *emphasis*", "[Link](x.md) text", "123", "Über uns", "a.b_c-d", "Q&A: what?"]
+        "heading",
+        [
+            "Daily Volume Profile (R6029)",
+            "11000/0 - Daily",
+            "`Code` and *emphasis*",
+            "[Link](x.md) text",
+            "123",
+            "Über uns",
+            "a.b_c-d",
+            "Q&A: what?",
+        ],
     )
     def test_agrees_with_pandoc(self, heading):
         html = subprocess.run(
-            ["pandoc", "-f", "markdown", "-t", "html"], input=f"# {heading}\n", capture_output=True, encoding="utf-8", check=True
+            ["pandoc", "-f", "markdown", "-t", "html"],
+            input=f"# {heading}\n",
+            capture_output=True,
+            encoding="utf-8",
+            check=True,
         ).stdout
         assert f'id="{anchor(heading)}"' in html
 
@@ -153,7 +188,10 @@ class TestConfiguration:
             ({"id": "a", "type": "regex-line", "pattern": "x", "severity": "loud"}, "severity must be one of"),
             ({"id": "a", "type": "path-exists", "pattern": "x"}, "needs a group"),
             ({"id": "a", "type": "requires-caption", "block": "box", "required_pattern": "x"}, "block must be one of"),
-            ({"id": "a", "type": "requires-caption", "block": "line", "required_pattern": "x"}, "needs 'trigger_pattern'"),
+            (
+                {"id": "a", "type": "requires-caption", "block": "line", "required_pattern": "x"},
+                "needs 'trigger_pattern'",
+            ),
         ],
     )
     def test_mistakes_name_the_rule(self, entry, message):
@@ -182,15 +220,21 @@ def test_rules_inline_in_py_doc_yml(self, tmp_path):
         assert [(i.rule, i.severity) for i in report.issues] == [("s/hr", "error")]
 
     def test_rules_from_a_file_and_errors_are_config_errors(self, tmp_path):
-        (tmp_path / "rules.yaml").write_text(yaml.safe_dump({"rules": [{"id": "x", "type": "regex-line", "pattern": "a"}]}), encoding="utf-8")
-        assert [r.id for r in load_config(self.write(tmp_path, "lint: {structure: rules.yaml}\n")).lint.structure] == ["x"]
+        (tmp_path / "rules.yaml").write_text(
+            yaml.safe_dump({"rules": [{"id": "x", "type": "regex-line", "pattern": "a"}]}), encoding="utf-8"
+        )
+        assert [r.id for r in load_config(self.write(tmp_path, "lint: {structure: rules.yaml}\n")).lint.structure] == [
+            "x"
+        ]
         with pytest.raises(ConfigError, match="not found"):
             load_config(self.write(tmp_path, "lint: {structure: gone.yaml}\n"))
         with pytest.raises(ConfigError, match="has type 'bad'"):
             load_config(self.write(tmp_path, "lint:\n  structure: [{id: x, type: bad}]\n"))
 
     def test_documents_are_taken_from_the_configuration(self, tmp_path):
-        config = load_config(self.write(tmp_path, "documents:\n  d: {sources: [a.md, {file: b.md, include: false}]}\n")).lint
+        config = load_config(
+            self.write(tmp_path, "documents:\n  d: {sources: [a.md, {file: b.md, include: false}]}\n")
+        ).lint
         assert config.documents == {"d": [tmp_path / "a.md"]}
 
 
@@ -228,7 +272,9 @@ def test_sample_project_findings(self, tmp_path):
             "[[IF: x]]\ntext\n\n![pic](img.png)\n\n| a |\n|---|\n| 1 |\n\n[l](#intro) [m](#nope)\n",
             encoding="utf-8",
         )
-        config = load_config_text(tmp_path, "lint: {structure: %s}\ndocuments:\n  d: {sources: [a.md]}\n" % EXAMPLE.as_posix())
+        config = load_config_text(
+            tmp_path, "lint: {structure: %s}\ndocuments:\n  d: {sources: [a.md]}\n" % EXAMPLE.as_posix()
+        )
         report = DocLinter(config=config).lint_path(a)
         got = sorted({(i.line, i.rule) for i in report.issues if i.rule.startswith("structure/")})
         assert got == [
diff --git a/tests/test_template_check.py b/tests/test_template_check.py
index bf7480c..1843daf 100644
--- a/tests/test_template_check.py
+++ b/tests/test_template_check.py
@@ -76,7 +76,9 @@ def change(d):
 
 
 def test_bold_body_text_fails(good_docx):
-    assert "Bold leak" in checks(check_template(edit(good_docx, lambda d: setattr(d.styles["Normal"].font, "bold", True))), "FAIL")
+    assert "Bold leak" in checks(
+        check_template(edit(good_docx, lambda d: setattr(d.styles["Normal"].font, "bold", True))), "FAIL"
+    )
 
 
 def test_a_normal_style_based_on_a_heading_fails(good_docx):
@@ -116,7 +118,11 @@ def test_powerpoint_needs_pandoc_s_layouts(tmp_path):
 @pytest.mark.skipif(shutil.which("pandoc") is None, reason="pandoc is not installed")
 def test_pandoc_s_own_reference_deck_passes(tmp_path):
     pptx = tmp_path / "ref.pptx"
-    pptx.write_bytes(subprocess.run(["pandoc", "--print-default-data-file", "reference.pptx"], capture_output=True, check=True).stdout)
+    pptx.write_bytes(
+        subprocess.run(
+            ["pandoc", "--print-default-data-file", "reference.pptx"], capture_output=True, check=True
+        ).stdout
+    )
     assert not check_template(pptx).failures
 
 
diff --git a/tests/test_vale.py b/tests/test_vale.py
index 8b66a07..908599b 100644
--- a/tests/test_vale.py
+++ b/tests/test_vale.py
@@ -93,9 +93,17 @@ def test_duplicates_of_the_builtin_rules_are_dropped():
 
 def test_alerts_are_mapped(tmp_path):
     f = tmp_path / "a.md"
-    text = json.dumps({str(f): [alert(check="Style.Rule", severity="suggestion", action={"Name": "replace", "Params": ["to"]})]})
+    text = json.dumps(
+        {str(f): [alert(check="Style.Rule", severity="suggestion", action={"Name": "replace", "Params": ["to"]})]}
+    )
     (issue,) = parse_output(text, [f])
-    assert (issue.rule, issue.category, issue.severity, issue.suggestion, issue.column) == ("Style.Rule", "Style", "info", "to", 3)
+    assert (issue.rule, issue.category, issue.severity, issue.suggestion, issue.column) == (
+        "Style.Rule",
+        "Style",
+        "info",
+        "to",
+        3,
+    )
     with pytest.raises(Exception, match="not JSON"):
         parse_output("oops", [f])
 
@@ -103,8 +111,14 @@ def test_alerts_are_mapped(tmp_path):
 def test_generated_files_follow_the_definition(tmp_path):
     settings = parse_vale(
         {
-            "packages": ["write-good"], "spelling": "en-GB", "min_alert_level": "warning",
-            "rules": {"PyDoc.SentenceLength": {"level": "error", "max": 20}, "PyDoc.PassiveVoice": "off", "write-good.Weasel": "error"},
+            "packages": ["write-good"],
+            "spelling": "en-GB",
+            "min_alert_level": "warning",
+            "rules": {
+                "PyDoc.SentenceLength": {"level": "error", "max": 20},
+                "PyDoc.PassiveVoice": "off",
+                "write-good.Weasel": "error",
+            },
             "terms": {"Kubernetes": ["k8s"]},
             "avoid": [{"pattern": r"\bsimply\b", "message": "No.", "level": "error"}],
         },
@@ -116,7 +130,9 @@ def test_generated_files_follow_the_definition(tmp_path):
     assert "PyDoc.PassiveVoice = NO" in ini and "write-good.Weasel = error" in ini
     sentence = yaml.safe_load((tmp_path / "vale/styles/PyDoc/SentenceLength.yml").read_text())
     assert sentence["max"] == 20
-    assert sentence["message"] == "Sentence is %d words long. Try to keep it under 20."  # Vale gives the count as a number
+    assert (
+        sentence["message"] == "Sentence is %d words long. Try to keep it under 20."
+    )  # Vale gives the count as a number
     assert yaml.safe_load((tmp_path / "vale/styles/PyDoc/Terms.yml").read_text())["swap"]["k8s"] == "Kubernetes"
     assert yaml.safe_load((tmp_path / "vale/styles/PyDoc/Terms.yml").read_text())["swap"]["lwm2m"] == "LwM2M"
     assert yaml.safe_load((tmp_path / "vale/styles/PyDoc/Avoid1.yml").read_text())["level"] == "error"
@@ -159,7 +175,9 @@ def test_a_broken_definition_fails_with_status_2_before_vale_runs(project, tmp_p
 
 
 def test_rules_files_merge_in_order_and_inline_wins(project, tmp_path):
-    (project / "base.yml").write_text("rules:\n  PyDoc.PassiveVoice: error\n  PyDoc.WeaselWords: error\n", encoding="utf-8")
+    (project / "base.yml").write_text(
+        "rules:\n  PyDoc.PassiveVoice: error\n  PyDoc.WeaselWords: error\n", encoding="utf-8"
+    )
     (project / "team.yml").write_text("rules:\n  PyDoc.WeaselWords: off\n", encoding="utf-8")
     settings = parse_vale({"rules_file": ["base.yml", "team.yml"], "rules": {"PyDoc.PassiveVoice": "warning"}}, project)
     assert settings.rules["PyDoc.PassiveVoice"].level == "warning"
@@ -205,7 +223,9 @@ def test_the_schema_accepts_a_full_definition():
 
 @pytest.mark.skipif(shutil.which("vale") is None, reason="Vale is not installed")
 def test_end_to_end_with_the_real_vale(project, capsys):
-    (project / "docs" / "a.md").write_text("# A\n\nThis is very good. TODO: finish.\n\n```\nvery TODO\n```\n", encoding="utf-8")
+    (project / "docs" / "a.md").write_text(
+        "# A\n\nThis is very good. TODO: finish.\n\n```\nvery TODO\n```\n", encoding="utf-8"
+    )
     assert lint(project, "--engine", "vale") == 0
     out = capsys.readouterr().out
     assert "PyDoc.WeaselWords" in out and "PyDoc.Placeholders" in out
@@ -219,7 +239,9 @@ def test_the_placeholder_words_are_not_in_the_accepted_vocabulary(project, tmp_p
     folder = tmp_path / "vale"
     config = LintConfig()
     build_workspace(config.vale, config, folder)
-    accepted = (folder / "styles" / "config" / "vocabularies" / "PyDoc" / "accept.txt").read_text(encoding="utf-8").split()
+    accepted = (
+        (folder / "styles" / "config" / "vocabularies" / "PyDoc" / "accept.txt").read_text(encoding="utf-8").split()
+    )
     assert "API" in accepted and not {"TODO", "FIXME", "TBD"} & set(accepted)
 
 
diff --git a/tests/test_word_control.py b/tests/test_word_control.py
index da10da4..f4cff26 100644
--- a/tests/test_word_control.py
+++ b/tests/test_word_control.py
@@ -39,7 +39,9 @@ def test_a_pattern_needing_a_version_without_one_is_an_error(self):
         with pytest.raises(ConversionError, match=r"uses \{version\}, but the document has no version"):
             expand_name("{name}-{version}", "guide", None)
 
-    @pytest.mark.parametrize(("pattern", "message"), [("{nmae}", "unknown field {nmae}"), ("a{b", "stray|brace"), ("a}", "brace")])
+    @pytest.mark.parametrize(
+        ("pattern", "message"), [("{nmae}", "unknown field {nmae}"), ("a{b", "stray|brace"), ("a}", "brace")]
+    )
     def test_bad_patterns(self, pattern, message):
         with pytest.raises(ValueError, match=message):
             check_name_pattern(pattern, "x")
@@ -62,7 +64,11 @@ def test_status_template_rule(self, tmp_path, caplog):
 @needs_git
 class TestGitVersion:
     def git(self, folder, *args):
-        subprocess.run(["git", "-C", str(folder), "-c", "user.name=t", "-c", "user.email=t@t", *args], check=True, capture_output=True)
+        subprocess.run(
+            ["git", "-C", str(folder), "-c", "user.name=t", "-c", "user.email=t@t", *args],
+            check=True,
+            capture_output=True,
+        )
 
     def test_describes_the_repository(self, tmp_path):
         self.git(tmp_path, "init", "-q")
@@ -139,9 +145,7 @@ def make_template(path: Path, body_text: str = "Cover") -> Path:
 
 def build(tmp_path, host, front: str, outputs: str = "template: tpl.docx", extra_files=None):
     (tmp_path / "g.md").write_text(f"---\n{front}\n---\n# Body\n\nText.\n", encoding="utf-8")
-    config = write_config(
-        tmp_path, f"documents:\n  g:\n    sources: [g.md]\n    outputs:\n      docx: {{{outputs}}}\n"
-    )
+    config = write_config(tmp_path, f"documents:\n  g:\n    sources: [g.md]\n    outputs:\n      docx: {{{outputs}}}\n")
     return build_document(config, config.documents["g"], runtime=host)
 
 
@@ -220,10 +224,14 @@ def test_version_git_uses_the_repository(self, tmp_path, host):
         subprocess.run(["git", "-C", str(tmp_path), "init", "-q"], check=True)
         (tmp_path / "x").write_text("x")
         subprocess.run(["git", "-C", str(tmp_path), "add", "x"], check=True)
-        subprocess.run(["git", "-C", str(tmp_path), "-c", "user.name=t", "-c", "user.email=t@t", "commit", "-qm", "c"], check=True)
+        subprocess.run(
+            ["git", "-C", str(tmp_path), "-c", "user.name=t", "-c", "user.email=t@t", "commit", "-qm", "c"], check=True
+        )
         subprocess.run(["git", "-C", str(tmp_path), "tag", "v7"], check=True)
         make_template(tmp_path / "tpl.docx")
-        (out,) = build(tmp_path, host, FRONT.replace("'1.2'", "git"), "template: tpl.docx, name: '{name}-{version_safe}'")
+        (out,) = build(
+            tmp_path, host, FRONT.replace("'1.2'", "git"), "template: tpl.docx, name: '{name}-{version_safe}'"
+        )
         assert out.name == "g-v7.docx" and "v v7 on" in all_text(Document(str(out)))
 
     def test_core_properties_are_written_in_the_right_namespaces(self, tmp_path, host):
diff --git a/tests/test_word_layout.py b/tests/test_word_layout.py
index f3f757c..f6c9213 100644
--- a/tests/test_word_layout.py
+++ b/tests/test_word_layout.py
@@ -79,7 +79,8 @@ def build(outputs="docx: {toc: true}", meta="toc_depth: 2\n", sample=SAMPLE):
         (tmp_path / "g.md").write_text(sample, encoding="utf-8")
         png(tmp_path / "pic.png")
         (tmp_path / "py-doc.yml").write_text(
-            f"documents:\n  g:\n    title: Guide\n{meta and '    ' + meta}    sources: [g.md]\n    outputs:\n      {outputs}\n", encoding="utf-8"
+            f"documents:\n  g:\n    title: Guide\n{meta and '    ' + meta}    sources: [g.md]\n    outputs:\n      {outputs}\n",
+            encoding="utf-8",
         )
         config = load_config(tmp_path / "py-doc.yml")
         (out,) = build_document(config, config.documents["g"], runtime=runtime)
@@ -129,7 +130,13 @@ def test_each_callout_kind_is_a_box_in_its_own_style(built):
     document = Document(str(out))
     styles = xml(out, "word/styles.xml")
     used = {p.style.name: p.text for p in document.paragraphs if p.style.name.startswith("Div.")}
-    for kind, fill in (("note", "E7F1F8"), ("tip", "E8F5E9"), ("important", "F1ECF9"), ("warning", "FFF4E0"), ("caution", "FCE8E8")):
+    for kind, fill in (
+        ("note", "E7F1F8"),
+        ("tip", "E8F5E9"),
+        ("important", "F1ECF9"),
+        ("warning", "FFF4E0"),
+        ("caution", "FCE8E8"),
+    ):
         assert f"Div.{kind}" in used or any(s.startswith(f"Div.{kind}") for s in used), kind
         assert fill in styles, f"{kind} box has no background"
     assert re.search(r'<w:left [^>]*w:val="single"', styles)
@@ -158,7 +165,9 @@ def test_landscape_section_between_the_markers(built):
     orientations = re.findall(r'<w:pgSz[^>]*w:orient="(\w+)"', body)
     assert "landscape" in orientations
     sizes = [(s.page_width, s.page_height) for s in Document(str(out)).sections if s.page_width and s.page_height]
-    assert any(w > h for w, h in sizes) and sizes[-1][1] > sizes[-1][0]  # landscape in the middle, portrait again at the end
+    assert (
+        any(w > h for w, h in sizes) and sizes[-1][1] > sizes[-1][0]
+    )  # landscape in the middle, portrait again at the end
 
 
 def test_code_uses_the_highlight_theme(built):

From fb0345f95d0b007b59092b85b6b2ba478bace276 Mon Sep 17 00:00:00 2001
From: Mark Bacon <mark@bacon.me.uk>
Date: Wed, 21 Oct 2026 15:26:59 +0100
Subject: [PATCH 5/6] Hide the ruff format commit from git blame

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .git-blame-ignore-revs | 6 ++++++
 1 file changed, 6 insertions(+)
 create mode 100644 .git-blame-ignore-revs

diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs
new file mode 100644
index 0000000..25ee0e3
--- /dev/null
+++ b/.git-blame-ignore-revs
@@ -0,0 +1,6 @@
+# Commits that only reformat code, hidden from git blame:
+#   git config blame.ignoreRevsFile .git-blame-ignore-revs
+# (GitHub applies this file on its own.)
+
+# ruff format of the whole Python code base
+3397cd98c04a00b9f646108301d03a0e00c8255d

From 91fe42d3b5b5f6ae1b91bca54347ea1736052853 Mon Sep 17 00:00:00 2001
From: Mark Bacon <mark@bacon.me.uk>
Date: Wed, 21 Oct 2026 16:35:36 +0100
Subject: [PATCH 6/6] Shorten the long sentences CI's Vale reports in the new
 docs

Vale 3.24 in CI counts FR-161, FR-162 and the AD-08 context over 30 words;
the near-limit sentences of the live preview docs are split as well.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/architecture/02_pipeline.md   | 2 +-
 docs/architecture/05_decisions.md  | 6 +++---
 docs/guide/02_projects.md          | 2 +-
 docs/requirements/01_functional.md | 4 ++--
 4 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/architecture/02_pipeline.md b/docs/architecture/02_pipeline.md
index d99d6b2..37d7c11 100644
--- a/docs/architecture/02_pipeline.md
+++ b/docs/architecture/02_pipeline.md
@@ -71,7 +71,7 @@ flowchart LR
 
 ## Live previews
 
-`--watch` on `py-doc poster`, `py-doc docx` and `py-doc slides` runs one loop (`watch.py`). It builds, then serves the pages on 127.0.0.1 from a thread of its own. Every half second it looks at the modification times of the source files: the Markdown, includes, pictures, diagram sources and templates below the folders of the sources. The pages it wrote and hidden folders are not watched. A change builds again. Each page is served with a small script that asks `/__status` whether a newer build is there and reloads when it is, so the files written are the same as without `--watch`. A build that fails keeps the last good page and shows its error over it.
+`--watch` on `py-doc poster`, `py-doc docx` and `py-doc slides` runs one loop (`watch.py`). It builds, then serves the pages on 127.0.0.1 from a thread of its own. Every half second it looks at the modification times of the source files: the Markdown, includes, pictures, diagram sources and templates below the folders of the sources. The pages it wrote and hidden folders are not watched. A change builds again. Each page is served with a small script that asks `/__status` whether a newer build is there, and reloads when it is. The script is added as the page is served, so the files are the same as without `--watch`. A build that fails keeps the last good page and shows its error over it.
 
 A poster is already a web page. A Word document or deck is not, so `docx` and `slides` (`_cli.py`) also write an *HTML twin* of each file (`convert.py`, `convert_twin`). The twin is the same Markdown through the same pipeline to pandoc's HTML. It adds `preview.css` after `html.css` to show page breaks, speaker notes and columns. The twin of a deck also runs `slides-preview.lua`, which puts each slide in a box. A box starts where pandoc's PowerPoint writer starts a slide: at headings up to the split level and at page breaks. The twins go to `.py-doc/preview/` below the input's folder and are served by their path. No file of the user's is overwritten, and two `readme.md` in different folders stay apart. When Word or PowerPoint has the output open, the engine raises `OutputLocked`; the watch loop warns and still writes the twin.
 
diff --git a/docs/architecture/05_decisions.md b/docs/architecture/05_decisions.md
index 7f3a7f5..c82ca36 100644
--- a/docs/architecture/05_decisions.md
+++ b/docs/architecture/05_decisions.md
@@ -50,7 +50,7 @@ Each decision records the context, the choice and its consequences.
 
 ## AD-08 Previews are served, not written beside the outputs
 
-- **Context**: authors want to see a document while they write it, but Word and PowerPoint have no live view, a document open in Word cannot be written, and the in-editor Markdown preview cannot draw most diagrams.
-- **Decision**: `--watch` builds an HTML twin of each document with the same pipeline, keeps it in `.py-doc/preview`, and serves it with a reload script added as it is served. The VS Code extension runs that command; its own instant preview is an approximation for typing.
-- **Consequences**: the preview shows every diagram exactly as the build draws it, and a document open in Word does not stop it. It is one HTML page: slides are boxes and page breaks are lines, but Word's page layout is not shown, and a first build waits for the tool container.
+- **Context**: authors want to see a document while they write it. Word and PowerPoint have no live view, and a document open in Word cannot be written. The in-editor Markdown preview cannot draw most diagrams.
+- **Decision**: `--watch` builds an HTML twin of each document with the same pipeline, and keeps it in `.py-doc/preview`. It serves the twin with a reload script, added as the page is served. The VS Code extension runs that command; its own instant preview is an approximation for typing.
+- **Consequences**: the preview shows every diagram exactly as the build draws it, and a document open in Word does not stop it. It is one HTML page: slides are boxes and page breaks are lines, but Word's page layout is not shown. A first build waits for the tool container.
 
diff --git a/docs/guide/02_projects.md b/docs/guide/02_projects.md
index 72691d1..5c13aba 100644
--- a/docs/guide/02_projects.md
+++ b/docs/guide/02_projects.md
@@ -171,7 +171,7 @@ A file that uses `[[IF:]]` needs its conditions defined, and only `py-doc build`
 
 ### Live preview
 
-`--watch` builds the files, then builds them again whenever a source below their folder changes: the Markdown, an included file, a picture, a diagram source or the template. Next to each `.docx` or `.pptx` it writes an HTML twin of the same Markdown, to `.py-doc/preview/` below the input's folder, and serves the twins on this computer only. The page in the browser reloads after each build, and a build that fails shows its error over the last good page.
+`--watch` builds the files, then builds them again whenever a source below their folder changes. A source is the Markdown, an included file, a picture, a diagram source or the template. For each `.docx` or `.pptx` it also writes an HTML twin of the same Markdown, to `.py-doc/preview/` below the input's folder. It serves the twins on this computer only. The page in the browser reloads after each build, and a build that fails shows its error over the last good page.
 
 - A document open in Word or PowerPoint cannot be written, so it is left as it is, with a warning, and its preview is still updated.
 - The twin shows page breaks as dashed lines, speaker notes in boxes and columns side by side. The twin of a deck shows each slide as a numbered 16:9 box, split as PowerPoint splits it.
diff --git a/docs/requirements/01_functional.md b/docs/requirements/01_functional.md
index acac62f..bece1f3 100644
--- a/docs/requirements/01_functional.md
+++ b/docs/requirements/01_functional.md
@@ -125,8 +125,8 @@ title: Functional requirements
 | FR-158 | `py-doc lint` and `py-doc build --lint` shall lint the posters of `py-doc.yml` with every rule but the document structure, acronym and passive voice rules. | Should | Met |
 | FR-159 | `py-doc poster --watch` shall build the posters again on every save of their sources and reload them in the browser, and show a failed build's error over the last good page. | Could | Met |
 | FR-160 | A poster's sections shall say in braces what they are and how they are laid out: `{.stats}`, `{.abstract}`, `{.summary}`, `{.references}`, `{.wide}` and `{cols=}`. No heading name shall have a meaning of its own, and every part shall be placed in the order of the file. Each kind shall have a choice of looks (`style=`), and `colour=` shall colour every one. | Should | Met |
-| FR-161 | `py-doc docx --watch` and `py-doc slides --watch` shall build again on every save, serve an HTML preview of each file that reloads itself, and keep updating the preview while the document is open in Word or PowerPoint. The preview shall never overwrite a file of the user's. | Could | Met |
-| FR-162 | The VS Code extension in `editors/vscode` shall preview py-doc Markdown in the editor without any tools, and start the live preview of the open file with the command that suits it. | Could | Met |
+| FR-161 | `py-doc docx --watch` and `py-doc slides --watch` shall build again on every save. They shall serve an HTML preview of each file that reloads itself. The preview shall keep updating while Word or PowerPoint has the file open, and never overwrite a file of the user's. | Could | Met |
+| FR-162 | The VS Code extension in `editors/vscode` shall preview py-doc Markdown in the editor without any tools. It shall start the live preview of the open file with the right command. | Could | Met |
 
 ## Tool container