explainer-html-docs

Files (66)

• SKILL.md
• base.css · assets/
• base.js · assets/
• color.css · assets/
• comments.css · assets/components/comments/
• comments.js · assets/components/comments/
• include.md · assets/components/comments/
• diagram.css · assets/components/diagram/
• diagram.js · assets/components/diagram/
• include.md · assets/components/diagram/
• diff.css · assets/components/diff/
• diff.js · assets/components/diff/
• include.md · assets/components/diff/
• highlight.css · assets/components/highlight/
• highlight.js · assets/components/highlight/
• include.md · assets/components/highlight/
• include.md · assets/components/reading-nav/
• reading-nav.css · assets/components/reading-nav/
• reading-nav.js · assets/components/reading-nav/
• template-tier2.html · assets/
• template.html · assets/
• components.md · docs/
• htmldocs.lua · filters/
• tier2.lua · filters/
• flake.lock
• flake.nix
• authoring-contract.md · references/
• markup-and-components.md · references/
• build-reference-site.sh · scripts/
• build-site.sh · scripts/
• build.sh · scripts/
• inline.awk · scripts/
• preflight.sh · scripts/
• base.css · site/assets/
• base.js · site/assets/
• color.css · site/assets/
• comments.css · site/assets/components/comments/
• comments.js · site/assets/components/comments/
• include.md · site/assets/components/comments/
• diagram.css · site/assets/components/diagram/
• diagram.js · site/assets/components/diagram/
• include.md · site/assets/components/diagram/
• diff.css · site/assets/components/diff/
• diff.js · site/assets/components/diff/
• include.md · site/assets/components/diff/
• highlight.css · site/assets/components/highlight/
• highlight.js · site/assets/components/highlight/
• include.md · site/assets/components/highlight/
• include.md · site/assets/components/reading-nav/
• reading-nav.css · site/assets/components/reading-nav/
• reading-nav.js · site/assets/components/reading-nav/
• nav-manifest.js · site/assets/
• color.html · site/
• components.html · site/
• contract.html · site/
• enhancement.html · site/
• foundation.html · site/
• index.html · site/
• tier2.html · site/
• color.md · src/
• …and 6 more

SKILL.md (first lines)

# explainer-html-docs — design system + semantic Markdown → page generator

This skill owns the shared design system, progressive-enhancement kit, and
deterministic generator used by [[diff-explainer]], the PDF/Paper reading sites, and
future explanation documents of the same shape.

The contract has two layers:

- The author writes **semantic Markdown**: Markdown plus fenced divs that name
  meaning (`::: {.callout variant=danger}`), never presentation.
- The generator binds that meaning to markup through `assets/template.html` and
  `filters/htmldocs.lua`.

Consumers copy the generated assets into their output and may add a context
stylesheet, context scripts, a consumer filter, or a template variant. They never
edit this skill's assets per document.

## Required reading by task

Read only the reference that the current task needs:

- **Authoring or generating a page/site:** read
  [`references/authoring-contract.md`](references/authoring-contract.md) completely
  before writing semantic Markdown or running a build. It contains the frontmatter,
  full semantic notation, consumer-extension contract, commands, and copy/inline
  behavior.
- **Reviewing generated output, using Tier 2 components, or changing the base:**
  read [`references/markup-and-components.md`](references/markup-and-components.md)
  completely. It contains the canonical meaning→markup index, review ownership,
  opt-in component rules, component-change checklist, and operational gotchas.
- **Designing or promoting a component:** also read
  [`docs/components.md`](docs/components.md) completely before editing. It is the
  existing normative design rationale and remains at this path for consumers that
  already link to it.

## The reference site is the contract

The normative worked example and visual catalog is the committed reference site under
`site/`:

| Page | Covers |
|---|---|
| `site/index.html` | Consumption modes, skeleton, page index |
| `site/foundation.html` | Classless headings, prose, tables, code, quotes |
| `site/color.html` | Meaning-only color model and token layers |
| `site/components.html` | Tier 1 semantic components |
| `site/enhancement.html` | `base.js` behavior and preconditions |
| `site/tier2.html` | Opt-in highlight, diff, diagram, comments, reading-nav bundles |
| `site/contract.html` | Generation and review contract |

The site is generated from `src/*.md` by this skill itself. When a summary elsewhere
disagrees with the site, the site wins. Edit the semantic source, then run
`scripts/build-reference-site.sh`; never hand-edit generated files under `site/`.
Serve `site/` over HTTP when inspecting the diagram component because ES modules do
not render over `file://`.

## Owned resources

Resolve all paths relative to this skill's installed directory:

- `assets/base.css`: foundation, meaning-only colors, Tier 1 components, and styles
  toggled by progressive enhancement.
- `assets/base.js`: dependency-free theme toggle, reading progress, responsive TOC
  with scroll-spy, and back-to-top.
- `assets/template.html`: generated page skeleton, theme boot, asset order,
  `header.site`, and `main article`.
- `assets/components/<name>/`: Tier 2 opt-in bundles.
- `filters/htmldocs.lua`: semantic vocabulary binding, hard validation, table
  wrapping, and figure-path rewriting.
- `scripts/build.sh`: build one page; `scripts/build-site.sh`: build a source
  directory; `scripts/preflight.sh`: resolve pandoc from PATH or bundled
  `nix develop`; `scripts/inline.awk`: fold local assets into a single page.
- `flake.nix` / `flake.lock`: pinned fallback runtime.

## Invariants

- **Use generation as the only authoring route.** Do not hand-write the page shell,
  asset links, base classes, inline colors, or table wrappers.
- **Preserve hard failures.** An unknown callout variant and a `.player` without
  `src=` must fail generation. Raw HTML is disabled with `-f markdown-raw_html`, so
  invented classes and inline styles cannot pass through.
- **Keep generated markup deterministic.** `template.html` owns structural
  boilerplate and asset order; `htmldocs.lua` owns meaning→markup and wraps every
  table in `.tablewrap`.
- **Copy local assets into each output.** Never link to the installed skill path.
  The static output remains readable without a server and without `base.js`.
- **Use color only for meaning.** `note`/`tip`/`warn`/`danger`/`key` and `<mark>`
  have fixed meanings. Everything else uses `--accent`; never color-code chapters or
  sections by position.
- **Let consumers own content semantics.** A consumer may add a non-conflicting
  semantic axis through its own stylesheet and filter. It must review any
  high-stakes semantic choices it introduces.
- **Keep heavy renderers opt-in.** Highlight.js, diff2html, and mermaid integrations
  live in Tier 2 bundles and may use version-pinned CDNs. The base substrate itself
  stays local and offline-capable.
- **Treat structure as opt-in.** A consumer needing several `article` elements or no
  `base.js` supplies a template variant; it does not fork the design system.

## Generation order

1. Read `references/authoring-contract.md`.
2. Author semantic Markdown and any consumer-owned context/filter/template.
3. Run `scripts/build.sh` for one page or `scripts/build-site.sh` for a site.
4. Pick a layout variant if the default 56rem measure is not right: `--layout
   narrow | wide`, or `layout:` in frontmatter. See the layout table in
   `references/authoring-contract.md`.
5. If a Tier 2 bundle is needed, pass repeatable `--component <name>` and follow that
   bundle's `include.md`.
6. Apply the review ownership described in
   `references/markup-and-components.md`: generated mechanics need no standalone
   review, while consumer-defined high-stakes semantics do.

The output shapes are:

- **Copy mode** (default): pages share a generated `assets/` directory.
- **Inline mode** (`build.sh --inline`): local CSS/JS is folded into one portable
  HTML file; remote CDN engines remain external.

## Completion checks

From choplin/explainer-studio, MIT.

More from choplin/explainer-studio