kreeader-docs

What it is

This repository contains the source for four tiered Kreeader PDF guides: User, Publisher, Administrator, and Developer. Each guide is assembled from Markdown chapters, Mermaid diagrams, and real captured screenshots, then built with Pandoc and pdflatex.

Chapter sources live under docs/user, docs/publisher, docs/admin, and docs/developer.

Shared assets, including the Kreeader logo and LaTeX preamble, live in docs/_shared. Each completed guide is written to dist/kreeader-<tier>-guide.pdf.

Build

Build one guide or all four:

./scripts/build.sh <tier>|all

<tier> is user, publisher, admin, or developer.

For each tier, scripts/build.sh renders Mermaid diagrams first, converts the shared SVG logo with rsvg-convert, pulls that tier's live external-include chapters, and invokes Pandoc with pdflatex, a table of contents, and the shared LaTeX preamble. For the Developer Guide, it also runs scripts/render-api-reference.sh to generate the API reference from a kreeader-server checkout.

The build toolchain is pandoc, pdflatex from TeX Live, mermaid-cli, rsvg-convert, Node.js and npm (Widdershins runs through npx), and yq.

Live per-repository documentation pulls

docs/external-includes.yaml declares documentation imported from sibling repositories. At build time, scripts/render-external-docs.sh copies each listed file verbatim from its repository's working tree into a generated appendix chapter for the configured guide tier.

The kreeader-server checkout resolves through SERVER_REPO. Other repository names resolve through REPO_<NAME>, with dashes changed to underscores and the name uppercased. Unset overrides fall back to the corresponding sibling directory.

External includes are only for reference material that is genuinely suitable as an appendix without being rewritten. Do not add material that a tier's own prose already paraphrases; the policy and manifest schema are documented in the comment block at the top of docs/external-includes.yaml.

Regenerating screenshots

Screenshots are captured from a local scratch kreeader-server instance seeded with synthetic demo data — never production. To recapture after a UI change:

./scripts/seed-demo-data.sh
./scripts/capture-screenshots.sh all
./scripts/seed-demo-data.sh stop

Requires a freshly seeded instance; run all in registry order — several flows are one-shot per seed (each depends on state a prior flow in the registry left behind), so running one flow alone or rerunning all against an already-used seed won't reproduce them.

Regenerating diagrams and the API reference

The build runs these generators automatically. They can also be run directly:

./scripts/render-diagrams.sh
./scripts/render-api-reference.sh /path/to/kreeader-server

Continuous integration and release

.forgejo/workflows/build-and-release.yml rebuilds all four guides on every push to master. It refreshes the four PDF assets on one rolling Forgejo release named latest: assets are replaced by name, while the tag is created once and left unchanged. This is a rolling release, not a versioned cut.

A scheduled run executes every Monday at 06:00 as a backstop, keeping the external-include appendix chapters fresh even when kreeader-docs has no new commits. The kreeader-server repository's docs-dispatch.yml workflow also dispatches this build directly for relevant documentation and API changes. workflow_dispatch permits manual runs.

The job runs in the organization's self-hosted, containerized Arch runner. On each run it installs the documentation toolchain: pandoc-cli, the required TeX Live packages, mermaid-cli, librsvg, npm, and yq.

docs/superpowers/ contains the plans and specifications used while writing the guides; it is not published guide content.