| name | okf-site-kit |
| description | Turn any Open Knowledge Format (OKF v0.1) bundle into a beautiful, browsable static website. Use when the user wants to publish, browse, view, share, or "make a site from" an OKF bundle / knowledge folder / agent-readable markdown wiki — e.g. "generate a site from my knowledge bundle", "make this OKF browsable", "publish the team knowledge to GitHub Pages". Ships a stdlib generator that reads the bundle (concepts with YAML frontmatter, reserved index.md/log.md, nested directories, non-markdown assets) and emits a complete Astro + Starlight project: hero landing page with section cards, one page per concept with an OKF metadata panel (type badge, tags, resource, timestamp, producer keys), rewritten internal links, changelog from log.md, full-text search, and light/dark theming. Tolerates every bundle dialect found in the wild — Google's sample bundles, spec-canonical bundles, and producer-extended bundles — reporting conformance warnings instead of failing. |
| license | MIT |
| compatibility | Requires python3 (stdlib only) to inspect bundles and generate the project; Node.js 18+ with npm to build/preview the emitted Astro + Starlight site (network needed only for npm install). |
| x-spec-version | 1 |
| metadata | {"author":"dhanesh","version":"1.1.0","tags":"okf,static-site,astro,starlight,knowledge-base,documentation,site-generator"} |
okf-site-kit
Generate a browsable website from an Open Knowledge Format bundle. OKF (Google's open
spec for agent-readable knowledge) deliberately ships no required tooling — a bundle is
just markdown with YAML frontmatter — which means "browsable" is left to consumers. This
skill is that consumer: assets/okf_site.py (stdlib-only) reads any
OKF bundle and emits a complete Astro + Starlight static-site project with search,
navigation, and OKF-aware presentation. The bundle stays the canonical knowledge; the
site is a generated view of it, regenerated whenever the bundle changes.
Ground rules
- The bundle is read-only. The generator never mutates the source bundle. When the
scan finds problems worth fixing at the source (missing
type, broken links), surface
them to the user and fix the bundle only if they ask.
- Tolerance over rejection. Per the OKF spec's consumer rules, unknown types, extra
frontmatter keys, missing optional files, and broken links must degrade gracefully.
The generator renders everything it can and prints
WARN: lines for the rest — pass
the warnings on, don't suppress them.
- Spec tracking. The generator targets OKF v0.1. If the spec has moved (check
references/okf-spec.md for the URL and update rule), update
the generator before emitting a stale dialect.
Workflow
- Locate and inspect the bundle. The bundle root is the directory whose
index.md
(or concept tree) the user means — for bundles made by the feynman-walkthrough
skill it's the knowledge root (e.g. docs/knowledge/). Run
python3 assets/okf_site.py inspect <bundle> and read the report: concept count and
routes, declared okf_version, and conformance warnings. Relay warnings that the
user can act on (concepts missing type, files without frontmatter).
- Generate the site.
python3 assets/okf_site.py generate <bundle> --out <dir>
with flags from references/parameters.md: --title
(defaults to the root index's H1), --tagline, --base /<repo> +
--site https://<user>.github.io + --deploy-workflow when the target is GitHub
Pages. The output is a self-contained project — nothing in it references the skill.
- Build and verify.
cd <dir> && npm install && npm run build must complete with
zero errors; treat generator lines about unresolved links as content issues
to report. Where a browser is available, and check the two pages
that prove the generation: the homepage (hero, one card per section, working links)
and one concept page (type badge, tags, metadata panel, rewritten links, table of
contents). Fix and regenerate until clean.
