Handbook: Zensical skeleton, ADR and publishing to git-pages #138

Closed
opened 2026-11-06 09:59:45 +01:00 by miko · 1 comment
Owner

Part of #137

What

Set up the handbook site: a Zensical project in handbook/ with the skeleton of both handbooks, published to git-pages as part of the release.

Decisions (from the #137 grilling)

  • Tool: Zensical, the successor of Material for MkDocs. Material has been in maintenance mode since 2025-11-05 and its support window ended on 2026-11-05, and MkDocs 2.0 drops the plugin system, so a new project on Material is a dead end. We only need navigation, search, admonitions, code blocks, tabs and dark mode.
  • Sources in handbook/ in the kataba repo (docs/ is taken by ADRs and agent docs), so doc changes land in the same MR as the feature. Python stays out of the Node project: pin Zensical in handbook/requirements.txt, install via uv/pipx.
  • English only for now; keep the structure open for a later translation.
  • Two handbooks in the navigation: User handbook (readers, short; authors, in depth) and Administration handbook (in-app admin + operating an instance). Pages may be stubs here; content follows in the sibling tickets.
  • Hosting: git-pages at https://pages.mike-ochmann.de/kataba/ (the server is already running there; sites live under paths, no wildcard subdomains). Set site_url accordingly.
  • Only the latest release is documented, no version switcher.
  • Deploy is a step in the release skill (~/.claude/skills/release, outside the repo), no Forgejo Action/runner: zensical build --strict (fails the release on broken links) → push the built site to the pages branch → PUT the repo URL to the site URL on git-pages. Find out how this git-pages instance authorizes a publish and document it in the skill.
  • The Forgejo repo's Website field points to the handbook; package.json homepage stays the repo.

Acceptance criteria

  • handbook/ builds with zensical build --strict from a clean checkout, following a short README section on how to preview it locally (zensical serve)
  • Navigation has both handbooks with placeholder pages; kataba logo and accent match the app
  • ADR-0024 records: Zensical in handbook/, hosted on git-pages, published by the release skill, screenshots generated by Playwright and committed (see sibling ticket) — including why (Material end of support, no built-in Forgejo Pages, no runner)
  • Release skill builds and publishes the handbook; first publish is live at https://pages.mike-ochmann.de/kataba/
  • Repo Website field points to the handbook
Part of #137 ## What Set up the handbook site: a Zensical project in `handbook/` with the skeleton of both handbooks, published to git-pages as part of the release. ## Decisions (from the #137 grilling) - **Tool: Zensical**, the successor of Material for MkDocs. Material has been in maintenance mode since 2025-11-05 and its support window ended on 2026-11-05, and MkDocs 2.0 drops the plugin system, so a new project on Material is a dead end. We only need navigation, search, admonitions, code blocks, tabs and dark mode. - **Sources in `handbook/`** in the kataba repo (`docs/` is taken by ADRs and agent docs), so doc changes land in the same MR as the feature. Python stays out of the Node project: pin Zensical in `handbook/requirements.txt`, install via `uv`/`pipx`. - **English only** for now; keep the structure open for a later translation. - **Two handbooks** in the navigation: *User handbook* (readers, short; authors, in depth) and *Administration handbook* (in-app admin + operating an instance). Pages may be stubs here; content follows in the sibling tickets. - **Hosting: git-pages at `https://pages.mike-ochmann.de/kataba/`** (the server is already running there; sites live under paths, no wildcard subdomains). Set `site_url` accordingly. - **Only the latest release is documented**, no version switcher. - **Deploy is a step in the release skill** (`~/.claude/skills/release`, outside the repo), no Forgejo Action/runner: `zensical build --strict` (fails the release on broken links) → push the built site to the `pages` branch → `PUT` the repo URL to the site URL on git-pages. Find out how this git-pages instance authorizes a publish and document it in the skill. - The Forgejo repo's *Website* field points to the handbook; `package.json` `homepage` stays the repo. ## Acceptance criteria - [ ] `handbook/` builds with `zensical build --strict` from a clean checkout, following a short README section on how to preview it locally (`zensical serve`) - [ ] Navigation has both handbooks with placeholder pages; kataba logo and accent match the app - [ ] **ADR-0024** records: Zensical in `handbook/`, hosted on git-pages, published by the release skill, screenshots generated by Playwright and committed (see sibling ticket) — including why (Material end of support, no built-in Forgejo Pages, no runner) - [ ] Release skill builds and publishes the handbook; first publish is live at `https://pages.mike-ochmann.de/kataba/` - [ ] Repo *Website* field points to the handbook
Author
Owner

Done in #143 (merged as 249de57): Zensical handbook skeleton in handbook/ with both handbooks as placeholder pages, kataba logo and accent in light and dark mode, README section on previewing it, ADR-0024, and a handbook step in the release skill (build --strict, pages branch, PUT to git-pages, authorized by the DNS challenge _git-pages-challenge.pages.mike-ochmann.de; token in ~/.config/kataba/pages-token). First publish is live at https://pages.mike-ochmann.de/kataba/ and the repo's Website field points there.

Done in #143 (merged as 249de57): Zensical handbook skeleton in handbook/ with both handbooks as placeholder pages, kataba logo and accent in light and dark mode, README section on previewing it, ADR-0024, and a handbook step in the release skill (build --strict, pages branch, PUT to git-pages, authorized by the DNS challenge _git-pages-challenge.pages.mike-ochmann.de; token in ~/.config/kataba/pages-token). First publish is live at https://pages.mike-ochmann.de/kataba/ and the repo's Website field points there.
miko closed this issue 2026-11-06 11:00:48 +01:00
Sign in to join this conversation.
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
MassiveDynamic/kataba#138
No description provided.