Skip to content

0005 docs and wiki

github-actions[bot] edited this page Nov 18, 2026 · 2 revisions

docs/ is for developers and is mirrored to the wiki

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

From LibreLifts ADR 0011. As built, 2026-11-18: scripts/wiki.ts and the workflow exist, and the local build writes 30 pages. The wiki has no first page yet, so nothing has been published and this stays planned. First publish 2026-11-18, when the foundation landed on dev: the wiki already had a first page, and the workflow succeeded.

Context

LibreBars has two kinds of reader. People who want the app need to know what it does; that is the website's job (0025). People who work on it need the decisions, the workflow and how to run it. Those documents are reviewed and versioned with the code, but a folder of Markdown files is awkward to browse.

Decision

  • docs/ is developer documentation: the decision records, the workflow and how to set up and run the project. Text for people who use the product 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 front matter shown as a status line. .github/workflows/wiki.yml publishes it on every push to dev that touches the docs.
  • The script fails on a link between docs that does not resolve, and it is a step of pnpm check, so the link check runs on every pull request.

Consequences

  • The docs can be browsed and searched on the wiki, and still change only 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.

LibreBars

Clone this wiki locally