Inspect staged output and routes

Use this guide after a successful build when you want to understand what the pipeline actually staged and which public routes it resolved.

Start with the manifest

Always read manifest.json first.

For a tiny spark example, the important part looks like this:

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

It is the authoritative entry point for:

  • the top-level staged roots
  • which aggregate data files are present
  • where the route and redirect inventories live for this stage

Use it as a lookup file and contract entry point. Do not treat it as ordinary renderer data. It is the finalized stage marker and may change on each successful stage refresh even when the interesting renderer-facing data files do not.

Then inspect the route surfaces

The most useful next files are usually:

  • the path referenced by manifest.dataFiles.routes
  • the path referenced by manifest.dataFiles.redirects

Use them to answer different questions:

  • routes.json tells you which public routes the stage owns
  • redirects.json tells you which requests should redirect and where they go

One concrete routes.json item looks like this:

 1{
 2  "originKey": "docs",
 3  "baseUrl": "https://docs.example.org",
 4  "path": "/spark/releases/4.0.0/",
 5  "url": "https://docs.example.org/spark/releases/4.0.0/",
 6  "componentSlug": "spark",
 7  "artifactKey": "runtime",
 8  "section": "released",
 9  "routeKind": "context",
10  "targetId": "released:spark:runtime:4.0.0"
11}

section tells you which publication surface the route belongs to. routeKind is the route class, such as published, context, or alias. The separate canonical flag tells you which published route is preferred when more than one route points at the same target.

One concrete redirects.json item looks like this:

1{
2  "fromUrl": "https://docs.example.org/spark/development/docs/",
3  "toUrl": "https://docs.example.org/spark/releases/4.0.0/",
4  "status": 302,
5  "sourceKind": "catalog"
6}

sourceKind tells you why the redirect exists. The built-in staging flow uses values such as catalog for authored publication redirects and withdrawal for withdrawn-release redirects.

Inspect one staged page

Open a staged page under content/ and look for the injected pipeline front matter. Fields such as title outside this namespace came from the authored page. The reserved pipeline namespace is derived during staging and must not be added to the source page:

 1pipeline:
 2  component:
 3    slug: spark
 4  page:
 5    kind: release-page
 6    path: /spark/releases/4.0.0
 7    canonicalUrl: https://docs.example.org/spark/releases/4.0.0/
 8    version:
 9      kind: released
10      label: 4.0.0
11    source:
12      key: runtime
13      path: docs/releases/4.0.0/index.md
14      repository: https://github.com/example/runtime
15      viewRef: main
16      editRef: main

That is the bridge between one page file and the normalized publication model. In particular, source.path is relative to the resolved runtime source binding. It is not the path of the staged copy. A renderer can use the optional repository and refs to build provider-specific source links; it should omit those links when the values are absent.

Then inspect cross-page discovery

content-index.json gives consumers a page inventory they can search without scanning the whole content tree:

 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  "source": {
10    "key": "runtime",
11    "path": "docs/releases/4.0.0/index.md",
12    "repository": "https://github.com/example/runtime",
13    "viewRef": "main",
14    "editRef": "main"
15  },
16  "versionKind": "released",
17  "versionLabel": "4.0.0",
18  "provider": "github"
19}

Keep the contract boundary in mind

The staged tree is the downstream contract. Renderers, deployment adapters, and audit tools should integrate against the stage root instead of reading internal Python objects or arbitrary source repositories.

Useful command-line checks

1cat site/.stage/manifest.json
2cat site/.stage/data/routes.json
3cat site/.stage/data/content-index.json

Typical next steps

  • generate HTTP-server or CDN config from the route and redirect metadata
  • validate that the expected latest, archive, or alias routes exist
  • inspect page front matter under the staged content tree

Read this next