AGENT SKILL

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

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-page or epub) 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.md completely. It defines the ordered-list invariants, current PDF/Paper profiles, and landing vocabulary.
  • At the start of Phase 2: read references/authoring-and-verification.md completely. 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 the reading-nav component.
  • [[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

  1. Inventory reports/*.md, audio files (.m4a, .mp3, .wav), PDF ocr/figures/*, and EPUB epub/media/* as applicable.
  2. Read references/profile-contract.md and resolve the consumer profile into one deterministic ordered [{ slug, kicker }] list. Fix it now; it is the source of truth for cards and navigation.
  3. 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.
  4. If site/ already exists, ask before clearing site/ and src/. 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.
  5. Create src/ and site/audio/; copy all source audio into site/audio/. src/ and site/ are reproducible and disposable. Never hand-edit site/.
  6. If ocr/figures/ exists, copy the whole directory to site/figures/. Copy every crop because page authors run independently; the generator rewrites report paths from ../ocr/figures/... to figures/....
  7. If the consumer supplied epub/media/, copy it recursively to site/media/. The generator rewrites ../epub/media/... to media/...; 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.

  1. Apply [[explainer-reading-site-page]] once per report, in parallel when the host supports isolated subagents. Each worker writes src/<slug>.md and returns only the source path, title, and a 2–3 line card summary.
  2. 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 from references/authoring-and-verification.md. The conventions are an explicit dispatch input because isolated workers cannot infer them from sibling output.
  3. 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.
  4. Compose src/index.md inline 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.
  5. Apply [[explainer-reading-site-consistency-sweep]] to every src/*.md at 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 to src/ 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.
  6. 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 .p is 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

  • overview is 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-docs build produces the landing and all report pages.
  • Every source-PDF page reference in prose uses the canonical .p form, and no page anchor appears in a heading.
  • Every EPUB source reference uses .source-locator with a canonical data-locator present in the consumer's map, and no fabricated .p appears.
  • The whole-source consistency sweep passes after parallel authoring and before the one site build.
  • nav-manifest.js is 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