Tiny sites

This page is for sites with one component, one main docs tree, and only a small amount of lifecycle or routing complexity.

Who this is for

  • one component repository
  • one primary docs tree
  • little or no version-history surface

Smallest working shape

Start with one consumer-owned catalog, one component source tree, and one staged output produced by site-pipeline build.

The smallest useful concrete shape is:

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

The smallest useful mental model is still simple:

  • site/catalog.yaml tells the pipeline which content participates
  • component source trees hold the authored docs that participate
  • the pipeline stages content into a stable output tree for a renderer or other downstream consumer

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  runtime:
11    localDir: components/runtime
12components:
13  - slug: spark
14    content:
15      source: runtime
16    publication:
17      mountPath: /spark/

The first commands are:

1site-pipeline check
2site-pipeline build

Those examples assume you run from the workspace root and keep the catalog at site/catalog.yaml. If you run from somewhere else or keep the catalog in a different repository, pass both selection flags explicitly, for example:

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

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

After build, expect at least:

1site/.stage/
2  content/
3  data/
4  manifest.json

Read these first

  1. ../concepts/tiny-site-shape.md
  2. ../concepts/staged-output-and-consumers.md
  3. ../how-to/create-a-tiny-site.md
  4. ../how-to/inspect-staged-output-and-routes.md
  5. staged output contract

Ignore for now

You can usually ignore these until the site grows:

  • provider snapshots as a required dependency, even if you later use them as an optional enrichment input
  • grouped components
  • compatibility metadata
  • localization and translation linkage
  • advanced publication selection and materialization strategy

Read this next when you grow

Move to small.md when the site adds stable version navigation, redirects, or one mounted imported/generated docs subtree.

Deeper reference trail