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.
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- explainer-reading-site-generate-base
- description
- 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.
- user-invocable
- false
02 资源文件 2
- 参考文档references/authoring-and-verification.md10.2 KB
- 参考文档references/profile-contract.md3.1 KB
03 SKILL.md 正文
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 is produced through
[[explainer-audio-guide]], which owns the whole audio phase chain.
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.
04 同仓库更多 Skills
invalid-skill-frontmatter
暂无简介
pdf-explainer-summarize
Digest a book, manual, or other long non-paper PDF into a source-anchored Markdown overview. Use when the requested deliverable is only a report, digest, or summary. Use paper-explainer-summarize for academic papers, direct reading for short PDFs, and book-explainer for coordinated reports, audio, site, rebuild, or resume.
pdf-explainer-pdf-stitch
Internal Phase 2 worker invoked once by pdf-explainer-summarize after chunk extraction. Reconciles sections across chunk boundaries, deduplicates the material, and writes the canonical structural spine and outline.
pdf-explainer-pdf-extract
Internal Phase 1 worker invoked by pdf-explainer-summarize once per page chunk. Reads the chunk visually or from a faithful text layer and writes structured source material with a verbatim heading stream, not a finished report.
pdf-explainer-pdf-detail
Internal per-chapter worker invoked by book-explainer for PDF input. Re-read one resolved chapter span visually or from a faithful text layer and write a standalone detail report with [pNN] source anchors.
pdf-explainer-generate-site
Compatibility entry point for requesting a local PDF reading site from an existing work directory. Route through book-explainer so Artifact reconciliation and Planning still occur.