Skip to content

site: eliminate docs duplication with build-time sync#385

Merged
mchmarny merged 24 commits intomainfrom
docs/single-source-site
Mar 13, 2026
Merged

site: eliminate docs duplication with build-time sync#385
mchmarny merged 24 commits intomainfrom
docs/single-source-site

Conversation

@tabern
Copy link
Copy Markdown
Contributor

@tabern tabern commented Mar 12, 2026

Summary

  • Single source of truth: docs/ is now the only place to edit documentation. site/docs/ content is generated at build time by tools/sync-site-docs.
  • CI guard: tools/check-docs-sidebar (wired into make lint) fails if any doc file is missing from the VitePress sidebar config — no more forgotten pages.
  • 3 missing pages added: Component Catalog, Validator Extension, Validator Development were in the repo but missing from the site sidebar.
  • 27 duplicated files deleted from site/docs/ (now gitignored, generated at build time).
  • Fixed stale Makefile: site-serve/site-build updated from Hugo to VitePress.

How it works

  1. Author edits docs/**/*.md (works on GitHub + site)
  2. tools/sync-site-docs copies docs → site/docs/ (runs automatically via npm predev/prebuild hooks)
  3. VitePress builds from site/ as usual
  4. make lint checks every doc has a sidebar entry

Test plan

  • npx vitepress build passes with zero dead links
  • tools/check-docs-sidebar passes (all docs in sidebar)
  • tools/check-docs-sidebar fails when a new doc is added without sidebar entry
  • Local dev server renders all pages correctly
  • Verify make lint passes in CI

tabern and others added 20 commits March 11, 2026 13:10
Restructure README to lead with what the project does, add quick start
showing full workflow (snapshot/recipe/validate/bundle), supported
environments, components table, and contributing guidance aligned with
launch materials.
Add docs/user/component-catalog.md listing every component that can
appear in a recipe, with descriptions and upstream links. References
recipes/registry.yaml as the source of truth. Linked from README and
user docs index.
- Update Go version from 1.25 to 1.26 in installation guide,
  contributor data docs, and copilot instructions
- Update golangci-lint version from v2.6/v2.9 to v2.10.1
- Expand API reference bundler list from 6 to all 18 registry
  components, reference registry.yaml as source of truth
- Fix Python and JavaScript API examples to send recipe as request
  body with bundlers as query params (matching curl examples and
  endpoint spec)
- Fix kubernetes-deployment.md claiming API server cannot generate
  bundles (it can via POST /v1/bundle)
- Replace hardcoded bundler list in copilot instructions with
  reference to registry.yaml
- Fix kubernetes-deployment.md agent Job example to show privileged
  mode (the default) instead of PSS-restricted mode. Add note about
  --privileged=false for restricted namespaces. Resolves contradiction
  with agent-deployment.md.
- Remove internal "v2" versioning from ROADMAP.md. External users have
  no context for v1 (internal playbooks) and the release version is
  0.10.x.
- Rename "Cluster Agent" to "Snapshot Agent" in README and correct
  description to reflect actual behavior (Job-based snapshot, not
  continuous monitoring)
- Replace broken kubectl apply -k deploy/aicrd with reference to
  full manifest (deploy/aicrd directory does not exist)
- Fix dead links to pkg/validator/checks/README.md in CONTRIBUTING.md
  and DEVELOPMENT.md — point to docs/contributor/validator.md instead
- Remove reference to nonexistent docs/monitoring/grafana-dashboard.json
Add AICR pipeline infographic showing the full workflow from ingest
through recipe generation, bundling, deployment, and validation.
Replaces the ASCII art diagram in the How It Works section.
- Restore skyhook-customizations, dynamo-crds, dynamo-platform, and
  kgateway-crds to component catalog to match all 18 entries in
  recipes/registry.yaml
- Fix typo: "include" → "included" in component-catalog.md
- Remove trailing whitespace in README.md
- Clarify kubectl apply comment to reference manifest section below
Replace Hugo/Docsy documentation site with VitePress. Content is
unchanged — all 38 markdown docs migrated as-is.

- Remove Hugo config, Go modules, Docsy theme, SCSS assets
- Add VitePress config with sidebar nav, local search, mermaid plugin
- Add custom NVIDIA dark theme (green #76B900, dark backgrounds)
- Add Vue landing page converted from React JSX prototype
- Add end-to-end workflow diagram (transparent PNG)
- Move content/docs/ to docs/, rename _index.md to index.md
- Add h1 headings from frontmatter title (VitePress requirement)
- Escape Go/Helm template syntax ({{ }}) in inline markdown
- Fix internal links for VitePress routing
- Update gh-pages workflow for VitePress build
- Rename Deployer Agnostic to Standards Based with updated description
- Add cosign to security card (SLSA, SPDX, Sigstore cosign)
- Simplify supported environments text (drop AKS/OKE/OpenShift, add COS)
- Remove Kind from environment cards
- Add curl install option to hero and quick start sections
- Update contributing section: make qualify, contributor docs link, GitHub link
Replace manually duplicated site/docs/ files with a build-time sync
from docs/ (single source of truth). Previously, adding a doc to docs/
required manually copying it to site/docs/ and adding a sidebar entry —
both steps were easy to forget, resulting in 3 missing pages.

Changes:
- Add tools/sync-site-docs: copies docs/ → site/docs/ at build time
- Add tools/check-docs-sidebar: CI check that every doc has a sidebar entry
- Rename docs/*/README.md → index.md (works on both GitHub and VitePress)
- Fix relative links pointing outside docs tree → GitHub URLs
- Delete 27 duplicated files from site/docs/ (now generated, gitignored)
- Add 3 missing sidebar entries: Component Catalog, Validator Extension,
  Validator Development
- Fix Makefile site-serve/site-build: Hugo → VitePress
- Wire sync into site/package.json predev/prebuild hooks
Resolve conflicts from main's Hugo→VitePress migration. Keep our
single-source approach (docs/ as source of truth, site/docs/ generated).
Accept main's dependency version bumps and unrelated overlay changes.
@github-actions github-actions bot removed the area/ci label Mar 13, 2026
@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 13, 2026

Coverage Report ✅

Metric Value
Coverage 73.3%
Threshold 70%
Status Pass
Coverage Badge
![Coverage](https://img.shields.io/badge/coverage-73.3%25-green)

No Go source files changed in this PR.

mchmarny
mchmarny previously approved these changes Mar 13, 2026
npx vitepress build bypasses the prebuild hook that syncs docs/
into site/docs/, causing 20 dead links for user/, contributor/,
and integrator/ sections.
@mchmarny mchmarny added this to the M2 - KubeCon EU milestone Mar 13, 2026
@mchmarny mchmarny added the documentation Improvements or additions to documentation label Mar 13, 2026
@mchmarny mchmarny merged commit c06950e into main Mar 13, 2026
27 of 28 checks passed
@mchmarny mchmarny deleted the docs/single-source-site branch March 13, 2026 11:46
xdu31 pushed a commit to xdu31/aicr that referenced this pull request Mar 24, 2026
Co-authored-by: Mark Chmarny <mchmarny@users.noreply.github.com>
Co-authored-by: Mark Chmarny <mark@chmarny.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/ci area/docs documentation Improvements or additions to documentation size/XL

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants