Migrate Docs to VitePress (#293)

Author: hardikdr

.github/workflows/publish-docs.yml

@@ -0,0 +1,57 @@
+name: Deploy VitePress site to Pages
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [assigned, opened, synchronize, reopened]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Run docs build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Install dependencies
+        run: npm ci
+      - name: Build with VitePress
+        run: npm run docs:build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs/.vitepress/dist
+        if: github.event_name != 'pull_request'
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Run docs publish
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

.github/workflows/publish_docs.yaml

@@ -30,3 +30,8 @@ vendor/
 *.swp
 *.swo
 *~
+
+# Node / VitePress
+node_modules/
+docs/.vitepress/cache/
+docs/.vitepress/dist/

.gitignore

@@ -2,8 +2,9 @@
 # Image URL to use all building/pushing image targets
 IMG ?= controller:latest
 
-# Docker image name for the mkdocs based local development setup
-IMAGE=ironcore-dev/boot-operator-docs
+# Docker image name for the VitePress based local development setup
+DOCS_IMAGE ?= ironcore-dev/boot-operator-docs
+DOCS_PORT ?= 5173
 
 # Get the currently used golang install path (in GOPATH/bin, unless GOBIN is set)
 ifeq (,$(shell go env GOBIN))
@@ -237,13 +238,21 @@ $(GOLANGCI_LINT): $(LOCALBIN)
 
 
 .PHONY: startdocs
-startdocs: ## Start the local mkdocs based development environment.
-	docker build -t $(IMAGE) -f docs/Dockerfile . --load
-	docker run -p 8000:8000 -v `pwd`/:/docs $(IMAGE)
+startdocs: ## Start the local VitePress based development environment.
+	@# When users have `docker build` forwarded to buildx (via `docker buildx install`),
+	@# the resulting image may remain only in the build cache unless `--load` is used.
+	@# Prefer `buildx --load` when available to keep `$(CONTAINER_TOOL) run $(DOCS_IMAGE)` working.
+	@if $(CONTAINER_TOOL) buildx version >/dev/null 2>&1; then \
+		$(CONTAINER_TOOL) buildx build --load -t $(DOCS_IMAGE) -f docs/Dockerfile .; \
+	else \
+		$(CONTAINER_TOOL) build -t $(DOCS_IMAGE) -f docs/Dockerfile .; \
+	fi
+	$(CONTAINER_TOOL) run --rm -p $(DOCS_PORT):5173 -v "$(shell pwd)":/app $(DOCS_IMAGE)
 
 .PHONY: cleandocs
-cleandocs: ## Remove all local mkdocs Docker images (cleanup).
-	docker container prune --force --filter "label=project=boot_operator"
+cleandocs: ## Cleanup local docs Docker artifacts (image + dangling layers).
+	-$(CONTAINER_TOOL) image rm --force $(DOCS_IMAGE)
+	-$(CONTAINER_TOOL) image prune --force --filter "label=project=boot_operator"
 
 .PHONY: addlicense
 addlicense: $(ADDLICENSE) ## Download addlicense locally if necessary.

Makefile

@@ -27,11 +27,12 @@ path = [
     "test/**",
     "CONTRIBUTING.md",
     "PROJECT",
-    "mkdocs.yml",
     ".dockerignore",
     ".golangci.yml",
     "CLAUDE.md",
-    "REUSE.toml"
+    "REUSE.toml",
+    "package-lock.json",
+    "package.json"
 ]
 precedence = "aggregate"
 SPDX-FileCopyrightText = "2025 SAP SE or an SAP affiliate company and IronCore contributors"

REUSE.toml

@@ -0,0 +1,89 @@
+import { withMermaid } from "vitepress-plugin-mermaid";
+import { fileURLToPath, URL } from "node:url";
+
+export default withMermaid({
+  title: "Boot Operator",
+  description: "Kubernetes operator to automate bare metal network boot infrastructure",
+  base: "/boot-operator/",
+  head: [
+    [
+      "link",
+      {
+        rel: "icon",
+        href: "https://raw.githubusercontent.com/ironcore-dev/ironcore/refs/heads/main/docs/assets/logo_borderless.svg",
+      },
+    ],
+  ],
+  vite: {
+    resolve: {
+      alias: [
+        {
+          // Override default theme footer with our funding notice.
+          find: /^.*\/VPFooter\.vue$/,
+          replacement: fileURLToPath(
+            new URL("./theme/components/VPFooter.vue", import.meta.url),
+          ),
+        },
+      ],
+    },
+  },
+  themeConfig: {
+    nav: [
+      { text: "Home", link: "/" },
+      { text: "Documentation", link: "/architecture" },
+      { text: "Quickstart", link: "/quickstart" },
+      { text: "IronCore Documentation", link: "https://ironcore-dev.github.io" },
+    ],
+
+    editLink: {
+      pattern: "https://github.com/ironcore-dev/boot-operator/blob/main/docs/:path",
+      text: "Edit this page on GitHub",
+    },
+
+    logo: {
+      src: "https://raw.githubusercontent.com/ironcore-dev/ironcore/refs/heads/main/docs/assets/logo_borderless.svg",
+      width: 24,
+      height: 24,
+    },
+
+    search: {
+      provider: "local",
+    },
+
+    sidebar: [
+      {
+        items: [
+          { text: "Quickstart", link: "/quickstart" },
+          {
+            text: "Installation",
+            collapsed: true,
+            items: [
+              { text: "Kustomize", link: "/installation/kustomize" },
+              { text: "Helm", link: "/installation/helm" },
+            ],
+          },
+          { text: "Architecture", link: "/architecture" },
+          { text: "API Reference", link: "/api-reference/api" },
+        ],
+      },
+      {
+        text: "Usage",
+        collapsed: false,
+        items: [{ text: "bootctl", link: "/usage/bootctl" }],
+      },
+      {
+        text: "Development",
+        collapsed: false,
+        items: [
+          { text: "Documentation", link: "/development/dev_docs" },
+          { text: "Create UKI", link: "/development/create_uki" },
+        ],
+      },
+    ],
+
+    socialLinks: [
+      { icon: "github", link: "https://github.com/ironcore-dev/boot-operator" },
+    ],
+  },
+});
+