docs: restructure into Write, Configure, Deploy, Templates and Internals

.github/workflows/e2e.yml

@@ -1,6 +1,6 @@
 name: e2e
 
-# Tier 3: Playwright against the seeded dev stack (docs/development.md).
+# Tier 3: Playwright against the seeded dev stack (docs/internals/development.md).
 # Always on main and on demand; on pull requests only where the change can
 # affect the browser flow.
 on:

README.md

@@ -28,8 +28,8 @@ Collection; a Document author fills structured fields in a leading
 - **injector**: a small reverse proxy in front of Outline that adds a
   "Download PDF" button without forking Outline.
 
-See [CONTEXT.md](CONTEXT.md) for the vocabulary and
-[docs/adr](docs/adr) for architecture decisions.
+See the [vocabulary](CONTEXT.md) and the
+[architecture decision records](docs/adr/README.md).
 
 ## Quick start
 
@@ -44,14 +44,15 @@ task e2e:run # optional: the browser tests against that stack
 ```
 
 The log-in, the seed data and what to click are described in
-[docs/development.md](docs/development.md). To try only the renderer, see
+[Development stack and end-to-end tests](docs/internals/development.md). To try only the renderer, see
 "Development" below.
 
 ## Documentation
 
-Start at the index, [docs/README.md](docs/README.md). Template authors begin
-with the [Template author guide](docs/template-author-guide.md). The research
-behind the design is in [docs/research](docs/research/README.md).
+The docs are at <https://outprint.task.media> and in [docs/](docs/README.md), in
+five sections: Write, Configure, Deploy, Templates and Internals. Template authors
+begin with the [Template author guide](docs/templates/template-author-guide.md). The research
+behind the design is in the [research notes](docs/research/README.md).
 
 ## Status
 
@@ -76,7 +77,7 @@ task e2e:run         # tier 3: browser tests against that stack
 ```
 
 The local stack, its login, the seeding and the end-to-end tests are described
-in [docs/development.md](docs/development.md).
+in [Development stack and end-to-end tests](docs/internals/development.md).
 
 Render a letter with the shipped Template and Configuration:
 
@@ -97,31 +98,30 @@ docker run --rm outprint validate                  # the packages shipped in the
 outprint validate --templates-root ./templates --configs-root ./configurations
 ```
 
-See [docs/metadata.md](docs/metadata.md) for the Metadata Block authors write
-(syntax, layering, field types, errors),
-[docs/packages.md](docs/packages.md) for the package format, field types,
-typed patterns, the TeX deny-list, the drift guard and `validate`, and
-[docs/standard-fields.md](docs/standard-fields.md) for the Standard Fields.
-See [docs/images.md](docs/images.md) for images: formats, sizes, captions,
-limits, error kinds and the `imageHosts` setting.
-See [docs/binding.md](docs/binding.md) for the `binding:` block a
-Collection admin uses to choose the Template and Configuration.
-See [docs/worker.md](docs/worker.md) for the Worker pipeline: phases, filters,
-engine lockdown, errors, logging and the debug switch.
-See [docs/architecture.md](docs/architecture.md) for the Gateway and Worker
-roles, the job bundle, the request flow and the error mapping, and
-[docs/deploy-compose.md](docs/deploy-compose.md) for running both with Docker
-Compose and the Worker security baseline.
-See [docs/injector.md](docs/injector.md) for the injector, the download button,
-compression and CSP handling, routing and the security notes.
-See [docs/security.md](docs/security.md) for the security layers, what each
-proves, the limits and how to run the suite, and
-[docs/testing.md](docs/testing.md) for the test tiers and the CI schedule.
-See [docs/limits.md](docs/limits.md) for the limits and admission control
-(slots, queue, per-user limit, and how to configure them).
-See [docs/sanitize.md](docs/sanitize.md) for the sanitisation gate and the
-pre-publish audit, and [docs/publishing.md](docs/publishing.md) for the
-maintainer's checklist.
+The reference for each part is in the docs: the [Metadata Block reference](docs/templates/metadata-reference.md),
+[Packages](docs/templates/packages.md) (format, field types, typed patterns,
+the TeX deny-list, the drift guard and `validate`) and
+[Standard Fields](docs/templates/standard-fields.md); [Images in the pipeline](docs/internals/images.md);
+[Choose a Template and Configuration](docs/configure/choose-a-template.md) for the
+`binding:` block of a Collection admin; the [Worker pipeline](docs/internals/worker.md);
+[Architecture](docs/internals/architecture.md); [Docker Compose](docs/deploy/docker-compose.md)
+with the Worker security baseline; the [Injector and download button](docs/deploy/injector.md);
+[Security](docs/internals/security.md) and [Testing](docs/testing.md) for the test tiers
+and the CI schedule; [Limits and admission control](docs/deploy/limits-and-admission.md);
+and, for the maintainer, the [Sanitisation gate](docs/sanitize.md) and the
+[Publishing checklist](docs/publishing.md).
+
+### Documentation site
+
+The pages in `docs/` are also published as a site (`website/`, Docusaurus).
+
+```sh
+task docs:build              # strict build of the site (broken links fail)
+task docs:catalogue          # regenerate the Template catalogue pages from the packages
+task docs:catalogue-check    # fail if the generated catalogue pages are out of date
+task docs:catalogue-preview  # re-render the catalogue preview images (needs Docker)
+task docs:errors-check       # fail if the error catalogue and the source codes differ
+```
 
 ## License
 

THIRD_PARTY_NOTICES

@@ -218,9 +218,9 @@ and similar licences; each is listed with its licence in the image.
   file, fontconfig resolved the generic families `sans-serif`, `serif`,
   `monospace` to TeX Gyre Adventor and `Helvetica` to TeX Gyre Heros, so SVG
   text is drawn with TeX Gyre fonts of section 5.2, unless the SVG's font name
-  matches an installed font (see docs/images.md). No proprietary font is
+  matches an installed font (see docs/internals/images.md). No proprietary font is
   shipped. Do not add fonts to Templates or Configurations unless their licence
-  allows redistribution; see docs/template-author-guide.md.
+  allows redistribution; see docs/templates/template-author-guide.md.
 
 
 6. Go dependencies
@@ -261,15 +261,15 @@ modules were checked by hand.)
 
 The browser test suite (e2e/package.json) uses @playwright/test, pdfjs-dist,
 typescript and @types/node as development dependencies. They are installed
-from npm by `make e2e-install`, are not part of any image or release, and are
+from npm by `task e2e:install`, are not part of any image or release, and are
 licensed under Apache-2.0 (Playwright, pdf.js, TypeScript) and MIT
 (@types/node), as their packages state; not re-verified in this run.
 
 
 7. Development and end-to-end test stack (not distributed)
 ----------------------------------------------------------
 
-`make dev` and `make e2e` start these images from public registries on the
+`task dev` and `task e2e:run` start these images from public registries on the
 developer's or the CI machine, from deploy/dev/versions.env. This repository
 contains only configuration files for them. They are separate containers that
 talk to our code over HTTP and OIDC. They are not copied into, built into or

Taskfile.yml

@@ -98,7 +98,7 @@ tasks:
         if: '! command -v node >/dev/null 2>&1'
 
   screenshots:
-    desc: Regenerate the documentation screenshots (needs `task dev`; see docs/development.md)
+    desc: Regenerate the documentation screenshots (needs `task dev`; see docs/internals/development.md)
     cmds:
       - task: e2e:screenshots
 
@@ -151,7 +151,7 @@ tasks:
     desc: Security layers 2 and 3 (needs a Docker daemon)
     summary: |
       The Worker image run with the flags of the shipped Compose file against
-      a hostile pipeline (docs/security.md). The "sandbox" image stage holds
+      a hostile pipeline (docs/internals/security.md). The "sandbox" image stage holds
       the test-only probe; the release image must not, and the suite checks
       that. The log is always shown before the skip guard runs.
     cmds:

cmd/sandbox-probe/main.go

@@ -1,7 +1,7 @@
 //go:build linux
 
 // Command sandbox-probe is the test-only adversary of the sandbox security
-// suite (docs/security.md, layers 2 and 3). It runs hostile actions as the
+// suite (docs/internals/security.md, layers 2 and 3). It runs hostile actions as the
 // Worker user, inside the container flags the shipped Compose file sets, and
 // reports what was contained. It is built into the "sandbox" image stage
 // only; the release image must not contain it.

cmd/seed/main.go

@@ -1,6 +1,6 @@
 // Command seed provisions the development stack: the fictional user, a bound
 // and an unbound Collection, each with a Document. `task dev` and `task e2e:run`
-// both run it. See docs/development.md.
+// both run it. See docs/internals/development.md.
 package main
 
 import (

config/service.yaml

@@ -16,11 +16,11 @@ defaultBinding:
 # Hosts besides the Outline origin that an image redirect may lead to, for
 # example the file storage behind Outline's attachments. Empty by default:
 # only the Outline origin is allowed. A host name matches ports 80 and 443;
-# write host:port for another port. See docs/images.md.
+# write host:port for another port. See docs/deploy/image-fetching.md.
 # imageHosts:
 #   - files.example.invalid
 
-# Admission control of the Gateway (docs/limits.md). One Worker runs one job,
+# Admission control of the Gateway (docs/deploy/limits-and-admission.md). One Worker runs one job,
 # so keep slots equal to the number of Worker replicas. Every key is optional;
 # the values below are the defaults. Environment variables override the file:
 # OUTPRINT_ADMISSION_SLOTS, _QUEUE_DEPTH, _PER_USER and _MAX_WAIT.

deploy/compose/compose.yaml

@@ -1,10 +1,10 @@
-# Gateway and Worker from one image (docs/deploy-compose.md, ADR 0001).
+# Gateway and Worker from one image (docs/deploy/docker-compose.md, ADR 0001).
 #
 #   OUTLINE_URL=https://wiki.example.test docker compose \
 #     -f deploy/compose/compose.yaml up --build
 #
 # The worker service block is the shipped Worker baseline. Security tests
-# read it (see docs/deploy-compose.md): weaken it and the build breaks.
+# read it (see docs/deploy/docker-compose.md): weaken it and the build breaks.
 
 name: outprint
 
@@ -70,7 +70,7 @@ services:
       # Required: the base URL of your Outline. The gateway refuses to start
       # without it.
       OUTLINE_URL: ${OUTLINE_URL:-}
-      # Admission control (docs/limits.md). Empty keeps the service
+      # Admission control (docs/deploy/limits-and-admission.md). Empty keeps the service
       # configuration's value. Scale the slots with the Worker replicas.
       OUTPRINT_ADMISSION_SLOTS: ${OUTPRINT_ADMISSION_SLOTS:-}
       OUTPRINT_ADMISSION_QUEUE_DEPTH: ${OUTPRINT_ADMISSION_QUEUE_DEPTH:-}
@@ -102,7 +102,7 @@ services:
       retries: 3
       start_period: 5s
 
-  # The injector sits in front of Outline (docs/injector.md). It is a
+  # The injector sits in front of Outline (docs/deploy/injector.md). It is a
   # separate, slim image without the TeX toolchain and is not part of the
   # Worker baseline.
   injector:

deploy/dev/Taskfile.yml

@@ -1,6 +1,6 @@
 # https://taskfile.dev
 #
-# Development stack (docs/development.md): Outline with login, the injector,
+# Development stack (docs/internals/development.md): Outline with login, the injector,
 # Gateway and Worker, seeded with a fictional user, a bound and an unbound
 # Collection. DEV ONLY. Included by the root Taskfile as `dev:`; tasks run in
 # the repository root.

deploy/dev/compose.yaml

@@ -23,7 +23,7 @@ x-outline-env: &outline-env
   FILE_STORAGE: local
   FILE_STORAGE_UPLOAD_MAX_SIZE: "26214400"
   # Sign-in with the dev Dex. The browser is sent to localhost:5556; Outline
-  # itself reaches Dex by its compose name. See docs/development.md.
+  # itself reaches Dex by its compose name. See docs/internals/development.md.
   OIDC_CLIENT_ID: outline
   OIDC_AUTH_URI: http://localhost:5556/dex/auth
   OIDC_TOKEN_URI: http://dex:5556/dex/token
@@ -66,7 +66,7 @@ services:
         target: /etc/dex/config.yaml
         read_only: true
     ports:
-      # The browser signs in here; see docs/development.md.
+      # The browser signs in here; see docs/internals/development.md.
       - "127.0.0.1:5556:5556"
     networks: [frontend]
     healthcheck:
@@ -102,7 +102,7 @@ services:
     environment:
       OUTLINE_URL: http://outline:3000
       # Outline names itself http://localhost:8090 in the redirect to a
-      # stored file; the Gateway fetches that from OUTLINE_URL (docs/images.md).
+      # stored file; the Gateway fetches that from OUTLINE_URL (docs/deploy/image-fetching.md).
       OUTLINE_PUBLIC_URL: http://localhost:8090
       OUTPRINT_SERVICE_CONFIG: /opt/outprint/service-dev.yaml
     volumes:

docs/README.md

@@ -1,42 +1,26 @@
-# Documentation
+# Outprint documentation
 
-## Using and running it
+Outprint turns Outline documents into typeset PDFs. Pick the section that fits
+your job. The same files make up the [documentation site](https://outprint.task.media).
 
-| Page | What it covers |
-|------|----------------|
-| [Metadata](metadata.md) | the Metadata Block a Document author writes: syntax, layering, field types, errors |
-| [Binding](binding.md) | the block a Collection admin uses to choose a Template and Configuration |
-| [Images](images.md) | images and logos: formats, sizes, captions, limits, errors |
-| [Deploying with Docker Compose](deploy-compose.md) | running Gateway and Worker with Docker Compose |
-| [Injector and download button](injector.md) | the reverse proxy that adds the Download PDF button |
-| [Limits and admission control](limits.md) | limits and admission control |
-
-## Writing Templates
+| Section | For | What you find |
+|---------|-----|---------------|
+| [Write](write/README.md) | people who write documents in Outline | download a PDF, fill in the details at the top of a document, add images, fix a message |
+| [Configure](configure/README.md) | admins of a Collection | choose a Template and a Configuration for a Collection |
+| [Deploy](deploy/README.md) | people who run Outline | prerequisites, Docker Compose, the injector, limits, security notes, upgrading |
+| [Templates](templates/README.md) | people who make Templates | the catalogue, the author guide, the package format, the Standard Fields |
+| [Internals](internals/README.md) | reviewers and contributors | architecture, the Worker, images, security, the local stack, decision records |
 
-| Page | What it covers |
-|------|----------------|
-| [Template author guide](template-author-guide.md) | start here: package format, fields, patterns, deny-list, `validate`, `render`, goldens, a worked example |
-| [Packages](packages.md) | reference for packages, field types, typed patterns, TeX deny-list, drift guard |
-| [Standard Fields](standard-fields.md) | the Standard Fields |
-
-## How it works
-
-| Page | What it covers |
-|------|----------------|
-| [Architecture](architecture.md) | Gateway and Worker roles, the job bundle, request flow, error mapping |
-| [Worker pipeline](worker.md) | the Worker pipeline, filters, engine lockdown |
-| [Security](security.md) | the security layers and what each proves |
-| [Architecture decision records](adr/README.md) | architecture decision records |
-| [Vocabulary](https://github.com/taskmedia/outprint/blob/main/CONTEXT.md) | the vocabulary |
+## Only on GitHub
 
-## Developing and publishing
+These pages are for the maintainers and are not part of the site.
 
 | Page | What it covers |
 |------|----------------|
-| [Development stack and end-to-end tests](development.md) | the seeded local stack with Outline |
-| [Testing](https://github.com/taskmedia/outprint/blob/main/docs/testing.md) | test tiers and CI |
-| [Sanitisation gate](https://github.com/taskmedia/outprint/blob/main/docs/sanitize.md) | the sanitisation gate and the pre-publish audit |
-| [Publishing checklist](https://github.com/taskmedia/outprint/blob/main/docs/publishing.md) | the maintainer's checklist before the repository goes public |
-| [Releasing](https://github.com/taskmedia/outprint/blob/main/docs/releasing.md) | the maintainer's release procedure: release PR, image publishing, one-time settings |
-| [Research notes](https://github.com/taskmedia/outprint/blob/main/docs/research/README.md) | the research notes behind the design |
-| [Third-party notices](https://github.com/taskmedia/outprint/blob/main/THIRD_PARTY_NOTICES) | third-party licences and the Pandoc source offer |
+| [Testing](testing.md) | test tiers and CI |
+| [Sanitisation gate](sanitize.md) | the sanitisation gate and the pre-publish audit |
+| [Publishing checklist](publishing.md) | the checklist before the repository goes public |
+| [Releasing](releasing.md) | the release procedure: release PR, image publishing, one-time settings |
+| [Research notes](research/README.md) | the research behind the design |
+| [Vocabulary](../CONTEXT.md) | the words with a fixed meaning |
+| [Third-party notices](../THIRD_PARTY_NOTICES) | third-party licences and the Pandoc source offer |