oscal documentation site

oscal documentation site

website/ holds an Astro Starlight site, which the README describes as built from the README, docs/, the schema’s pages and the knowledge bundle, and whose address it gives as https://lmodel.github.io/oscal.¹ CHANGELOG.md says that this knowledge website replaces the mkdocs site.² NOTICE says that the site derives from the ktl-website templates of the Knowledge Trust Ladder repository.

website/README.md says that the Knowledge website workflow publishes the site to GitHub Pages at https://lmodel.github.io/oscal/.³ website/site.config.mjs names the repository lmodel/oscal, the address https://lmodel.github.io and the base path /oscal.⁴ A comment in lychee.toml says that the site answers once the workflow first deploys it to Pages, so the link check leaves its address out until then.⁵

What the pages come from

website/README.md says that every page comes from a file the repository already holds, so a change to the site is a change to that file:

• each concept in .lokf/knowledge/ becomes a page under knowledge/, with its trust label from knowledge-report.sh, its sources and its typed relations both ways, and the four files lokf export writes are served beside them;
• the README becomes the home page, and each page under docs/ a page under docs/, except docs/templates-linkml/, which site.config.mjs leaves out;
• CHANGELOG.md becomes a page per release under changelog/, which site.config.mjs shows once the file holds a released version;
• the schema’s pages, which gen-doc writes into docs/elements/, become a page each under schema/, with their class diagrams drawn in the browser. The folder is not committed, so the sync runs the command that builds it when it is missing.

site.config.mjs shows no data pages, since BROWSE is null. Its REDIRECTS send the addresses that the mkdocs site gave its pages on to the new ones: /elements and each /elements/<name> to /schema/, and /about to /docs/about/.

Previewing it

Previewing needs Node.js 22.12 or later and uv. In website/, run npm ci --ignore-scripts, then npm run dev for a local server, or npm run build, which writes dist/ and then checks every link between its pages. Both run npm run sync first, which runs lokf export from the sidecar’s environment in .lokf/ and writes the generated pages. Nothing the sync writes is committed. From the repository root, just testdoc runs just gen-doc and then the same local server.⁶

Publishing it

Knowledge website builds the site on pull requests and on the default branch, and deploys it to GitHub Pages only once the repository variable KNOWLEDGE_WEBSITE_ENABLED is true.

Editing it

Change a page’s words in the file it comes from: the README, a page under docs/, the schema, or a concept, which goes through the librarian and the curator like any other change to the bundle. Change the site’s values and options in site.config.mjs, and its look in src/styles/custom.css, which is this repository’s own.

Footnotes

1. README.md, Documentation Website and the website item of Repository Structure ↩

2. CHANGELOG.md, the last item under Added ↩

3. website/README.md, the list of page sources, Preview it and What to edit ↩

4. website/site.config.mjs, REPO, SITE, BASE, DOCS, REDIRECTS, CHANGELOG, SCHEMA and BROWSE ↩

5. lychee.toml, the comment above the site’s address in exclude ↩

6. justfile, the testdoc and _serve recipes ↩