Create a tiny site

Use this guide when you want the smallest useful Site Pipeline setup: one consumer-owned site catalog, one component, and one staged output.

Create the smallest useful tree

Start with this workspace shape:

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

The provider snapshot is optional. Keep it when you want provider-enriched metadata in staged page front matter and aggregate files.

Write the catalog

Create site/catalog.yaml:

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

If you want provider-enriched version metadata in the first build, create site/provider-snapshot.json:

1{
2  "schemaVersion": 1,
3  "providers": [{"key": "github", "type": "githubReleases", "fetchedAt": "2026-04-03T00:00:00Z"}],
4  "records": [
5    {"provider": "github", "kind": "development", "componentSlug": "spark", "artifactKey": "runtime", "ref": "main"},
6    {"provider": "github", "kind": "lineHead", "componentSlug": "spark", "artifactKey": "runtime", "releaseLine": "4.0", "ref": "maintenance/4.0"},
7    {"provider": "github", "kind": "released", "componentSlug": "spark", "artifactKey": "runtime", "version": "4.0.0", "tag": "v4.0.0"}
8  ]
9}

Add one authored page

Create components/runtime/docs/releases/4.0.0/index.md:

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

Validate and build

Run these from the workspace root:

1site-pipeline check
2site-pipeline build

Those defaults assume the catalog lives at site/catalog.yaml. If your site catalog is in a different repository or you invoke the CLI from outside the workspace root, pass both paths explicitly:

1site-pipeline check --workspace-root /workspace --catalog /workspace/buildish/site/catalog.yaml
2site-pipeline build --workspace-root /workspace --catalog /workspace/buildish/site/catalog.yaml

With that split, authored relative paths from the catalog still resolve from --workspace-root, while .stage, .site-pipeline-work, and the default provider snapshot stay next to the selected catalog file.

If you want a machine-readable build report for automation, use:

1site-pipeline build --report-format json --report-schema-version 1

What to decide early

Even for a tiny site, decide these explicitly:

  • the stable component identity
  • which content roots belong to the component repository
  • which content belongs to the consumer-owned site layer instead

That keeps component identity separate from future publication layout changes.

Inspect the first successful result

After build, inspect these paths first:

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

One staged page now carries normalized pipeline metadata in its front matter:

 1pipeline:
 2  component:
 3    slug: spark
 4  page:
 5    kind: release-page
 6    path: /spark/releases/4.0.0
 7    provider:
 8      key: github
 9    version:
10      kind: released
11      label: 4.0.0

What success looks like

You are in a good starting state when:

  • the pipeline produces one coherent stage root
  • manifest.json is present and readable
  • staged pages and assets are separated from source layout details
  • a renderer can consume the stage root without reading repositories directly

Read this next