Skip to content

0011 docs and wiki

github-actions[bot] edited this page Nov 17, 2026 · 3 revisions

docs/ is for developers and is mirrored to the wiki

Status: accepted · Implementation: done · Date: 2026-11-17

Built: scripts/wiki.ts and the workflow. First publish 2026-11-17: 15 pages, a sidebar and a footer, identical to the local build. Since ADR 0012 the wiki is published on pushes to dev, not main.

Context

LibreLifts has two kinds of reader. People who want the app need to know what it does; that is the website's job (ADR 0009). People who work on it need the scope, the decisions and how to run it. Those documents live in docs/, reviewed and versioned with the code, but a folder of Markdown files is awkward to browse.

Decision

  • docs/ is developer documentation: the parity plan, the decision records and how to set up and run the project. Material for users goes on the website.
  • docs/ is the only place the docs are edited.
  • The GitHub wiki is a generated mirror of docs/. scripts/wiki.ts turns the folder into wiki pages, with links rewritten, a sidebar, and each record's frontmatter shown as a status line. .github/workflows/wiki.yml publishes it on every push to main that touches the docs.
  • The script fails on a link between docs that doesn't resolve, so publishing is also the link check.

Consequences

  • The docs can be browsed and searched on the wiki, and still change through commits.
  • An edit made on the wiki in the browser is overwritten by the next publish.
  • Wiki commits are made by the GitHub Actions bot in the wiki's own repository. They are not signed and are not part of the project's history.
  • The wiki has to exist before the workflow can push to it: its first page is created by hand, once.

Clone this wiki locally