Small sites

This page is for one main product with a small visible release history and maybe one mounted API, generated reference tree, or imported docs subtree.

Who this is for

  • one product with a few visible versions
  • simple latest-release/development/archive routing
  • maybe one mounted subtree for generated or imported docs

Smallest working shape

Keep one component and one independently versioned artifact in focus, but make the development, maintenance-line, and released contexts explicit. A small versioned workspace can look like this:

 1site/
 2  catalog.yaml
 3  provider-snapshot.json
 4components/
 5  runtime/
 6    docs/
 7      index.md
 8      maintenance/
 9        4.0/
10          index.md
11      releases/
12        4.0.0/
13          index.md

The catalog owns the public route policy and which contexts are selected:

 1schemaVersion: 1
 2defaults:
 3  docsRoot: docs
 4  publication:
 5    origin: docs
 6site: {}
 7origins:
 8  docs:
 9    baseUrl: https://docs.example.org
10sources:
11  runtime:
12    localDir: components/runtime
13components:
14  - slug: spark
15    content:
16      source: runtime
17    publication:
18      mountPath: /spark/
19    artifacts:
20      - key: runtime
21        source: runtime
22        versioning:
23          developmentRef: main
24          tagPattern: ^v.*$
25        publicationSelection:
26          development: true
27          lineHeads:
28            mode: allAuthored
29          releases:
30            mode: latestPerLine
31        lifecycle:
32          releaseLines:
33            - key: "4.0"
34              maintenanceRef: maintenance/4.0
35              latest: "4.0.0"
36          releases:
37            - version: "4.0.0"

The provider snapshot must contain matching records for the selected contexts. It enriches the authored identities; it does not choose the public paths:

 1{
 2  "schemaVersion": 1,
 3  "providers": [
 4    {
 5      "key": "github",
 6      "type": "githubReleases",
 7      "fetchedAt": "2026-04-03T00:00:00Z"
 8    }
 9  ],
10  "records": [
11    {
12      "provider": "github",
13      "kind": "development",
14      "componentSlug": "spark",
15      "artifactKey": "runtime",
16      "ref": "main"
17    },
18    {
19      "provider": "github",
20      "kind": "lineHead",
21      "componentSlug": "spark",
22      "artifactKey": "runtime",
23      "releaseLine": "4.0",
24      "ref": "maintenance/4.0"
25    },
26    {
27      "provider": "github",
28      "kind": "released",
29      "componentSlug": "spark",
30      "artifactKey": "runtime",
31      "version": "4.0.0",
32      "tag": "v4.0.0"
33    }
34  ]
35}

Run:

1site-pipeline check
2site-pipeline build

Inspect the result

The staged route inventory should include these target/path pairs:

1development:spark:runtime       /spark/development/
2line-head:spark:runtime:4.0     /spark/development/4.0/
3released:spark:runtime:4.0.0    /spark/releases/4.0.0/

The matching pages should appear below site/.stage/content/spark/, while data/routes.json, data/releases.json, and data/refs.json provide the cross-page views. Add aliases or redirects in the publication policy only when another public path must resolve to one of these targets.

Common failures

  • A selected context without a matching provider record cannot be staged.
  • A release record whose component, artifact, version, ref, or tag disagrees with the authored lifecycle fails validation.
  • Two components or contexts that claim the same public route cause a collision.
  • A redirect to an unselected typed target cannot be resolved.

Read these first

  1. Model versioning and redirects
  2. Inspect staged output and routes
  3. Create HTTP server configuration

Ignore for now

Most small sites can defer:

  • grouped components and group-level defaults
  • translation linkage and localization
  • advanced compatibility metadata

Read this next when you grow

Move to Medium sites when the site has multiple artifacts, imported or generated docs become normal, or publication planning and materialization become a regular step in the workflow.

Deeper unreleased development reference

These contracts describe unreleased development behavior and have not yet been published as release documentation.