skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/converters/skills/md-to-html/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: md-to-html
+description: Turn a Markdown draft into one self-contained, print-friendly HTML file that survives being emailed or attached, with headings that have anchor links, tables, code, quotes, an optional table of contents, local images embedded, brand colours and fonts from a brand.json, Mermaid diagrams kept as text or drawn from a pinned CDN, and raw HTML escaped so nothing in the source runs. Use when the user wants Markdown "as a web page", "as an HTML file I can send", "something people can open in a browser and print", or says "convert this to HTML".
+---
+
+# md-to-html
+
+You turn a Markdown file into a single `.html` file that anyone can open in a browser, print
+to PDF, or attach to an email, with nothing else to send alongside it. A stdlib script does the
+conversion. Your job is to pick the options, run it, and tell the user exactly what the file
+depends on (network for diagrams, remote images) and what it left out. Drafts often come from
+`guide-builder`; the brand comes from `brand-kit`.
+
+## How to respond
+
+1. **Ask once for what is missing, with defaults.** Take what the user already gave and offer
+   defaults so they can reply "go":
+
+   > Before I build the HTML, confirm these. Anything you skip uses the default:
+   > 1. **The Markdown file.** *No default.*
+   > 2. **Brand:** a `brand.json` from brand-kit. *Default: a neutral navy theme.*
+   > 3. **Table of contents:** *default on when the document has four or more `##` sections.*
+   > 4. **Mermaid diagrams:** keep as text, or draw them in the browser from a pinned CDN copy of
+   >    Mermaid (the file then needs network when opened). *Default: keep as text.*
+
+2. **Check the Markdown converts cleanly.** The script handles ATX headings (`#`), lists
+   (nested, task lists), GFM pipe tables, fenced and indented code, quotes, links and images.
+   Rewrite before converting:
+   - Setext headings (`Title` over `=====`) into `# Title`.
+   - Reference-style links (`[text][1]`) into inline links `[text](...)`.
+   - Footnotes (`[^1]`) into a "Notes" section with plain text.
+
+   Show the user what you changed.
+
+3. **Diagrams.** For a file going to people offline or behind a strict proxy, render the
+   Mermaid to SVG first with `mermaid-render` and reference the SVGs as images. They get
+   embedded and need no network. Use `--mermaid cdn` only when readers will be online.
+
+4. **Run the script.**
+
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/md_to_html.py" draft.md -o draft.html --brand ./brand/brand.json --toc
+   # Other IDEs (from the skill folder)
+   python3 scripts/md_to_html.py draft.md -o draft.html --brand ./brand/brand.json --toc
+   ```
+
+   Options: `--mermaid cdn` draws diagrams with Mermaid 11.4.1 from jsDelivr (pinned, so the
+   drawing does not change under the reader); `--allow-html` passes raw HTML blocks through,
+   only for a source the user wrote themselves. Use `-` as the input to read stdin.
+
+5. **Read every warning and report it in plain words.** The script prints counts (headings,
+   tables, code blocks, diagrams, images embedded, remote, missing) and a warning for each
+   remote image, missing image, unsafe link dropped, raw HTML escaped, and diagrams left as
+   text. Translate them: "the logo is linked from the web, so it won't show offline", not
+   "1 remote".
+
+6. **Tell the user how to check it:** open the file, print-preview it (tables keep their
+   header row on each page, links print their address), and click two anchor links.
+
+**Non-interactive runs** (subagent, CI, headless): no brand falls back to the neutral theme
+with an `[assumption]` line in the reply; TOC and Mermaid use the defaults above. If there is
+no Markdown input, emit `BLOCKED: need the Markdown file to convert` and write nothing.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md): what Markdown is supported, the brand.json fields read, print rules, and why raw HTML is escaped
+- [`scripts/md_to_html.py`](scripts/md_to_html.py): the converter (stdlib only)
+- [`examples/ops-review.md`](examples/ops-review.md): a status review with a table, code, an image and a Mermaid fence, converted with real output
+
+## Quality bar
+
+- **One file, nothing beside it.** Local images are embedded as data URIs. Any remote image is named to the user, because it breaks offline.
+- **Nothing in the source runs.** Raw HTML is shown as text and `javascript:` links are dropped, unless the user asked for `--allow-html` on their own source.
+- **Every heading has a stable anchor** (`#rollout-plan`) so people can link to a section in chat.
+- **It prints well:** table headers repeat, code wraps instead of being cut off, links print their URL, headings don't sit alone at the bottom of a page.
+- **The brand is the user's,** read from their `brand.json`; the neutral theme only when there is none, and said out loud.
+- **Network dependence is stated.** If `--mermaid cdn` is on, the reply says the diagrams need network when opened.
+
+## When to use this skill
+
+- ✅ A Markdown report, guide or review that people outside the repo will open in a browser
+- ✅ A file to attach to an email or upload to an intranet that has no Markdown renderer
+- ✅ A printable version of a Markdown doc, in the company's colours and fonts
+
+## When NOT to use this skill
+
+- ❌ The reader needs to edit and track changes in Word; use `md-to-docx`
+- ❌ The content is a table someone will sort and filter; use `md-to-xlsx`
+- ❌ A designed one-page flyer or poster; use `marketing-flyer`
+- ❌ Only diagrams, as SVG or PNG files; use `mermaid-render`
+- ❌ Writing the document in the first place; use `guide-builder` or the relevant generator, then convert
+
+## Anti-patterns to avoid
+
+- ❌ **Linking images from the user's disk** (`<img src="/Users/...">`). Always build with the script, which embeds them.
+- ❌ **Turning on `--allow-html` for pasted content** from an email or a web page. That is how a `<script>` ends up in a file the whole team opens.
+- ❌ **Sending a `--mermaid cdn` file to a client** without saying it needs network. Render to SVG with `mermaid-render` instead.
+- ❌ **Hand-editing the CSS in the output** to change colours. Change `brand.json` and rebuild, so the next version matches.
+- ❌ **Reporting "done" while warnings scrolled past.** A missing image is a hole in the document; name it.

skilldrop_cli/data/packs/converters/skills/md-to-html/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Turn this markdown report into an HTML page I can attach to an email",
+    "should_trigger": true
+  },
+  {
+    "query": "Convert README.md to a standalone html file with our brand colours",
+    "should_trigger": true
+  },
+  {
+    "query": "I need a printable web version of design-notes.md with a table of contents",
+    "should_trigger": true
+  },
+  {
+    "query": "md to html please, single file, images inlined",
+    "should_trigger": true
+  },
+  {
+    "query": "Convert this markdown to a Word document legal can track changes in",
+    "should_trigger": false
+  },
+  {
+    "query": "Turn the markdown table of vendors into an Excel sheet",
+    "should_trigger": false
+  },
+  {
+    "query": "Render the Mermaid diagram in arch.mmd to an SVG",
+    "should_trigger": false
+  },
+  {
+    "query": "Make a one-page flyer for the open day in our branding",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/converters/skills/md-to-html/evals/evals.json

@@ -0,0 +1,18 @@
+{
+  "skill_name": "md-to-html",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Convert docs/q3-review.md to an HTML file I can email to the Northwind Health ops committee. Use ./brand/brand.json and add a contents box. It has a results table, a screenshot at img/dashboard.png and one Mermaid flowchart. Some people on the committee read email offline on the train.",
+      "assertions": [
+        "Runs md_to_html.py with --brand ./brand/brand.json and --toc, writing a single .html file",
+        "Does not use --mermaid cdn without saying the file then needs network; because readers are offline, offers to render the flowchart to SVG with mermaid-render or keeps it as text",
+        "Reports the image as embedded, or names it as missing if the script warned it was not found",
+        "Relays every warning the script printed in plain words, not just the counts",
+        "Does not pass --allow-html",
+        "Does not invent content, numbers or sections that are not in docs/q3-review.md",
+        "Tells the user to print-preview the file and check an anchor link"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/converters/skills/md-to-html/evals/files/1/brand/brand.json

@@ -0,0 +1,80 @@
+{
+  "$comment": "brand-kit output. deck-builder and marketing-flyer read this file; any field left out is asked for or defaulted by them. Paths are relative to this file. Every value carries where it came from in `sources`.",
+  "name": "Northwind Health",
+  "tagline": "Care that comes to you",
+  "logo": {
+    "primary": "logo.png",
+    "on_dark": "logo-white.png",
+    "mark": "mark.png",
+    "notes": "Keep clear space equal to the height of the N on every side. Never place the full-colour logo on the green."
+  },
+  "colors": {
+    "primary": "#0E5A46",
+    "secondary": "#3D7F6B",
+    "accent": "#F2A541",
+    "background": "#FFFFFF",
+    "text": "#1F2A28",
+    "extra": [
+      {
+        "name": "Mist",
+        "hex": "#E8F1EE",
+        "use": "panel backgrounds"
+      }
+    ]
+  },
+  "fonts": {
+    "heading": {
+      "family": "Georgia",
+      "fallback": "serif",
+      "weight": 700
+    },
+    "body": {
+      "family": "Arial",
+      "fallback": "sans-serif",
+      "weight": 400
+    }
+  },
+  "voice": {
+    "tone": "Warm, plain, confident. Short sentences.",
+    "use": [
+      "members",
+      "care team",
+      "near you"
+    ],
+    "avoid": [
+      "patients",
+      "cutting-edge",
+      "solutions"
+    ]
+  },
+  "imagery": {
+    "style": "Real people in daylight, community settings, no stock handshakes.",
+    "do": [
+      "natural light",
+      "diverse ages"
+    ],
+    "dont": [
+      "clinical close-ups",
+      "illustrated icons as hero images"
+    ]
+  },
+  "templates": {
+    "pptx": "northwind-master.potx"
+  },
+  "contact": {
+    "website": "northwindhealth.example",
+    "email": "hello@northwindhealth.example",
+    "phone": "",
+    "address": ""
+  },
+  "legal": {
+    "footer": "\u00a9 2026 Northwind Health",
+    "disclaimer": ""
+  },
+  "sources": {
+    "colors": "brand guidelines PDF, page 4 [explicit]",
+    "fonts": "brand guidelines PDF, page 6 [explicit]",
+    "voice": "website About page [inferred]",
+    "logo": "files supplied by the user [explicit]"
+  }
+}

skilldrop_cli/data/packs/converters/skills/md-to-html/evals/files/1/docs/q3-review.md

@@ -0,0 +1,35 @@
+# Northwind Health operations review, Q3
+
+Prepared for the ops committee. Figures cover 1 July to 30 September.
+
+## Summary
+
+Appointment wait time fell and the no-show rate held steady. The call centre missed its answer-time target in August.
+
+## Results
+
+| Measure | Q2 | Q3 | Target |
+|:--------|---:|---:|-------:|
+| Median wait for an appointment (days) | 9 | 6 | 7 |
+| No-show rate | 8.4% | 8.1% | 8.0% |
+| Calls answered within 60 seconds | 82% | 76% | 80% |
+| Member satisfaction (out of 5) | 4.2 | 4.4 | 4.3 |
+
+## Dashboard
+
+![Q3 operations dashboard](../img/dashboard.png)
+
+## How a referral moves
+
+```mermaid
+flowchart LR
+    A[Referral received] --> B{Complete?}
+    B -->|Yes| C[Booked]
+    B -->|No| D[Returned to referrer]
+    D --> A
+```
+
+## Next quarter
+
+- Add two call-centre shifts on Mondays.
+- Pilot text reminders at the Riverside clinic.

skilldrop_cli/data/packs/converters/skills/md-to-html/examples/inputs/chart.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="320" height="120" viewBox="0 0 320 120">
+  <rect width="320" height="120" fill="#ffffff"/>
+  <rect x="20" y="60" width="50" height="40" fill="#0E5A46"/>
+  <rect x="95" y="40" width="50" height="60" fill="#0E5A46"/>
+  <rect x="170" y="30" width="50" height="70" fill="#0E5A46"/>
+  <rect x="245" y="20" width="50" height="80" fill="#F2A541"/>
+  <text x="160" y="115" font-family="Arial" font-size="10" text-anchor="middle">Weekly active members, Q1 to Q4 (illustrative)</text>
+</svg>

skilldrop_cli/data/packs/converters/skills/md-to-html/examples/inputs/ops-review.md

@@ -0,0 +1,48 @@
+# Northwind Health: Q3 platform review
+
+Prepared for the **operations committee**. Figures are *placeholders* for this example.
+
+## Summary
+
+- Uptime held at the target for the quarter
+- Two incidents, both under 30 minutes
+  - INC-101: login latency
+  - INC-102: delayed reminder emails
+- [x] Migrate reminders to the new queue
+- [ ] Retire the old scheduler
+
+> Decision needed: approve the scheduler retirement for October.
+
+## Numbers
+
+| Metric | Q2 | Q3 | Change |
+|:-------|---:|---:|:------:|
+| Uptime | 99.90% | 99.95% | up |
+| Incidents | 4 | 2 | down |
+| `p95` login (ms) | 410 | 380 | down |
+
+![Weekly active members](chart.svg)
+
+## How a reminder is sent
+
+```mermaid
+flowchart LR
+    Sched([Scheduler]) -->|enqueue| Q{{Reminder queue}}
+    Q --> W[Worker]
+    W -->|SMTP| Mail[(Mail relay)]
+```
+
+The worker retries with this rule:
+
+```python
+def backoff(attempt):
+    return min(2 ** attempt, 300)  # seconds, capped at 5 minutes
+```
+
+## Notes
+
+Raw HTML is shown as text, not run: <script>alert("hi")</script>
+
+<div style="color:red">This block came from a pasted email.</div>
+
+See the [runbook](https://northwindhealth.example/runbooks/reminders) for the retry rules.

skilldrop_cli/data/packs/converters/skills/md-to-html/examples/ops-review.md

@@ -0,0 +1,83 @@
+# Example: a quarterly ops review as one HTML file
+
+**What the user said:** *"Turn `ops-review.md` into something the operations committee can
+open from an email and print. Add a contents box."*
+
+The input is [`inputs/ops-review.md`](inputs/ops-review.md). It has nested and task lists, a
+quote, an aligned table, a local SVG chart ([`inputs/chart.svg`](inputs/chart.svg)), a Mermaid
+fence, a Python code block, and two things that should not survive as-is: an inline
+`<script>` and a pasted `<div>` block. (A `javascript:` link would also be dropped, with a
+warning naming it.)
+
+## Command
+
+```bash
+python3 scripts/md_to_html.py examples/inputs/ops-review.md -o ops-review.html --toc
+```
+
+## What the script printed (real output)
+
+```text
+warning: 1 Mermaid diagram(s) kept as text; use --mermaid cdn to draw them (needs network when opened), or render them to SVG with mermaid-render
+warning: raw HTML found and shown as text (2 place(s)); this is deliberate, see --allow-html
+wrote ops-review.html (6 KB): 5 headings, 1 tables, 1 code blocks, 1 Mermaid, 1 images embedded, 0 remote, 0 missing
+```
+
+## The `<main>` of the output (real, base64 shortened)
+
+```html
+<h1 id="northwind-health-q3-platform-review">Northwind Health: Q3 platform review<a class="anchor" href="#northwind-health-q3-platform-review" aria-hidden="true">#</a></h1>
+<nav class="toc" aria-label="Contents"><p>Contents</p><ul><li><a href="#summary">Summary</a></li><li><a href="#numbers">Numbers</a></li><li><a href="#how-a-reminder-is-sent">How a reminder is sent</a></li><li><a href="#notes">Notes</a></li></ul></nav>
+<p>Prepared for the <strong>operations committee</strong>. Figures are <em>placeholders</em> for this example.</p>
+<h2 id="summary">Summary<a class="anchor" href="#summary" aria-hidden="true">#</a></h2>
+<ul>
+<li>Uptime held at the target for the quarter</li>
+<li>Two incidents, both under 30 minutes
+<ul>
+<li>INC-101: login latency</li>
+<li>INC-102: delayed reminder emails</li>
+</ul></li>
+<li class="task"><input type="checkbox" disabled checked> Migrate reminders to the new queue</li>
+<li class="task"><input type="checkbox" disabled> Retire the old scheduler</li>
+</ul>
+<blockquote><p>Decision needed: approve the scheduler retirement for October.</p></blockquote>
+<h2 id="numbers">Numbers<a class="anchor" href="#numbers" aria-hidden="true">#</a></h2>
+<div class="table-wrap"><table><thead><tr><th style="text-align:left">Metric</th><th style="text-align:right">Q2</th><th style="text-align:right">Q3</th><th style="text-align:center">Change</th></tr></thead><tbody><tr><td style="text-align:left">Uptime</td><td style="text-align:right">99.90%</td><td style="text-align:right">99.95%</td><td style="text-align:center">up</td></tr><tr><td style="text-align:left">Incidents</td><td style="text-align:right">4</td><td style="text-align:right">2</td><td style="text-align:center">down</td></tr><tr><td style="text-align:left"><code>p95</code> login (ms)</td><td style="text-align:right">410</td><td style="text-align:right">380</td><td style="text-align:center">down</td></tr></tbody></table></div>
+<p><img src="data:image/svg+xml;base64,…" alt="Weekly active members"></p>
+<h2 id="how-a-reminder-is-sent">How a reminder is sent<a class="anchor" href="#how-a-reminder-is-sent" aria-hidden="true">#</a></h2>
+<pre class="mermaid">flowchart LR
+    Sched([Scheduler]) --&gt;|enqueue| Q{{Reminder queue}}
+    Q --&gt; W[Worker]
+    W --&gt;|SMTP| Mail[(Mail relay)]</pre>
+<p>The worker retries with this rule:</p>
+<pre><code class="language-python">def backoff(attempt):
+    return min(2 ** attempt, 300)  # seconds, capped at 5 minutes</code></pre>
+<h2 id="notes">Notes<a class="anchor" href="#notes" aria-hidden="true">#</a></h2>
+<p>Raw HTML is shown as text, not run: &lt;script&gt;alert(&quot;hi&quot;)&lt;/script&gt;</p>
+<pre class="raw-html">&lt;div style=&quot;color:red&quot;&gt;This block came from a pasted email.&lt;/div&gt;</pre>
+<p>See the <a href="https://northwindhealth.example/runbooks/reminders">runbook</a> for the retry rules.</p>
+```
+
+## With `--mermaid cdn`
+
+The same command with `--mermaid cdn` adds exactly one script and a policy that allows only it
+(real output):
+
+```html
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; img-src data: https:; style-src 'unsafe-inline'; font-src data: https:; script-src 'sha256-FFdGvPoYRnPQ2cUJFzJW6IyZn0u1kdvZbGgLe0Qjl8Y=' https://cdn.jsdelivr.net; connect-src https://cdn.jsdelivr.net">
+<script type="module">import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11.4.1/dist/mermaid.esm.min.mjs";mermaid.initialize({startOnLoad:true,securityLevel:"strict"});</script>
+```
+
+Opened in headless Chrome with network, the `<pre class="mermaid">` was replaced by a drawn
+flowchart SVG.
+
+## What to tell the user
+
+> `ops-review.html` is ready: one 6 KB file with the chart embedded, so it works as an email
+> attachment. Three things to know:
+> - The reminder diagram shows as text. If the committee will be online, I can rebuild with
+>   the diagram drawn (it then needs network when opened), or render it to an SVG and embed it.
+> - The pasted `<div>` and `<script>` show as text on purpose. Delete them from the source if they
+>   were not meant to be there.
+>
+> Print-preview it once: the table header repeats on each page and the runbook link prints its address.

skilldrop_cli/data/packs/converters/skills/md-to-html/manifest.json

@@ -0,0 +1,43 @@
+{
+  "name": "md-to-html",
+  "version": "0.1.0",
+  "description": "Turn a Markdown draft into one self-contained, print-friendly HTML file that survives being emailed or attached, with headings that have anchor links, tables, code, quotes, an optional table of contents, local images embedded, brand colours and fonts from a brand.json, Mermaid diagrams kept as text or drawn from a pinned CDN, and raw HTML escaped so nothing in the source runs. Use when the user wants Markdown \"as a web page\", \"as an HTML file I can send\", \"something people can open in a browser and print\", or says \"convert this to HTML\".",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "brand-kit",
+    "guide-builder",
+    "marketing-flyer",
+    "md-to-docx",
+    "md-to-xlsx",
+    "mermaid-render"
+  ],
+  "handoff": [
+    {
+      "to": "mermaid-render",
+      "when": "the document has Mermaid diagrams and readers may be offline",
+      "purpose": "Render each diagram to SVG so it can be embedded and needs no network.",
+      "fallback": "If mermaid-render is absent, keep the diagrams as text (the default) and tell the user they show as source, or use --mermaid cdn and say it needs network."
+    }
+  ],
+  "tags": [
+    "html",
+    "markdown",
+    "convert",
+    "print",
+    "export",
+    "brand"
+  ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths", "notes": "The script makes no network calls. With --mermaid cdn, the HTML it writes loads Mermaid from cdn.jsdelivr.net when someone opens it."},
+  "model": {
+    "tier": "light",
+    "rationale": "A deterministic stdlib script does the conversion; the model picks options, fixes a few unsupported Markdown constructs and relays the script's warnings. Little judgment."
+  }
+}

skilldrop_cli/data/packs/converters/skills/md-to-html/reference.md

@@ -0,0 +1,70 @@
+# md-to-html reference
+
+## Markdown the script supports
+
+| Construct | Supported | Notes |
+|---|---|---|
+| ATX headings `#` to `######` | ✅ | Each gets an `id` from its text (`## Rollout plan` becomes `#rollout-plan`); duplicates get `-1`, `-2` |
+| Setext headings (`Title` over `===`) | ❌ | Comes through as a paragraph. Rewrite as `# Title` |
+| Paragraphs, hard breaks (two trailing spaces or `\`) | ✅ | |
+| `**bold**`, `*italic*`, `_italic_`, `~~strike~~`, `` `code` `` | ✅ | |
+| Links `[text](...)` with an optional `"title"`, `<https://…>`, bare `https://…` | ✅ | `javascript:`, `vbscript:` and non-image `data:` targets are dropped with a warning |
+| Reference links `[text][id]` | ❌ | Rewrite as inline links |
+| Images `![alt](...)` | ✅ | Local files embedded as data URIs; remote URLs kept and warned about; missing files shown as `[image not found: alt]` |
+| Ordered, unordered, nested lists; `- [ ]` task lists | ✅ | A blank line between items makes the list loose (each item a paragraph) |
+| GFM pipe tables with `:---:` alignment | ✅ | `\|` for a literal pipe; pipes inside `` `code` `` are kept |
+| Fenced code (```` ``` ```` or `~~~`) with a language | ✅ | `class="language-x"` on the `<code>`, no colouring |
+| Indented code (4 spaces) | ✅ | |
+| Blockquotes `>` | ✅ | Nested Markdown inside is rendered |
+| `---` / `***` rules | ✅ | |
+| YAML front matter at the top | ✅ | Removed from the output |
+| Footnotes `[^1]`, definition lists, math | ❌ | Plain text. Rewrite footnotes as a Notes section |
+| Raw HTML | Escaped | Shown as text; see below |
+
+## Why raw HTML is escaped by default
+
+The output is usually shared: attached to email, uploaded to an intranet, opened by people who
+did not write the source. Markdown drafts pick up pasted HTML from emails, web pages and other
+tools, and a `<script>`, an `onerror=` attribute or a `<form>` in that paste would run in every
+reader's browser. Escaping shows the HTML as text, so nothing is lost and nothing runs.
+`--allow-html` passes raw HTML *blocks* through (a line that starts with a tag, up to the next
+blank line). Inline tags inside a paragraph stay escaped either way.
+
+The file also carries a Content-Security-Policy that allows no scripts at all, or, with
+`--mermaid cdn`, only the one Mermaid loader (by hash) and jsDelivr.
+
+## brand.json fields read
+
+From the `brand-kit` shape:
+
+| Field | Used for |
+|---|---|
+| `colors.primary` | Headings, table header background, the header rule |
+| `colors.secondary` | Links |
+| `colors.accent` | Blockquote bar |
+| `colors.background`, `colors.text` | Page background and body text |
+| `fonts.heading.family` + `fallback` | Headings |
+| `fonts.body.family` + `fallback` | Body text |
+| `logo.primary` | Embedded at the top of the page, path relative to brand.json |
+| `legal.footer` | Footer line |
+
+A colour that is not a hex code is ignored with a warning. Fonts are named, not embedded: the
+reader's machine must have them, or the fallback is used. Say so when the brand font is not a
+common system font.
+
+## Print rules in the stylesheet
+
+- Page margins 18 mm top and bottom, 16 mm left and right; body text 11 pt.
+- Table header rows repeat on every page; tables, code blocks, quotes and images avoid page breaks inside.
+- Headings avoid being the last line on a page.
+- Code wraps instead of running off the page.
+- External links print their address after the link text.
+- Anchor `#` markers are hidden.
+
+## Mermaid
+
+| Mode | What the reader sees | Needs network |
+|---|---|---|
+| default (`--mermaid none`) | The diagram source in a box | No |
+| `--mermaid cdn` | The drawn diagram, by Mermaid 11.4.1 from jsDelivr, pinned to that exact version | Yes, each time the file is opened |
+| Pre-render with `mermaid-render`, reference the SVG as an image | The drawn diagram, embedded | No |