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

Co-authored-by: Mark Chmarny <mchmarny@users.noreply.github.com>
Co-authored-by: Mark Chmarny <mark@chmarny.com>

Author: tabern

.github/workflows/gh-pages.yaml

@@ -66,11 +66,11 @@ jobs:
 
       - name: Build site (PR)
         if: github.event_name == 'pull_request'
-        run: cd site && npm ci && npx vitepress build
+        run: cd site && npm ci && npm run build
 
       - name: Build site
         if: github.event_name != 'pull_request'
-        run: cd site && npm ci && npx vitepress build
+        run: cd site && npm ci && npm run build
 
       - name: Upload artifact
         if: github.event_name != 'pull_request'

.gitignore

@@ -124,6 +124,12 @@ tags
 site/.vitepress/cache/
 site/.vitepress/dist/
 site/node_modules/
+# Generated from docs/ by tools/sync-site-docs (do not edit directly)
+site/docs/user/
+site/docs/integrator/
+site/docs/contributor/
+site/docs/conformance/evidence/
+site/docs/conformance/index.md
 
 # Claude
 .claude/settings.local.json

Makefile

@@ -103,13 +103,17 @@ generate: ## Runs go generate for code generation
 	@echo "Code generation completed"
 
 .PHONY: lint
-lint: lint-go lint-yaml license check-agents-sync ## Lints the entire project (Go, YAML, and license headers)
+lint: lint-go lint-yaml license check-agents-sync check-docs-sidebar ## Lints the entire project (Go, YAML, and license headers)
 	@echo "Completed Go and YAML lints and ensured license headers"
 
 .PHONY: check-agents-sync
 check-agents-sync: ## Verifies AGENTS.md is in sync with .claude/CLAUDE.md
 	@./tools/check-agents-sync
 
+.PHONY: check-docs-sidebar
+check-docs-sidebar: ## Verifies all docs/ pages have sidebar entries in VitePress config
+	@./tools/check-docs-sidebar
+
 .PHONY: lint-go
 lint-go: ## Lints Go files with golangci-lint and go vet
 	@set -e; \
@@ -226,19 +230,19 @@ docs: ## Serves Go documentation on http://localhost:6060
 .PHONY: site-serve
 site-serve: ## Serve documentation site locally
 	@set -e; \
-	echo "Starting documentation site on http://localhost:1313..."; \
-	cd site && npm install && hugo serve --baseURL http://localhost:1313/
+	echo "Starting documentation site on http://localhost:5173..."; \
+	cd site && npm install && npm run dev
 
 .PHONY: site-build
 site-build: ## Build documentation site
 	@set -e; \
 	echo "Building documentation site..."; \
-	cd site && npm install && hugo --minify; \
-	echo "Site built in site/public/"
+	cd site && npm install && npm run build; \
+	echo "Site built in site/.vitepress/dist/"
 
 .PHONY: site-clean
 site-clean: ## Clean documentation build artifacts
-	@rm -rf site/public site/resources
+	@rm -rf site/.vitepress/dist site/.vitepress/cache
 	@echo "Cleaned documentation build artifacts"
 
 .PHONY: build

docs/README.md

@@ -132,7 +132,7 @@ For developers contributing code, extending functionality, or working on AICR in
 
 | Document | Description |
 |----------|-------------|
-| [Architecture Overview](contributor/README.md) | System design, patterns, and deployment topologies |
+| [Architecture Overview](contributor/index.md) | System design, patterns, and deployment topologies |
 | [CLI Architecture](contributor/cli.md) | Detailed CLI implementation and workflow diagrams |
 | [API Server Architecture](contributor/api-server.md) | HTTP server design, middleware, and endpoints |
 | [Data Architecture](contributor/data.md) | Recipe metadata system, criteria matching, and inheritance |

docs/conformance/cncf/README.md docs/conformance/cncf/index.mddocs/conformance/cncf/README.md renamed to docs/conformance/cncf/index.md

@@ -1048,7 +1048,7 @@ export TAG=$(curl -s https://api.github.com/repos/NVIDIA/aicr/releases/latest |
 gh attestation verify oci://ghcr.io/nvidia/aicrd:${TAG} --owner nvidia
 ```
 
-For detailed CI/CD architecture, see [../CONTRIBUTING.md#github-actions--cicd](../../CONTRIBUTING.md#github-actions--cicd) and [README.md](README.md#cicd-architecture).
+For detailed CI/CD architecture, see [CONTRIBUTING.md](https://github.com/NVIDIA/aicr/blob/main/CONTRIBUTING.md#github-actions--cicd) and [Architecture Overview](index.md#cicd-architecture).
 
 ### Local Build Configuration
 

docs/contributor/api-server.md

@@ -191,8 +191,8 @@ The component registry (`recipes/registry.yaml`) supports these fields:
 
 - Only add custom manifests when the Helm chart doesn't provide needed functionality
 - Use Helm template syntax (not Go templates) for manifest files
-- Reference values via `{{ index .Values "component-name" }}`
-- Make manifests conditional with `{{- if }}` blocks
+- Reference values via <code v-pre>{{ index .Values "component-name" }}</code>
+- Make manifests conditional with <code v-pre>{{- if }}</code> blocks
 
 ### Testing
 
@@ -452,9 +452,9 @@ See [CLI Architecture](cli.md#deployer-framework-gitops-integration) for detaile
 
 ## See Also
 
-- [Architecture Overview](README.md) - Complete bundler framework architecture
+- [Architecture Overview](index.md) - Complete bundler framework architecture
 - [CLI Architecture](cli.md) - Deployer framework and GitOps integration
 - [CLI Reference](../user/cli-reference.md) - Bundle generation commands
 - [API Reference](../user/api-reference.md) - Programmatic access (recipe generation only)
-- [Component Registry](../../recipes/registry.yaml) - Declarative component configuration
-- [Recipe Data README](../../recipes/README.md) - Recipe and component data overview
+- [Component Registry](https://github.com/NVIDIA/aicr/blob/main/recipes/registry.yaml) - Declarative component configuration
+- [Recipe Data](https://github.com/NVIDIA/aicr/tree/main/recipes) - Recipe and component data overview

docs/contributor/component.md

@@ -25,7 +25,7 @@ The recipe system is a rule-based configuration engine that generates tailored s
 4. **Merging configurations** - Components, constraints, and values are merged with overlay precedence
 5. **Computing deployment order** - Topological sort of components based on dependency references
 
-The recipe data is organized in [`recipes/`](../../recipes/) as multiple YAML files:
+The recipe data is organized in [`recipes/`](https://github.com/NVIDIA/aicr/tree/main/recipes) as multiple YAML files:
 
 ```
 recipes/
@@ -1292,5 +1292,5 @@ func initDataProvider(cmd *cli.Command) error {
 - [CLI Architecture](cli.md) - How the CLI uses recipe data
 - [CLI Reference](../user/cli-reference.md) - Complete CLI flag reference
 - [API Server Architecture](api-server.md) - How the API serves recipes
-- [OpenAPI Specification](../../api/aicr/v1/server.yaml) - Recipe API contract
-- [Recipe Package Documentation](../../pkg/recipe/) - Go implementation details
+- [OpenAPI Specification](https://github.com/NVIDIA/aicr/blob/main/api/aicr/v1/server.yaml) - Recipe API contract
+- [Recipe Package Documentation](https://github.com/NVIDIA/aicr/tree/main/pkg/recipe) - Go implementation details

docs/contributor/data.md

@@ -1,5 +1,6 @@
 # AICR Architecture
 
+
 This directory contains architecture documentation for the AI Cluster Runtime (AICR) tooling.
 
 ## First Principles
@@ -38,8 +39,6 @@ This directory contains architecture documentation for the AI Cluster Runtime (A
 * The system provides validated configuration, not a new operational model.
 
 **Why:** If adoption requires retraining users on “the right way” then our design has failed.
-
-
 ## Components
 
 - **[CLI Architecture](cli.md)**: Command-line tool (`aicr`) implementing all four workflow stages
@@ -719,7 +718,7 @@ The Bundler Framework provides an extensible system for generating deployment bu
 **3. BaseBundler Helper Pattern**
 **Rationale**: Common file operations across all bundlers
 **Implementation**: Struct embedding with methods (directory creation, file writing, template rendering, checksum generation)
-**Reference**: [pkg/component](../../pkg/component)
+**Reference**: [pkg/component](https://github.com/NVIDIA/aicr/tree/main/pkg/component)
 
 **4. Registry Pattern**  
 **Rationale**: Decoupled bundler registration; extensibility without modifying core code  
@@ -950,8 +949,6 @@ Components are configured in `recipes/registry.yaml`. The bundler automatically
 
 **Per-Component Bundle Generation**:
 The bundler generates a per-component Helm bundle with individual values and manifests for each component, based on the recipe's `componentRefs`.
-
-
 ### Metrics and Observability
 
 **Bundler Metrics** (Prometheus):
@@ -1222,9 +1219,9 @@ cosign verify-attestation \
 - Source code in public repository
 - Attestations queryable via `rekor-cli`
 
-For detailed CI/CD documentation, see [../../.github/actions/README.md](../../.github/actions/README.md) and [CONTRIBUTING.md](../../CONTRIBUTING.md#github-actions--cicd).
+For detailed CI/CD documentation, see [.github/actions](https://github.com/NVIDIA/aicr/tree/main/.github/actions) and [CONTRIBUTING.md](https://github.com/NVIDIA/aicr/blob/main/CONTRIBUTING.md#github-actions--cicd).
 
-For supply chain security verification, see [../../SECURITY.md](../../SECURITY.md).
+For supply chain security verification, see [SECURITY.md](https://github.com/NVIDIA/aicr/blob/main/SECURITY.md).
 
 ## E2E Testing Architecture
 
@@ -1323,7 +1320,7 @@ steps:
 - **Agent Testing**: Validates RBAC permissions and Job execution
 - **Bundle Verification**: Ensures deployment artifacts are correct
 
-For detailed usage, see [../../CONTRIBUTING.md#end-to-end-testing](../../CONTRIBUTING.md#end-to-end-testing).
+For detailed usage, see [CONTRIBUTING.md](https://github.com/NVIDIA/aicr/blob/main/CONTRIBUTING.md#end-to-end-testing).
 
 ## References and Further Reading
 

docs/contributor/README.md docs/contributor/index.mddocs/contributor/README.md renamed to docs/contributor/index.md

@@ -364,6 +364,6 @@ When adding a new upstream check:
 ## See Also
 
 - [Validator Extension Guide](../integrator/validator-extension.md) — External validators via `--data`
-- [Validator Catalog Reference](../../recipes/validators/README.md) — Catalog schema and entries
-- [Validator V2 ADR](../design/002-validatorv2-adr.md) — Architecture decision record
+- [Validator Catalog Reference](https://github.com/NVIDIA/aicr/tree/main/recipes/validators) — Catalog schema and entries
+- [Validator V2 ADR](https://github.com/NVIDIA/aicr/blob/main/docs/design/002-validatorv2-adr.md) — Architecture decision record
 - [CLI Reference](../user/cli-reference.md#aicr-validate) — Validate command flags