147 lines
7.6 KiB
Markdown
147 lines
7.6 KiB
Markdown
---
|
|
name: export-starlight
|
|
description: Export the local wiki/ knowledge base into an Astro + Starlight-consumable form at outputs/starlight/, producing a human-readable documentation website. Use when the user asks to "export the wiki to Starlight", "generate the docs site", "export as Astro Starlight", "build a human-readable wiki site", or "publish the knowledge base as a website".
|
|
---
|
|
|
|
# Export to Astro Starlight skill
|
|
|
|
## Purpose
|
|
|
|
Regenerate `outputs/starlight/` from the current `wiki/` tree so it can be
|
|
built and served as an Astro + Starlight documentation website — a
|
|
human-readable, browsable version of this knowledge base (unlike
|
|
`export-okf`, which targets machine/tool consumption). This is a one-way,
|
|
on-demand export — `wiki/` stays the authoritative source; `outputs/starlight/`
|
|
is always a derived artifact of it, never edited by hand and never fed back
|
|
in.
|
|
|
|
This skill only runs when explicitly invoked — it is deliberately not part
|
|
of the always-loaded `CLAUDE.md`/`AGENTS.md` Ingest/Lint workflows.
|
|
|
|
The heavy lifting (frontmatter remapping, link rewriting, asset copying,
|
|
sidebar generation) is done by a deterministic Python script, not by
|
|
reading and rewriting every page by hand — the wiki now has 60+ pages, and
|
|
a mechanical transform like this belongs in code, not in per-page model
|
|
reasoning. Nothing in this skill needs an LLM to run correctly; the model's
|
|
job is just to ask the two setup questions below, invoke the script, and
|
|
relay its report.
|
|
|
|
## Trigger phrases
|
|
|
|
Use this skill when the user says things like:
|
|
- "export the wiki to Starlight" / "export as Astro Starlight"
|
|
- "generate the docs site" / "build the Starlight site"
|
|
- "publish the knowledge base as a website"
|
|
- "sync outputs/starlight"
|
|
|
|
## 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
|
|
python3 "<skill-dir>/scripts/export_starlight.py" --mode <full|content-only> [--include-meta]
|
|
```
|
|
|
|
Resolve `<skill-dir>` to this skill's own directory. 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
|
|
|
|
- **A future `wiki/<newtopic>/` subdirectory:** handled automatically —
|
|
the script discovers top-level `wiki/` subdirectories dynamically and
|
|
adds a sidebar `autogenerate` group for each; no script changes needed.
|
|
- **Re-running with no wiki changes:** should produce byte-identical
|
|
output (directory listings are sorted before writing). If asset copying
|
|
or link rewriting ever introduces nondeterminism, that's a bug in the
|
|
script, not expected behavior.
|
|
- **A wiki page with no `tldr`:** `description` is simply omitted from
|
|
that page's frontmatter — Starlight tolerates a missing description.
|
|
- **A wiki page with no H1:** falls back to a slugified filename as the
|
|
title (e.g. `foo-bar.md` → "Foo Bar"), same fallback rule `export-okf`
|
|
uses.
|