site: eliminate docs duplication with build-time sync#385
Merged
Conversation
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.
…s to Supported Components
- 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.
Coverage Report ✅
Coverage BadgeNo Go source files changed in this PR. |
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.
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/is now the only place to edit documentation.site/docs/content is generated at build time bytools/sync-site-docs.tools/check-docs-sidebar(wired intomake lint) fails if any doc file is missing from the VitePress sidebar config — no more forgotten pages.site/docs/(now gitignored, generated at build time).site-serve/site-buildupdated from Hugo to VitePress.How it works
docs/**/*.md(works on GitHub + site)tools/sync-site-docscopies docs →site/docs/(runs automatically via npmpredev/prebuildhooks)site/as usualmake lintchecks every doc has a sidebar entryTest plan
npx vitepress buildpasses with zero dead linkstools/check-docs-sidebarpasses (all docs in sidebar)tools/check-docs-sidebarfails when a new doc is added without sidebar entrymake lintpasses in CI