pipeline-navigator

name: pipeline-navigator description: >- Documentation pipeline architecture for f5-sales-demo — where to make changes across docs-theme, docs-builder, docs-control, and docs-icons. Use when deciding which repository to modify, understanding config ownership (astro.config.mjs, content.config.ts), debugging the release dispatch chain, checking managed files, or when a theme/icon change is not appearing on live sites. Also use when the user asks "where should I make this change" or mentions docs-theme, docs-builder, or the build pipeline. user-invocable: false

Documentation Pipeline Navigator

All f5-sales-demo repositories publish docs to GitHub Pages using a shared pipeline.

Repository Roles

Content repositories only need a docs/ directory — the build container and workflow handle everything else. CI builds trigger when files in docs/ change on main.

Where to Make Changes

• Site appearance, navigation, or Astro config — change docs-theme (owns astro.config.mjs, content.config.ts, CSS, fonts, logos, and layout components)
• Build process, Docker image, or npm deps — change docs-builder (owns the Dockerfile, entrypoint, and dependency set)
• Interactive components (placeholder forms, API viewers, Mermaid rendering) — change docs-builder
• Icon packages (Iconify JSON sets, Astro icon components) — change docs-icons (publishes npm packages consumed by docs-builder)
• CI workflow or governance files — change docs-control (syncs managed files and repository settings to downstream repositories)
• Page content and images — change the docs/ directory in the content repository itself
• Never add astro.config.mjs, package.json, or build config to a content repository — the pipeline provides these
• Never create astro.config.mjs, uno.config.ts, or Astro integration config in docs-builder — these are owned exclusively by docs-theme

Configuration Ownership

Read references/config-ownership.md for the full ownership rules including the single-source-of-truth mechanism and the pattern for adding new capabilities.

Release Dispatch Chain

Read references/release-dispatch-chain.md for the 5-step automated chain from theme/icon merge through content site rebuild.

If a theme or icon change does not appear on live sites, check each step in that chain for failures — do not manually trigger github-pages-deploy.yml as a workaround.

Managed Files

Read references/managed-files.md for the full list of files centrally managed by docs-control and automatically synced to all repos. Do not modify managed files in downstream repos — local changes will be overwritten on the next enforcement run.

To change any managed file, open a PR in f5-sales-demo/docs-control instead.

Other Infrastructure Repos

The organization also contains repos with their own CI pipelines that are not part of the docs theme/build dispatch chain but do receive managed files: