Organize grouped components and publication policy

Use this guide when one docs estate starts behaving like an ecosystem with many components, artifacts, or publication surfaces that should share defaults.

What to centralize

Keep these concerns in the consumer-owned catalog layer:

  • origins and public base URLs
  • group-level defaults
  • publication path policy
  • per-component or per-artifact publication overrides

That lets component repositories keep owning identity and content roots without owning the final public URL design.

Define a group only for shared public behavior

This group places related components below /platform/ and gives renderers a stable label. Each component supplies only its route segment:

 1sources:
 2  spark:
 3    localDir: components/spark
 4  operator:
 5    localDir: components/operator
 6groups:
 7  streaming:
 8    displayName: Streaming
 9    pathPrefix: /platform/
10    navigationSection: Streaming projects
11components:
12  - slug: spark
13    group: streaming
14    content:
15      source: spark
16    publication:
17      pathSegment: spark
18    artifacts: []
19  - slug: spark-operator
20    group: streaming
21    content:
22      source: operator
23    publication:
24      pathSegment: spark-operator
25    artifacts: []

The resolved component roots are:

1/platform/spark/
2/platform/spark-operator/

data/components.json retains the streaming group identity for navigation or listing templates. data/routes.json remains authoritative for the public paths.

Apply defaults from broad to narrow

Use this order when deciding where a setting belongs:

  1. Put site-wide origin and path-segment defaults in defaults.
  2. Put policy shared only by a real component family in its groups entry.
  3. Put component-specific route choices on the component.
  4. Put independently versioned publication choices on the artifact.

The nearest explicit setting wins, but an override should express a real public difference rather than mirror repository layout.

Validate before adding content

After introducing or changing a group, run:

1site-pipeline check
2site-pipeline build

Inspect the two component entries and their routes before adding aliases, redirects, releases, or mounted content. This makes it easier to identify which inheritance layer created a surprising path.

When to add another group

Add a group when it gives a clearer shared default layer. Do not add groups just to mirror repository layout or organization charts.

Good reasons include a shared public prefix, navigation section, origin, or ordering policy. If components share only ownership or repository location, renderer navigation or source configuration is usually the better place to express that relationship.

Failure cases

  • Two components that resolve to the same path fail route-ownership checks.
  • A component that names an unknown group fails reference validation.
  • A pathSegment must remain one segment; use the group’s pathPrefix for the shared hierarchy.
  • An explicit mountPath can bypass the group prefix, so use it only when that exception is intentional and review the resulting route inventory.

Read this next

For unreleased development contract details: