Knowledge Website

Overview

website/ builds the site that the Knowledge website workflow publishes to GitHub Pages at https://noelmcloughlin.github.io/obsidian-ktl-registrar/. The ktl-website skill installed both the folder and the workflow. Every page comes from a file the repository already holds, so a change to the site is a change to that file.

What the site is built from

• 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.

• The four files lokf export writes are served under knowledge/, beside each concept’s own Markdown file and its JSON-LD. The bundle log is served as an Atom feed, knowledge/log.xml.

• The README becomes the home page, each page under docs/ becomes a page under docs/, and CHANGELOG.md becomes a page per release under changelog/, which search leaves out. Each release page links the repository, the docs and the bundle at the release’s tag.

• The LinkML schema’s pages and SQLite databases are shown only when site.config.mjs shows them. This repository’s site.config.mjs sets SCHEMA to "auto" and BROWSE to null.

The commit that promotes a release’s changelog skips CI, so its page appears with the next build: the workflow’s weekly run at the latest, or a run by hand.

Preview it

You need Node.js 22.12 or later and uv. From website/, run npm ci, then npm run dev to serve the site at http://localhost:4321/obsidian-ktl-registrar/, or npm run build to write dist/ and check every link between its pages. Both commands run npm run sync first, which runs lokf export from the sidecar’s own environment in .lokf/ and writes the generated pages. Nothing the sync writes is committed.

What to edit

• Edit a page’s words in the file it comes from: the README, a page under docs/, or a concept, through the librarian and the curator like any other change to the bundle.

• Edit the site’s values and options (the addresses, the title, the logo, the home page’s tagline and buttons, the docs groups and the extra pages) in site.config.mjs.

• Edit the site’s look in src/styles/custom.css, which is this repository’s own. theme.css and catalogue.css are the house style.

The workflow

.github/workflows/knowledge-website.yaml runs on a push to the default branch and on a pull request when either touches website/, the bundle, the README, docs/, .assets/, CHANGELOG.md, llms.txt, .linkml/, a justfile, a pyproject.toml, a uv.lock or the workflow itself. It also runs on Mondays at 05:23 UTC and on demand. It has two jobs, split for least privilege:

• build runs under a read-only token. It installs the lokf toolkit the sidecar pins with uv sync --locked, runs npm ci and npm run build in website/, and uploads website/dist as the Pages artifact. A pull request gets the same build and link check, and no deployment.

• deploy runs only GitHub’s own deploy-pages action and holds the pages: write and id-token: write scopes. It runs for the default branch only, and only once the repository variable KNOWLEDGE_WEBSITE_ENABLED is true.

Set KNOWLEDGE_WEBSITE_ENABLED under Repository variables, not on an environment, because a job’s if: sees only repository and organization variables. Before setting it, tell Pages once to take its site from Actions, under Settings > Pages > Source. A repository that already publishes Pages another way keeps the variable unset until that publisher is retired, because two publishers overwrite each other’s site.