6.3 KiB
| name | description |
|---|---|
| ckb-export-starlight | Export wiki/ into an Astro + Starlight-consumable form at outputs/starlight/, producing a human-readable documentation website. Use for "export the wiki to Starlight", "generate the docs site", "build a human-readable wiki site", or "publish the knowledge base as a website". |
Export to Astro Starlight skill
Purpose
One-way and on demand: wiki/ stays authoritative, outputs/starlight/ is
derived, never hand-edited, never fed back in. A deterministic script does
the transform; the model asks the two setup questions below, invokes it, and
relays its report. Human-readable counterpart of ckb-export-okf.
How to run this skill
Step 1 — Ask the two setup questions, every time
The user has explicitly said they want to choose these on every invocation
— do not assume a default or reuse an answer from a previous run. Use
AskUserQuestion with:
-
Export scope:
- "Full runnable scaffold" →
--mode full— regenerates the wholeoutputs/starlight/project (package.json, astro.config.mjs with sidebar, tsconfig.json, src/content.config.ts, splashindex.mdx) plus all content. Fully deletes and rebuildsoutputs/starlight/. - "Content only" →
--mode content-only— regenerates onlysrc/content/docs/**,public/assets/**, and aSIDEBAR-SNIPPET.mdwith the sidebar config to paste in. Leaves any existing scaffold files (package.json, astro.config.mjs, tsconfig.json, content.config.ts, index.mdx) untouched — use this if the user is dropping the output into a Starlight project they already maintain elsewhere.
- "Full runnable scaffold" →
-
Meta pages:
- "Include them" → add
--include-meta— publisheswiki/log.mdas a Change Log page andwiki/error-book.mdas an Error Book page. - "Exclude them" → omit the flag — only entities, sources, graph, and overview get published.
- "Include them" → add
Step 2 — Run the script
From the repository root:
<python> "<skill-dir>/scripts/export_starlight.py" --mode <full|content-only> [--include-meta]
Resolve <skill-dir> to this skill's own directory and <python> per
"Scripts and the Python Runtime" in AGENTS.md. Python 3.8+ is a hard
requirement here (and Node.js to build the site afterwards) — there is
no manual fallback. If no interpreter is found, stop before asking the
setup questions, say so, and point to "Prerequisites" in docs/MANUAL.md.
Optional extra flag:
--site-title "Custom Title" overrides the auto-derived site title (which
otherwise comes from wiki/overview.md's H1 — a serviceable but generic
default like "Knowledge Base Overview"). Consider offering this to the user
rather than always silently accepting the default, since it's the one
piece of branding a reader sees first.
Step 3 — Relay the script's report
The script prints, and you should summarize back to the user:
- Mode used and page count exported.
- Assets (images) copied.
- Which meta pages were skipped (if
--include-metawas omitted). - Any unresolved
[[wikilinks]](bare wikilinks with no matching page title — these get silently degraded to plain text in the output; a small number is normal wiki-content noise, but flag the list so the user can fix the source page if it's not). - Any broken internal links the validation pass found (a link that was
rewritten to a route with no corresponding generated file) — this is a
real problem in the source
wiki/content (a stale or malformed cross-reference), not a bug in the export, and is worth reporting back as something to fix at the source. - A reminder that
outputs/starlight/has been regenerated on disk but not staged, committed, ornpm installed — those are separate steps for the user. For--mode full, the site is immediately runnable withcd outputs/starlight && npm install && npm run dev.
What the transform does (for context, not something you need to re-derive)
- Frontmatter:
tldr→description; the first# H1in the body becomes Starlight's requiredtitle(and is removed from the body, since Starlight renderstitleas the page heading itself — leaving the H1 in would duplicate it).type/confidence/quality/retention/last_updated/resourcehave no native Starlight field, so they're rendered as a:::note[Knowledge base metadata]aside at the top of the page body instead of being dropped. - Badges: a page gets a
sidebar.badge— "Superseded" (ifsuperseded_byis set), else "Stale" (iflast_updated+freshness_window_dayshas elapsed), else "Low confidence" (ifconfidence< 0.5) — priority in that order, one badge max. - Links: dual-linked cross-references (
[text](path) ([[Wikilink]]), or the older[[Wikilink]] / [text](path)ordering) collapse to just the markdown link, since Starlight has no wikilink concept. Bare[[Wikilinks]]are resolved against every page's H1 title and converted to a proper link where a match exists, otherwise degraded to plain text. Root-absolute/wiki/...links become site routes (/wiki/entities/foo.md→/entities/foo/; a link to a directory'sindex.mdmaps to the bare directory route, e.g./entities/).linked/.../libs/...cascade references (pointing outside any self-contained export) become plain text noting the path, not a broken link. - Assets: person photos referenced as
../assets/people/x.jpgare copied topublic/assets/people/x.jpgand rewritten to/assets/people/x.jpg. - Graph:
wiki/graph/edges.jsonis not copied verbatim (Starlight doesn't render JSON as a page) — its content is fully rendered as a Markdown table appended tograph/index.md, sorted byfrom, so no information is lost. - Sidebar: one
autogenerategroup per top-levelwiki/subdirectory (so new pages added toentities//sources/graph/any future topic folder show up automatically on the next export without touching the sidebar config), plus explicit entries for the handful of root-level pages (Overview, the routing table, and the two optional meta pages).
Edge cases
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
references/edge-cases.md. Read that file when a
run hits something the steps above don't cover; don't load it otherwise.