What a tiny site looks like

This page shows the smallest concrete example thread used across the user-facing docs.

Repository shape

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

site/catalog.yaml is the consumer-owned entry point. One minimal versioned example looks like this:

 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.*$

The optional site/provider-snapshot.json enriches version metadata without making the renderer talk to providers directly.

Authored page shape

The authored page can stay ordinary Markdown:

1---
2title: Spark 4.0.0 release notes
3---
4
5Hello from the first staged page.

First commands

Run these from the workspace root:

1site-pipeline check
2site-pipeline build

Use check when you want validation without mutating site/.stage/. Use build when you want the content tree and aggregate data written.

What appears after build

1site/.stage/
2  content/spark/releases/4.0.0/index.md
3  data/components.json
4  data/content-index.json
5  data/routes.json
6  data/redirects.json
7  manifest.json

That output is the important boundary:

  • authored files stay in your repos
  • staged files become consumer input for renderers and deployment adapters
  • component-owned staged paths follow the same resolved public hierarchy that the route inventory publishes
  • aggregate JSON files tell downstream tools which public routes, redirects, pages, and metadata the stage owns

What matters at this size

  • stable component identity like spark
  • one clear docs root
  • one publication mount path such as /spark/
  • using manifest.json as the entry point into the stage root

What you can ignore for now

  • grouped components
  • localization and translation linkage
  • compatibility metadata
  • advanced publication planning