Skip to content

docs: restructure into Write, Configure, Deploy, Templates and Internals - #68

Merged
fty4 merged 2 commits into
mainfrom
feat/52-docs-content-restructure-2
Nov 1, 2026
Merged

fty4 merged 2 commits into
mainfrom
feat/52-docs-content-restructure-2

Conversation

@fty4

@fty4 fty4 commented Nov 1, 2026

Copy link
Copy Markdown
Member

Part of #52 (work package 5: content restructure). Closes nothing; #52 stays open for work packages 8 and 9 and the docs snapshot step.

What changes

docs/ is reorganised into five sections, each with an intro page and a _category_.json:

Section For Pages
Write document authors, non-technical Download a PDF, Fill in the document, Images and logos, When something goes wrong (error catalogue), Limits you may hit
Configure Collection admins Choose a Template and Configuration
Deploy operators Prerequisites first (own Outline only; the injector is required, with the edge -> injector -> Outline picture), Docker Compose, Injector, Image fetching, Limits, Security notes, Upgrading; coming soon: Helm/Kubernetes (#51), reverse-proxy recipes, Podman
Templates template authors Author guide, Packages, Standard Fields, Metadata reference, and a generated Catalogue (neutral)
Internals the curious Architecture, Worker pipeline, Images, Security, Development, ADRs
  • Home page: designed landing in website/src/pages/index.js (numbered list of the five sections, one line each), five sections in the navbar. docs/README.md stays a plain table for GitHub and is excluded from the site.
  • Error catalogue: 46 codes, one permanent ### \code` anchor each (#no_binding, #busy, #user_limit, ...). scripts/docs-error-codes.sh check` compares the codes in the source with the entries on the page (46 and 46).
  • Template catalogue: scripts/docs-catalogue/ (Go, reuses the product's package loader and metadata resolver, so every block shown passed the real checks) generates the pages from the template packages. Tasks docs:catalogue, docs:catalogue-check, docs:catalogue-preview, docs:errors-check. The preview image docs/assets/screens/template-neutral.png is rendered with the real pipeline and committed.
  • The Outline UI screenshots from feat: generate documentation screenshots from the dev stack #66 are used on the Write pages.
  • Stale paths updated: README, THIRD_PARTY_NOTICES, code comments and tests that named moved pages (only references to docs paths were touched outside docs/).

Not done

  • CI does not yet run docs:catalogue-check and docs:errors-check. Adding them is a workflow change (work package 8).
  • package-lock.json in the repo root still has the name outline-latex-pdf (from the logo kit); not part of this PR.
  • The Write pages name a few internal phase names (gateway, worker, tex) where the real error messages contain them.

Test plan

  • strict site build passes; images under the excluded assets/** are bundled
  • none of 2095 links in the built HTML has link text ending in .md
  • error codes: 46 in the source, 46 on the page
  • docs:catalogue-check clean; the metadata blocks on the Write pages pass the real resolver
  • task sanitize, task test, task test-guard
  • served locally: home, the five sections, catalogue, /adr/, a coming-soon page and the error anchors return 200; light and dark screenshots checked
  • CI

@fty4
fty4 merged commit e92f954 into main Nov 1, 2026
14 checks passed
@fty4
fty4 deleted the feat/52-docs-content-restructure-2 branch November 1, 2026 16:32
@fty4 fty4 mentioned this pull request Nov 1, 2026
2 of 3 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant