Staged output and consumers

The staged tree is the durable hand-off point between Site Pipeline and the systems that render, serve, or audit the site.

Start with manifest.json

After site-pipeline build, site/.stage/manifest.json tells downstream tools where the important stage roots and aggregate files live:

 1{
 2  "schemaVersion": 1,
 3  "command": "build",
 4  "roots": {
 5    "content": "content",
 6    "static": "static",
 7    "data": "data"
 8  },
 9  "dataFiles": {
10    "components": "data/components.json",
11    "routes": "data/routes.json",
12    "redirects": "data/redirects.json",
13    "contentIndex": "data/content-index.json"
14  }
15}

If a consumer does not know where to start, manifest.json is the answer.

Use it to discover the stage layout and the aggregate files that exist for that stage. Do not treat it as ordinary renderer data or import it into templates. manifest.json is the hand-off marker for a finalized stage publication, so it may change on every successful build or watch cycle even when the meaningful renderer-facing inputs stay the same.

Staged pages carry pipeline front matter

Site Pipeline preserves authored fields such as title, description, and weight, then adds normalized pipeline metadata that downstream tooling can trust. Authors must not define the reserved pipeline namespace themselves; the build derives it from the effective catalog, provider data, and page context:

 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
12      tag: v4.0.0
13    source:
14      key: runtime
15      path: docs/releases/4.0.0/index.md
16      repository: https://github.com/example/runtime
17      viewRef: main
18      editRef: main

That means a renderer can read one staged page and still know which component, publication surface, provider, version context, and authored source it belongs to. The structured source object gives a repository-aware consumer the data needed to construct view or edit links without pointing users at .stage. See pipeline-enhanced front matter for the ownership boundary and common renderer use cases.

Aggregate files answer cross-page questions

Use aggregate files when you need answers that span more than one page:

  • data/routes.json for public routes
  • data/redirects.json for redirect behavior
  • data/components.json for component-level publication metadata
  • data/content-index.json for page discovery

For example, one content-index.json item looks like this:

 1{
 2  "id": "spark-runtime-4.0.0-index",
 3  "componentSlug": "spark",
 4  "artifactKey": "runtime",
 5  "pageKind": "release-page",
 6  "originKey": "docs",
 7  "path": "/spark/releases/4.0.0",
 8  "url": "https://docs.example.org/spark/releases/4.0.0/",
 9  "canonicalUrl": "https://docs.example.org/spark/releases/4.0.0/",
10  "source": {
11    "key": "runtime",
12    "path": "docs/releases/4.0.0/index.md",
13    "repository": "https://github.com/example/runtime",
14    "viewRef": "main",
15    "editRef": "main"
16  },
17  "versionKind": "released",
18  "versionLabel": "4.0.0",
19  "provider": "github"
20}

What consumers should not do

Downstream systems should not:

  • inspect internal Python objects
  • infer routing directly from repo layout
  • fetch provider state on their own to reconstruct page metadata
  • treat manifest.json as normal renderer data when staged pages and data/*.json already provide the renderer-facing inputs

They should use the staged output instead.