Large sites

This page is for platform-style sites with many modules, sibling projects, or extensions that share publication policy but still need explicit routing, lifecycle, and compatibility behavior.

Who this is for

one platform plus many modules or sibling projects
several active release lines
grouped publication policy and compatibility rules matter

Smallest working shape

At this size, the site is an ecosystem rather than a single product. The key shift is to treat publication defaults, route ownership, compatibility metadata, and provider enrichment as first-class modeled inputs.

One concrete starter layout is:

 1site/
 2  catalog.yaml
 3  provider-snapshot.json
 4components/
 5  spark/
 6    docs/
 7      index.md
 8      releases/
 9        4.0.0/
10          index.md
11  operator/
12    docs/
13      index.md
14      releases/
15        1.2.0/
16          index.md

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  spark:
11    localDir: components/spark
12  operator:
13    localDir: components/operator
14groups:
15  streaming:
16    displayName: Streaming
17    pathPrefix: /platform/
18components:
19  - slug: spark
20    group: streaming
21    content:
22      source: spark
23    publication:
24      pathSegment: spark
25    compatibility:
26      - subjectRef: component:spark
27        targetRef: component:spark-operator
28        relation: testedWith
29        notes: Spark runtime docs assume the matching operator line.
30    artifacts:
31      - key: runtime
32        source: spark
33        versioning:
34          developmentRef: main
35          tagPattern: ^v.*$
36        publicationSelection:
37          development: true
38          releases:
39            mode: latestPerLine
40        lifecycle:
41          releaseLines:
42            - key: "4.0"
43              maintenanceRef: maintenance/4.0
44              latest: "4.0.0"
45          releases:
46            - version: "4.0.0"
47  - slug: spark-operator
48    group: streaming
49    content:
50      source: operator
51    publication:
52      pathSegment: spark-operator
53    artifacts:
54      - key: operator
55        source: operator
56        versioning:
57          developmentRef: main
58          tagPattern: ^operator-v.*$
59        publicationSelection:
60          development: true
61          releases:
62            mode: latestPerLine
63        lifecycle:
64          releaseLines:
65            - key: "1.2"
66              maintenanceRef: maintenance/1.2
67              latest: "1.2.0"
68          releases:
69            - version: "1.2.0"

One representative site/provider-snapshot.json then enriches release state without taking over route ownership:

 1schemaVersion: 1
 2providers:
 3  - key: github
 4    type: githubReleases
 5    fetchedAt: 2026-04-03T00:00:00Z
 6records:
 7  - provider: github
 8    kind: released
 9    componentSlug: spark
10    artifactKey: runtime
11    version: 4.0.0
12    tag: v4.0.0
13  - provider: github
14    kind: released
15    componentSlug: spark-operator
16    artifactKey: operator
17    version: 1.2.0
18    tag: operator-v1.2.0

The first commands are usually:

1site-pipeline check
2site-pipeline build

After build, inspect at least:

1site/.stage/
2  data/components.json
3  data/compatibility.json
4  data/releases.json
5  data/routes.json

For this size band, the important sanity check is that the grouped publication policy is obvious in data/routes.json, while compatibility and provider data show up in their own emitted aggregates instead of being hidden in route hacks.

Read these first

Usually still background material

Only skip localization and provider topics if the site truly does not need them. For many large sites, those topics are already close to the critical path.

Read this next when you grow

Move to very-large.md when the site spans many repositories or product families and needs stronger operational boundaries, localization policy, or very large redirect inventories.