Medium sites

This page is for product families with multiple visible publication surfaces, common generated or imported docs, and a real planning/materialization step.

Who this is for

  • one product plus tools or subprojects
  • multiple visible versions or lifecycle states
  • imported docs, generated refs, or mounted content are common

Smallest working shape

At this size, the pipeline is no longer just a file copier. It is a boundary between publication policy, local materialized inputs, and stable staged output.

One concrete starter layout is:

 1site/
 2  catalog.yaml
 3  provider-snapshot.json
 4components/
 5  runtime/
 6    docs/
 7      runtime/
 8        guide/
 9          index.md
10        releases/
11          4.0.0/
12            guide/
13              index.md
14  api/
15    docs/
16      reference/
17        index.md
18      releases/
19        4.0.0/
20          reference/
21            index.md

You will usually need to think about:

  • components versus artifacts
  • shared defaults across related publication surfaces
  • planning which contexts should exist before staging starts
  • lifecycle and publication state in addition to plain route layout

One representative site/catalog.yaml looks like this:

 1schemaVersion: 1
 2defaults:
 3  docsRoot: docs
 4  publication:
 5    origin: docs
 6origins:
 7  docs:
 8    baseUrl: https://docs.example.org
 9sources:
10  runtime:
11    localDir: components/runtime
12  api:
13    localDir: components/api
14components:
15  - slug: spark
16    content:
17      source: runtime
18    publication:
19      mountPath: /spark/
20    artifacts:
21      - key: runtime
22        source: runtime
23        docsRoot: docs/runtime
24        versioning:
25          developmentRef: main
26          tagPattern: ^v.*$
27        publicationSelection:
28          development: true
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"
38      - key: api
39        source: api
40        docsRoot: docs
41        versioning:
42          developmentRef: main
43          tagPattern: ^api-v.*$
44        publicationSelection:
45          development: true
46          releases:
47            mode: latestPerLine
48        lifecycle:
49          releaseLines:
50            - key: "4.0"
51              maintenanceRef: maintenance/4.0
52              latest: "4.0.0"
53          releases:
54            - version: "4.0.0"

That is the smallest useful medium-site packet because it already makes three important things explicit:

  • one public component route can carry several independently versioned artifacts
  • provider-snapshot.json tells planning which development and release contexts actually exist before staging starts
  • staged output is something you inspect directly, not something you infer from the source tree alone

The first commands are usually:

1site-pipeline plan
2site-pipeline check
3site-pipeline build

After build, inspect at least:

1site/.stage/
2  content/spark/development/guide/index.md
3  content/spark/development/reference/index.md
4  content/spark/releases/4.0.0/guide/index.md
5  content/spark/releases/4.0.0/reference/index.md
6  data/content-index.json
7  data/routes.json

Read these first

  1. ../how-to/plan-publication-and-materialization.md
  2. ../how-to/model-versioning-and-redirects.md
  3. ../architecture/source-resolution-and-materialization.md

Ignore for now

You can still often postpone:

  • cross-component compatibility relationships
  • provider snapshot integration if authored metadata is enough
  • localization and translation linkage

Read this next when you grow

Move to large.md when you need grouped components, strong compatibility relationships, or provider-enriched publication state across a larger ecosystem.

Deeper reference trail