feat(docs): an HTML target, so one source feeds the ODT and the artifact pages #124

Merged

peterswimm merged 1 commit from feat/udg-odf-document-product into main

2026-09-11 18:18:15 +00:00

peterswimm commented

2026-09-11 18:05:57 +00:00

Owner

Adds an HTML target to tools/doc_build.py, so one markdown source feeds the ODT and the artifact pages. Follows #121, which added the ODF writer and the document lint.

Scope

tools/doc_build.py --to html — a self-contained artifact page fragment: dist/<product>/skin.css inlined between UDG:BEGIN/UDG:END, token-only CSS so just doc-lint gates it, light and dark themes, tables in scroll containers, images as data URIs.
--only (repeatable) keeps whole top-level sections, so one source splits into several pages with nothing to drift apart; --title, --heading and --nav set each page's name, visible heading and sibling links.
justfile — just doc-html <src.md> for whole documents. Split pages call doc_build.py directly, because just's variadic arguments drop the quoting that --only "Part One" needs.

Testing

just check exit 0; pytest 291 passed.
ODT path unchanged: rebuilding the same source gives byte-identical content.xml and styles.xml.
Two real pages generated from one source: every section present (18 and 20), doc-lint exit 0, both figures inlined. Rendered in light and dark, including a figure with coloured arrows under dark-mode inversion. No sideways overflow at 500px (headless Chrome's minimum width).

Impact Statement

Additive: no change to existing ODT output, token sources or dist/.
Worth a follow-up: embedding Sora and DM Mono in the ODT. A recipient without them installed sees a serif fallback; DM Mono exists here only as WOFF2, which ODF cannot embed as-is.

Adds an HTML target to `tools/doc_build.py`, so one markdown source feeds the ODT and the artifact pages. Follows #121, which added the ODF writer and the document lint. ## Scope - `tools/doc_build.py --to html` — a self-contained artifact page fragment: `dist/<product>/skin.css` inlined between `UDG:BEGIN`/`UDG:END`, token-only CSS so `just doc-lint` gates it, light and dark themes, tables in scroll containers, images as data URIs. - `--only` (repeatable) keeps whole top-level sections, so one source splits into several pages with nothing to drift apart; `--title`, `--heading` and `--nav` set each page's name, visible heading and sibling links. - `justfile` — `just doc-html <src.md>` for whole documents. Split pages call `doc_build.py` directly, because just's variadic arguments drop the quoting that `--only "Part One"` needs. ## Testing - `just check` exit 0; `pytest` 291 passed. - ODT path unchanged: rebuilding the same source gives byte-identical `content.xml` and `styles.xml`. - Two real pages generated from one source: every section present (18 and 20), `doc-lint` exit 0, both figures inlined. Rendered in light and dark, including a figure with coloured arrows under dark-mode inversion. No sideways overflow at 500px (headless Chrome's minimum width). ## Impact Statement - Additive: no change to existing ODT output, token sources or `dist/`. - Worth a follow-up: embedding Sora and DM Mono in the ODT. A recipient without them installed sees a serif fallback; DM Mono exists here only as WOFF2, which ODF cannot embed as-is.

peterswimm added 1 commit

2026-09-11 18:05:57 +00:00

feat(docs): an HTML target, so one source feeds the ODT and the artifact pages

PR policy check / policy-gate (pull_request) Successful in 1s

Details

Test Generator / lint-workflows (pull_request) Successful in 20s

Details

Security Scans / Gitleaks secret scan (pull_request) Successful in 39s

Details

Security Scans / Trivy filesystem scan (pull_request) Successful in 48s

Details

Test Generator / test (pull_request) Failing after 1m3s

Details

Test Generator / lint-prose (pull_request) Successful in 37s

Details

UDG dist drift gate / dist/ matches dtcg + udg sources (pull_request) Successful in 25s

Details

Copy coverage / Design copy reaching rendered HTML (pull_request) Failing after 39s

Details

792fd8750b

doc_build.py --to html writes a self-contained page fragment for a claude.ai
artifact: dist/<product>/skin.css inlined between UDG:BEGIN and UDG:END,
token-only CSS so just doc-lint gates it, light and dark themes, tables in
scroll containers, and images as data: URIs because the artifact sandbox
loads no external images.

--only keeps whole top-level sections, so one markdown source splits into
several pages with no copies to drift apart. --title keeps an artifact's
name stable, --heading sets the visible H1, --nav links sibling pages.

First use: a proposal and SOW whose published pages had fallen a full
revision behind their source document. Both are now generated from it.

The ODT path is unchanged: rebuilding the same source gives byte-identical
content.xml and styles.xml.

just doc-html renders a whole document. Split pages call doc_build.py
directly, because just's variadic arguments drop the quoting that
--only "Part One" needs.

peterswimm merged commit 66f2f7e36f into main

2026-09-11 18:18:15 +00:00

peterswimm deleted branch feat/udg-odf-document-product

2026-09-11 18:18:16 +00:00

peterswimm referenced this pull request from a commit

2026-09-11 18:18:16 +00:00

Merge pull request 'feat(docs): an HTML target, so one source feeds the ODT and the artifact pages' (#124) from feat/udg-odf-document-product into main

peterswimm referenced this pull request

2026-09-11 18:33:12 +00:00

feat(docs): carry the brand fonts inside the ODT #125