From cf291347fc4a7f013150bb8531a89e145317d946 Mon Sep 17 00:00:00 2001 From: draw me an elephant <68925779+drawmeanelephant@users.noreply.github.com> Date: Fri, 28 Aug 2026 10:34:08 -0400 Subject: [PATCH] Portable doc-site guide (#263, reframed) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The old docs.rotkeeper.com domain is abandoned, so the issue is reframed from "auto-generate a dead domain" to "the docs are portable generated output." New home/content/docs/publishing.md documents: - what the pipeline produces (render -> output/, dip -> dip-matrix + book reports, book binders -> bones/book-reports, showcase -> gallery) — the same bytes any workstation generates on a full docs run - that output/ is self-contained static HTML (relative asset links, no JS runtime, no server, no CDN) and publishes as-is to any static host - GitHub Pages as one option among many — it serves identical bytes to a local run, a hosting choice rather than a pipeline - what not to do: commit output/, wire CI to a specific domain, or hand-edit generated artifacts Linked from the docs index under a new "Hosting the Generated Docs" section. Validated: render + status green, no scripts touched. --- home/content/docs/index.md | 3 +++ home/content/docs/publishing.md | 47 +++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+) create mode 100644 home/content/docs/publishing.md diff --git a/home/content/docs/index.md b/home/content/docs/index.md index 621e9b0a..345301e5 100644 --- a/home/content/docs/index.md +++ b/home/content/docs/index.md @@ -77,6 +77,9 @@ The current workflow is deliberately small and local-first: - [Archive Reports](bones/archive/index.html) - [DIP Matrix](dip-matrix.html) +### 5½. 🌐 Hosting the Generated Docs +- [Publishing the Docs](publishing.html) — the docs are portable output; publish the bytes anywhere + ### 6. 🌀 Advanced Flags & Edge Cases - [Rotkeeper Reference](rotkeeper-reference.html) - [Rotkeeper Rituals](rotkeeper-rituals.html) diff --git a/home/content/docs/publishing.md b/home/content/docs/publishing.md new file mode 100644 index 00000000..52d828bf --- /dev/null +++ b/home/content/docs/publishing.md @@ -0,0 +1,47 @@ +--- +title: "Publishing the Docs" +slug: publishing +template: "rotkeeper-doc.html" +version: "1.0" +updated: "2026-08-28" +description: "The docs are portable generated output — the same bytes any workstation produces when the full render + DIP + book pipeline runs. Publish them to any static host." +tags: + - rotkeeper + - docs + - publishing +--- + +# Publishing the Docs + +The docs are not a separate repo, and they no longer have a blessed domain (the old rotkeeper.com is abandoned). The docs are **generated output**: run the same toolchain any workstation runs, get the same site, and publish it to whichever static host you like. Someone who clones Rotkeeper and runs the full pipeline on their machine gets the same bytes you would publish — GitHub Pages, rot.filed.fyi, or a plain rsync target are all just places to put those bytes. + +## What the pipeline produces + +| Command | Artifact | What it is | +| --- | --- | --- | +| `bash rotkeeper.sh render` | `output/` | The whole static site — `docs/` pages, showcase gallery, assets. Self-contained: relative asset links, no JS runtime, no server, no CDN (the DaisyUI prototype vendors its CSS on-prem). | +| `bash rotkeeper.sh dip` | `home/content/docs/dip-matrix.md` (+ book reports) | The documentation-integrity matrix: ownership, stale/obsolete docs, pillars. Shows up in the site on the next `render`. | +| `bash rotkeeper.sh book` (`--docbook`, `--configbook`, `--scriptbook-full`, …) | `bones/book-reports/` | The bound reference set — documentation, configuration, scripts, content retrieval artifacts. | +| `bash rotkeeper.sh showcase` | `home/content/showcase/` → `output/showcase/` | The theme gallery wall, every theme through the same evaluation body. | + +A full docs run on a workstation is: `render` + `dip` + the `book` binders you care about, then `render` again so the DIP matrix lands in the site. Nothing in that chain depends on where the output ends up. + +## Publish the bytes + +`output/` is portable as-is: relative `../assets/` links work at a domain root or a subpath, there is no build step on the host, and no JavaScript is required to read the docs. + +- **Any static host** — copy `output/` (rsync, scp, object storage, a file drop) and point the host at it. +- **A domain you own** — same copy; DNS + static hosting is all it takes. +- **GitHub Pages** — one option among many, not the blessed one: publish `output/` (e.g. an Actions workflow that runs `render` + `dip` and uploads a `gh-pages` branch, or a Pages source directory). The interesting property is that Pages serves *identical bytes* to a local run — it is a hosting choice, not a pipeline. + +The point of the whole arrangement: **anyone who wants the docs runs the toolchain and gets them.** There is no per-host build, no dead-domain CI, and no reason to treat any particular URL as canonical. + +## What not to do + +- Don't commit `output/` to the repo — it's the generated tree; `render` and `scan` treat it as output. +- Don't wire CI to a specific domain — the pipeline produces the site; hosting is downstream of the pipeline, not part of it. +- Don't hand-edit generated docs artifacts (`dip-matrix.md`, `bones/book-reports/`) — regenerate them. + +--- + +*Back to*: [Documentation overview](index.md)