docs/

This directory is the source for craigjmidwinter.github.io/katra — reference docs and design notes, published by GitHub Pages. It is not part of the katra CLI nav; this file exists for whoever edits the site next.

How it’s built

Plain GitHub Pages, no custom Actions workflow:

Jekyll, theme is just-the-docs, pulled in via remote_theme in _config.yml and pinned to a tag (just-the-docs/just-the-docs@v0.12.0) so an upstream release can’t change the site without a commit here.
Served from /docs on the main branch — set in the repo’s Pages settings, not in any file here.
Plugins: jekyll-include-cache (required by just-the-docs when loaded remotely), jekyll-seo-tag (title/meta description/canonical/OG tags), jekyll-sitemap — all three are in GitHub Pages’ supported plugin allowlist, so no custom build step is needed.
Color scheme: _sass/color_schemes/katra.scss is the same Field Notebook palette the viewer itself uses (internal/viewer/assets/styles.css) — the docs and the product should never disagree about what katra looks like. If you change one, change both.

Nav order is nav_order in each page’s front matter; the Design notes pages nest under architecture.md via has_children: true / parent:.

Previewing locally

Honest note first: local Jekyll needs Ruby ≥ 2.7. The machine this README was written on has 2.6.10 (ruby -v), which is old enough that bundle install for github-pages will fail outright — check yours before trying:

ruby -v

If you’re on 2.7+:

cd docs
bundle init
bundle add jekyll --version "~> 3.9"
bundle add github-pages --group jekyll_plugins   # pins the same gem set Pages runs
bundle exec jekyll serve --livereload

Then open http://localhost:4000/katra/ — the baseurl in _config.yml is /katra, so the site does not live at the bare root even locally.

If your Ruby is too old, the honest fallback is: push to a branch and let GitHub Pages build it (Settings → Pages → your branch), or read the rendered Markdown directly — every page here is meant to stand on its own without the theme’s chrome.

What’s generated vs. authored

Authored by hand, in this directory: every .md page’s prose, _config.yml, _includes/, _sass/.

Generated, checked in as build output (not hand-edited):

Path	Generated by	Regenerate with
`docs/assets/brand/*` (favicons, lockup, wordmark, mark, social-preview)	`branding/build.py` — an exact-pixel-grid SVG mark, rasterized via `rsvg-convert`	`python3 branding/build.py`
`docs/assets/screenshots/*.png`	`scripts/capture-screenshots.sh` — Playwright driving a locally-built `katra serve` (and the hub, if `katra hub serve` is already up on `:4200`)	`scripts/capture-screenshots.sh`

Both scripts have their own header comments with the full contract (dependencies, what’s not CI-gated and why, in the screenshot script’s case). Regenerate and commit the output in the same PR as the change that caused it — neither is wired into CI as a staleness gate.

robots.txt in this directory is also hand-authored, not generated.