Explainer reading site generate base
Skill choplin/explainer-studio/skills/explainer/explainer-reading-site-generate-base
Internal build orchestrator invoked by book and paper site consumers. Turns reports into semantic pages, a landing page, assets, and navigation using the consumer's ordering profile and vocabulary.From its SKILL.md
npx -y skills add choplin/explainer-studio --skill explainer-reading-site-generate-baseAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
9.2 KB, as published. Nobody here has run it
explainer-reading-site-generate-base — shared build pipeline
This skill owns the pipeline shared by [[book-explainer-generate-site]],
[[paper-explainer-generate-site]], and future consumers that turn a work directory's
reports/ into a reading-guide site.
The consumer owns only:
- its trigger;
- an ordered
[{ slug, kicker }]page profile; - the absolute path to its canonical source-structure artifact;
- its locator kind (
pdf-pageorepub) and EPUB locator map when applicable; - its optional original-media source and destination;
- three landing-page nouns: guide kicker, cards-section heading, and count-chip unit.
This base owns scaffold, semantic authoring, the single generator build, landing page,
navigation manifest, verification, and deployment handoff. The output is
<WORK_DIR>/site/; deployment is a separate
[[explainer-reading-site-deploy]] action.
Required reading by phase
- Before resolving pages or adding a consumer: read
references/profile-contract.mdcompletely. It defines the ordered-list invariants, current PDF/Paper profiles, and landing vocabulary. - At the start of Phase 2: read
references/authoring-and-verification.mdcompletely. It contains per-page delegation inputs, landing source notation, nav-manifest format, gotchas, and the full success checklist.
Do not read the second reference during Phase 1 inventory unless you need to inspect the later output contract.
Preconditions and ownership
The input is <WORK_DIR> with at least one reports/*.md and the consumer's
canonical source-structure artifact. audio/, PDF ocr/figures/, and EPUB
epub/media/ are optional. If
reports or the structure artifact are missing, stop and ask the consumer's
summarize skill to run first. Audio can be produced through
[[explainer-audio-dialogue]] and [[explainer-audio-narrate]].
Both dependency skills must be installed:
- [[explainer-html-docs]] supplies
base.css,base.js, the deterministic semantic-Markdown generator, and thereading-navcomponent. - [[explainer-reading-site-library-base]] supplies the shared content layer
reading-site.css.
If either dependency is missing, stop and report it; never guess a path or fork the assets.
Pages are authored, not converted, and are written as semantic Markdown. The [[explainer-reading-site-page]] procedure restructures each report for web reading. The generator then owns head markup, theme boot, asset order, classes, table wrapping, and figure-path rewriting. A 1:1 Markdown conversion or hand-written HTML is not the deliverable.
Pipeline
Run these phases in order. Do not build before every semantic source, including the landing, is ready.
Phase 1 — Scaffold
- Inventory
reports/*.md, audio files (.m4a,.mp3,.wav), PDFocr/figures/*, and EPUBepub/media/*as applicable. - Read
references/profile-contract.mdand resolve the consumer profile into one deterministic ordered[{ slug, kicker }]list. Fix it now; it is the source of truth for cards and navigation. - Resolve the consumer's canonical source-structure artifact and verify it exists. Keep its absolute path as the source-topology authority for every page worker and the fan-in sweep; never infer source structure from authored pages.
- If
site/already exists, ask before clearingsite/andsrc/. Recommend a clean rebuild so removed reports/audio cannot remain as publishable orphans. If the user declines, build over the existing tree and warn about stale files. - Create
src/andsite/audio/; copy all source audio intosite/audio/.src/andsite/are reproducible and disposable. Never hand-editsite/. - If
ocr/figures/exists, copy the whole directory tosite/figures/. Copy every crop because page authors run independently; the generator rewrites report paths from../ocr/figures/...tofigures/.... - If the consumer supplied
epub/media/, copy it recursively tosite/media/. The generator rewrites../epub/media/...tomedia/...; keep original bytes and relative manifest paths.
Do not copy design assets in this phase. The generator copies them in Phase 3.
Phase 2 — Author all semantic sources
Read references/authoring-and-verification.md completely now.
- Apply [[explainer-reading-site-page]] once per report, in parallel when the host
supports isolated subagents. Each worker writes
src/<slug>.mdand returns only the source path, title, and a 2–3 line card summary. - Pass each worker only the absolute report/output paths, the absolute canonical
source-structure path, locator kind and EPUB map when applicable, site title,
profile kicker, source-media availability, matching audio filename or
none, and the exact canonical site-wide authoring conventions fromreferences/authoring-and-verification.md. The conventions are an explicit dispatch input because isolated workers cannot infer them from sibling output. - Do not have workers author head markup, presentation-only classes outside the page skill's semantic vocabulary, figure rewrites, or prev/next links. Runtime navigation comes from the manifest written in Phase 3.
- Compose
src/index.mdinline from worker replies and the consumer vocabulary. Do not re-read report sources for cards. The landing is semantic Markdown and is built like every other page. - Apply [[explainer-reading-site-consistency-sweep]] to every
src/*.mdat once, including the landing. Pass the fixed profile and the same canonical conventions used for page dispatch, the canonical source-structure path, plus the site title and consumer landing vocabulary. Apply its targeted findings tosrc/and rerun it until clean. This fan-in gate catches source-attribution errors, required markup omissions, and cross-page structural drift that are valid Markdown and therefore invisible to the generator. Do not begin Phase 3 while findings remain. - Run any deterministic locator validator supplied by the consumer. The EPUB
consumer rejects unknown canonical locators here before Pandoc; PDF and paper
consumers need no extra command because
.pis self-validating.
Phase 3 — Build once, then write navigation data
Build every src/*.md in one pass:
explainer-html-docs/scripts/build-site.sh <WORK_DIR>/src <WORK_DIR>/site \
--assets explainer-html-docs/assets \
--context explainer-reading-site-library-base/assets \
--filter explainer-reading-site-library-base/filters/reading-site.lua \
--component reading-nav
Resolve dependency directories as sibling skills under the installed skills root.
The command builds src/index.md and every report source, and copies base.css,
base.js, reading-site.css, reading-nav.css, and reading-nav.js.
A bad source must fail loudly. Fix the named source and rerun the build; do not bypass unknown variants or missing player sources.
After the build, write site/assets/nav-manifest.js from the Phase 1 order and Phase
2 titles. It assigns window.__HTMLDOCS_NAV; include every report page exactly once
and omit the landing. This generated data is the only page-order source. Never author
neighbor links into individual pages.
Phase 4 — Verify and hand off
Apply every item in the success checklist in
references/authoring-and-verification.md. Do not claim success from a build command
alone.
Then tell the user the site is ready under <WORK_DIR>/site/ and offer
[[explainer-reading-site-deploy]]. If the shared library has never been deployed,
[[explainer-reading-site-initialize]] must run first. Never deploy from this skill;
the user reviews the built artifact before it goes public.
Core invariants
overviewis first and is the landing hero CTA.- Every existing report appears exactly once in a deterministic order and has a non-empty kicker.
- Reports are not color-coded by chapter, section, or perspective.
src/contains semantic Markdown;site/contains generated output. Source and editorial body headings use distinct structure-provenance classes.- Source-derived headings match the consumer's canonical source-structure artifact; editorial headings are visibly attributed in both the article and TOC.
- One
explainer-html-docsbuild produces the landing and all report pages. - Every source-PDF page reference in prose uses the canonical
.pform, and no page anchor appears in a heading. - Every EPUB source reference uses
.source-locatorwith a canonicaldata-locatorpresent in the consumer's map, and no fabricated.pappears. - The whole-source consistency sweep passes after parallel authoring and before the one site build.
nav-manifest.jsis the only page-navigation source.- Shared assets are reused through
--assets,--context, and--component reading-nav; consumers do not fork them. - The site stays readable with JavaScript disabled and contains every local figure and audio file it references.