Add shared build scripts and fix Docusaurus build errors

.github/workflows/build-and-deploy.yml

@@ -63,6 +63,11 @@ jobs:
       with:
         node-version: '20'
 
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
     - name: Setup caching for build artifacts
       uses: actions/cache@v4
       id: cache-npm
@@ -174,6 +179,13 @@ jobs:
 
         echo "✅ Configuration patches applied"
 
+    - name: Patch docs source
+      run: |
+        cd "${{ env.TEMP_DIR }}/llama-stack/docs"
+        echo "🔧 Patching docs source (sidebar validation, blog warnings, MDX compat)..."
+        "${{ github.workspace }}/patch-docs-source.sh" --repo-dir "${{ github.workspace }}"
+        echo "✅ Docs source patched"
+
     - name: Import existing versioning artifacts
       run: |
         echo "📥 Importing existing versioning artifacts from repository..."
@@ -362,34 +374,20 @@ jobs:
           echo "🏗️ Building latest version (no version snapshot needed)"
         fi
 
-    - name: Fix versioned docs relative imports
+    - name: Inline raw-loader imports in versioned docs
       run: |
         cd "${{ env.TEMP_DIR }}/llama-stack/docs"
 
-        echo "🔧 Fixing relative imports in versioned docs..."
+        echo "🔧 Inlining raw-loader imports in versioned docs..."
 
         if [ -d "versioned_docs" ]; then
-          # Fix relative paths (../../../file.md -> absolute path)
-          find versioned_docs -name "*.mdx" -type f \
-            -exec grep -l "!!raw-loader!\.\." {} \; | \
-            while read file; do
-              echo "Fixing relative raw-loader imports in $file"
-              # Pattern: !!raw-loader! followed by any number of ../ then a filename
-              # Replace with absolute path to repo root + filename
-              perl -i -pe "s|!!raw-loader!(\.\.\/)+([^'\"]*)|!!raw-loader!${{ env.TEMP_DIR }}/llama-stack/\$2|g" "$file"
-            done
-
-          # Fix hardcoded old temp paths (/tmp/tmp.XXXXXX/llama-stack/file.md -> current temp path)
-          find versioned_docs -name "*.mdx" -type f \
-            -exec grep -l "!!raw-loader!/tmp/tmp\." {} \; | \
-            while read file; do
-              echo "Fixing hardcoded temp path imports in $file"
-              # Pattern: !!raw-loader!/tmp/tmp.XXXXXX/llama-stack/filename
-              # Replace with current temp directory path
-              perl -i -pe "s|!!raw-loader!/tmp/tmp\.[^/]+/llama-stack/([^'\"]*)|!!raw-loader!${{ env.TEMP_DIR }}/llama-stack/\$1|g" "$file"
-            done
-
-          echo "✅ Versioned docs import paths corrected"
+          for version_dir in versioned_docs/version-*; do
+            if [ -d "$version_dir" ]; then
+              echo "  Processing $version_dir..."
+              python3 "${{ github.workspace }}/inline-raw-loader.py" "$version_dir" "${{ env.TEMP_DIR }}/llama-stack"
+            fi
+          done
+          echo "✅ Versioned docs raw-loader imports inlined"
         else
           echo "ℹ️ No versioned docs found"
         fi

build-archived-version.sh

@@ -63,14 +63,14 @@ if [ -f "static/deprecated-llama-stack-spec.yaml" ]; then
   npm run gen-api-docs deprecated 2>&1 | grep -E "^Successfully" || true
 fi
 
-# Step 4: Inline raw-loader imports
+# Step 4: Patch docs source (sidebar validation, blog warnings, MDX compat)
+echo "--- Patching docs source ---"
+"$REPO_DIR/patch-docs-source.sh" --repo-dir "$REPO_DIR"
+
+# Step 5: Inline raw-loader imports
 echo "--- Inlining raw-loader imports ---"
 python3 "$REPO_DIR/inline-raw-loader.py" docs "$TEMP_DIR/llama-stack"
 
-# Step 5: Fix MDX compatibility issues
-echo "--- Fixing MDX compatibility ---"
-python3 "$REPO_DIR/fix-mdx-compat.py" docs
-
 # Step 6: Patch config for standalone archived build
 echo "--- Patching config for baseUrl: /$VERSION/ ---"
 export VERSION
@@ -102,12 +102,6 @@ config = config.replace(
   `themeConfig: {${bannerEntry}`
 );
 
-// Fix blog include pattern to support both .md and .mdx
-config = config.replace(
-  /include:\s*\['?\*\.md'?\]/g,
-  "include: ['*.{md,mdx}']"
-);
-
 fs.writeFileSync('docusaurus.config.ts', config);
 console.log('Config patched');
 CONFIGEOF

build-latest.sh

@@ -0,0 +1,194 @@
+#!/bin/bash
+set -euo pipefail
+
+# build-latest.sh - Build the latest (main branch) Docusaurus docs locally
+#
+# Usage: ./build-latest.sh [--llama-stack-dir <path>] [--output-dir <path>]
+#
+# Examples:
+#   ./build-latest.sh
+#   ./build-latest.sh --llama-stack-dir /tmp/llama-stack
+#   ./build-latest.sh --output-dir /tmp/docs-output
+#
+# Output: docs/ directory (or specified output dir) containing the full static site
+
+REPO_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Parse optional arguments
+LLAMA_STACK_DIR=""
+OUTPUT_DIR="$REPO_DIR/docs"
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --llama-stack-dir) LLAMA_STACK_DIR="$2"; shift 2 ;;
+    --output-dir) OUTPUT_DIR="$2"; shift 2 ;;
+    *) echo "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+# Setup temp directory for the build
+TEMP_DIR=$(mktemp -d)
+BUILD_DIR="$TEMP_DIR/llama-stack/docs"
+trap 'rm -rf "$TEMP_DIR"' EXIT
+
+echo "=== Building latest docs ==="
+
+# Step 1: Get llama-stack at main branch
+if [ -n "$LLAMA_STACK_DIR" ] && [ -d "$LLAMA_STACK_DIR" ]; then
+  echo "--- Cloning from local repo ---"
+  git clone --local --no-checkout "$LLAMA_STACK_DIR" "$TEMP_DIR/llama-stack"
+  cd "$TEMP_DIR/llama-stack"
+  git checkout main
+else
+  echo "--- Cloning from GitHub ---"
+  git clone --depth 1 --branch main https://github.com/llamastack/llama-stack.git "$TEMP_DIR/llama-stack"
+fi
+
+cd "$BUILD_DIR"
+
+# Step 2: Install dependencies
+echo "--- Installing dependencies ---"
+npm ci 2>&1 | tail -5
+
+# Step 3: Patch docs source for clean build
+echo "--- Patching docs source ---"
+"$REPO_DIR/patch-docs-source.sh" --repo-dir "$REPO_DIR"
+
+# Step 4: Generate API docs
+echo "--- Generating API docs ---"
+
+if [ -f "static/llama-stack-spec.yaml" ]; then
+  npm run gen-api-docs stable 2>&1 | grep -E "^Successfully" || true
+fi
+
+if [ -f "static/experimental-llama-stack-spec.yaml" ]; then
+  npm run gen-api-docs experimental 2>&1 | grep -E "^Successfully" || true
+fi
+
+if [ -f "static/deprecated-llama-stack-spec.yaml" ]; then
+  npm run gen-api-docs deprecated 2>&1 | grep -E "^Successfully" || true
+fi
+
+# Step 5: Inline raw-loader imports
+echo "--- Inlining raw-loader imports ---"
+python3 "$REPO_DIR/inline-raw-loader.py" docs "$TEMP_DIR/llama-stack"
+
+# Step 6: Set up versioning configuration
+echo "--- Setting up versioning ---"
+cp "$REPO_DIR/versionsArchived.json" ./
+
+# Load existing versions.json or create empty
+if [ -f "$REPO_DIR/docs/versions.json" ]; then
+  cp "$REPO_DIR/docs/versions.json" ./
+  echo "Loaded existing versions.json"
+else
+  echo "[]" > versions.json
+  echo "Created empty versions.json"
+fi
+
+# Copy existing versioned_docs and versioned_sidebars if they exist
+if [ -d "$REPO_DIR/versioned_docs" ]; then
+  cp -r "$REPO_DIR/versioned_docs" ./
+  echo "Imported existing versioned_docs"
+fi
+
+if [ -d "$REPO_DIR/versioned_sidebars" ]; then
+  cp -r "$REPO_DIR/versioned_sidebars" ./
+  echo "Imported existing versioned_sidebars"
+fi
+
+# Inline raw-loader imports in versioned docs
+if [ -d "versioned_docs" ]; then
+  for version_dir in versioned_docs/version-*; do
+    if [ -d "$version_dir" ]; then
+      python3 "$REPO_DIR/inline-raw-loader.py" "$version_dir" "$TEMP_DIR/llama-stack"
+    fi
+  done
+fi
+
+# Patch Docusaurus config for versioning
+node << 'EOF'
+const fs = require('fs');
+
+let config = fs.readFileSync('docusaurus.config.ts', 'utf8');
+
+// Add versioning imports after OpenAPI import
+const versioningImports = `
+// Import fs for versioning configuration
+const fs = require('fs');
+
+// Versioning configuration for llamastack.github.io
+const versionsArchived = (() => {
+  try {
+    return JSON.parse(fs.readFileSync('./versionsArchived.json', 'utf8'));
+  } catch (e) {
+    console.warn('Could not load versionsArchived.json:', e);
+    return {};
+  }
+})();
+
+const archivedVersionsDropdownItems = Object.entries(versionsArchived).map(
+  ([versionName, versionUrl]) => ({
+    label: versionName,
+    href: versionUrl,
+  })
+);
+`;
+
+config = config.replace(
+  /import type \* as OpenApiPlugin from "docusaurus-plugin-openapi-docs";/,
+  `import type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs";
+
+${versioningImports}`
+);
+
+// Add version dropdown to navbar (replace GitHub item)
+const versionDropdown = `        {
+  href: 'https://github.com/llamastack/llama-stack',
+  label: 'GitHub',
+  position: 'right',
+},
+{
+  type: 'docsVersionDropdown',
+  position: 'right',
+  dropdownItemsAfter: archivedVersionsDropdownItems.length > 0 ? [
+    {
+      type: 'html',
+      value: '<hr class="dropdown-separator">',
+    },
+    {
+      type: 'html',
+      className: 'dropdown-archived-versions',
+      value: '<b>Previous versions</b>',
+    },
+    ...archivedVersionsDropdownItems,
+  ] : [],
+},`;
+
+config = config.replace(
+  /\s*{\s*href:\s*'https:\/\/github\.com\/llamastack\/llama-stack',\s*label:\s*'GitHub',\s*position:\s*'right',\s*},/,
+  versionDropdown
+);
+
+fs.writeFileSync('docusaurus.config.ts', config);
+console.log('Versioning config patched');
+EOF
+
+# Step 7: Patch out duplicate version badges from OpenAPI MDX files
+echo "--- Patching duplicate version badges ---"
+find . -name "llama-stack-specification.info.mdx" -type f -exec sed -i '' '/<span$/,/<\/span>$/d' {} \; 2>/dev/null || \
+find . -name "llama-stack-specification.info.mdx" -type f -exec sed -i '/<span$/,/<\/span>$/d' {} \;
+
+# Step 8: Build
+echo "--- Building ---"
+NODE_OPTIONS="--max-old-space-size=8192" npm run build 2>&1 | tail -50
+
+# Step 9: Copy build output
+echo "--- Copying to $OUTPUT_DIR ---"
+rm -rf "$OUTPUT_DIR"
+mkdir -p "$OUTPUT_DIR"
+cp -r build/* "$OUTPUT_DIR/"
+touch "$OUTPUT_DIR/.nojekyll"
+
+echo "=== Done building latest docs ==="
+echo "Output: $OUTPUT_DIR"
+du -sh "$OUTPUT_DIR"