122 lines
6.3 KiB
Markdown
122 lines
6.3 KiB
Markdown
---
|
|
name: ckb-export-starlight
|
|
description: 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:
|
|
|
|
1. **Export scope:**
|
|
- "Full runnable scaffold" → `--mode full` — regenerates the whole
|
|
`outputs/starlight/` project (package.json, astro.config.mjs with
|
|
sidebar, tsconfig.json, src/content.config.ts, splash `index.mdx`)
|
|
plus all content. Fully deletes and rebuilds `outputs/starlight/`.
|
|
- "Content only" → `--mode content-only` — regenerates only
|
|
`src/content/docs/**`, `public/assets/**`, and a `SIDEBAR-SNIPPET.md`
|
|
with 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.
|
|
|
|
2. **Meta pages:**
|
|
- "Include them" → add `--include-meta` — publishes `wiki/log.md` as a
|
|
Change Log page and `wiki/error-book.md` as an Error Book page.
|
|
- "Exclude them" → omit the flag — only entities, sources, graph, and
|
|
overview get published.
|
|
|
|
### Step 2 — Run the script
|
|
|
|
From the repository root:
|
|
|
|
```bash
|
|
<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-meta` was 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, or `npm install`ed — those are separate steps for
|
|
the user. For `--mode full`, the site is immediately runnable with
|
|
`cd 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 `# H1` in the body
|
|
becomes Starlight's required `title` (and is removed from the body, since
|
|
Starlight renders `title` as the page heading itself — leaving the H1 in
|
|
would duplicate it). `type`/`confidence`/`quality`/`retention`/
|
|
`last_updated`/`resource` have 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" (if
|
|
`superseded_by` is set), else "Stale" (if `last_updated` +
|
|
`freshness_window_days` has elapsed), else "Low confidence" (if
|
|
`confidence` < 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's `index.md` maps 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.jpg` are
|
|
copied to `public/assets/people/x.jpg` and rewritten to `/assets/people/x.jpg`.
|
|
- **Graph:** `wiki/graph/edges.json` is not copied verbatim (Starlight
|
|
doesn't render JSON as a page) — its content is fully rendered as a
|
|
Markdown table appended to `graph/index.md`, sorted by `from`, so no
|
|
information is lost.
|
|
- **Sidebar:** one `autogenerate` group per top-level `wiki/` subdirectory
|
|
(so new pages added to `entities/`/`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`](references/edge-cases.md). Read that file when a
|
|
run hits something the steps above don't cover; don't load it otherwise.
|