Revamped engine for static documentation in the Next.js site

.devcontainer/devcontainer.json

@@ -0,0 +1,15 @@
+{
+  "name": "DocumentDB Next.js Dev Container",
+  "image": "mcr.microsoft.com/devcontainers/javascript-node",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "redhat.vscode-yaml"
+      ]
+    }
+  },
+  "forwardPorts": [
+    3000
+  ],
+  "postCreateCommand": "npm install"
+}

.github/scripts/ajv-to-ctrf.js

@@ -0,0 +1,90 @@
+// Minimal AJV output to CTRF converter
+// Reads validation-output.txt and writes a dummy CTRF report
+
+const fs = require('fs');
+const [, , inputPath, outputPath] = process.argv;
+
+if (!inputPath || !outputPath) {
+  console.error('Usage: node ajv-to-ctrf.js <input> <output>');
+  process.exit(1);
+}
+
+if (!fs.existsSync(inputPath)) {
+  console.error(`Error: Input file not found: ${inputPath}`);
+  fs.writeFileSync(outputPath, JSON.stringify({ version: '1.0', results: [], error: `Input file not found: ${inputPath}` }, null, 2));
+  process.exit(0);
+}
+
+const output = {
+  version: '1.0',
+  results: []
+};
+
+try {
+  const lines = fs.readFileSync(inputPath, 'utf-8').split('\n');
+  let currentTest = null;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    // Detect start of a new validation
+    if (trimmed.startsWith('Validating:')) {
+      if (currentTest) {
+        output.results.push(currentTest);
+      }
+      const match = trimmed.match(/Validating:\s+(.+?)\s+against\s+(.+)/);
+      if (match) {
+        currentTest = {
+          testName: match[1],
+          status: 'unknown',
+          message: `Validating ${match[1]} against ${match[2]}`,
+          details: []
+        };
+      }
+    }
+    // Detect pass/fail status
+    else if (trimmed.startsWith('✓ PASSED:')) {
+      if (currentTest) {
+        currentTest.status = 'pass';
+        output.results.push(currentTest);
+        currentTest = null;
+      }
+    }
+    else if (trimmed.startsWith('✗ FAILED:')) {
+      if (currentTest) {
+        currentTest.status = 'fail';
+        output.results.push(currentTest);
+        currentTest = null;
+      }
+    }
+    // Collect error details
+    else if (currentTest && (trimmed.includes('error') || trimmed.includes('invalid') || trimmed.includes('must'))) {
+      currentTest.details.push(trimmed);
+      currentTest.message += '\n' + trimmed;
+    }
+  }
+
+  // Add last test if exists
+  if (currentTest) {
+    output.results.push(currentTest);
+  }
+
+  // If no results, create a summary entry
+  if (output.results.length === 0) {
+    output.results.push({
+      testName: 'YAML Schema Validation',
+      status: 'pass',
+      message: 'No validation results found or all files skipped'
+    });
+  }
+
+  fs.writeFileSync(outputPath, JSON.stringify(output, null, 2));
+  console.log(`CTRF report generated: ${outputPath}`);
+  console.log(`Total tests: ${output.results.length}`);
+  console.log(`Passed: ${output.results.filter(r => r.status === 'pass').length}`);
+  console.log(`Failed: ${output.results.filter(r => r.status === 'fail').length}`);
+} catch (err) {
+  console.error('Error:', err);
+  process.exit(1);
+}

.github/workflows/nextjs.yml → .github/workflows/continuous-deployment.yml

@@ -1,33 +1,28 @@
 # Workflow for building Next.js site and downloading DocumentDB packages, then deploying to GitHub Pages
 name: Deploy Next.js site and DocumentDB packages to Pages
-
 on:
   # Runs on pushes targeting the default branch
   push:
-    branches: ["main"]
-
+    branches:
+      - main
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
-
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
 # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
 # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
 concurrency:
-  group: "pages"
+  group: pages
   cancel-in-progress: false
-
 jobs:
   # Build job
   build:
+    name: Build Next.js static site
+    # Sets permissions of the GITHUB_TOKEN to allow reading of repository content
+    permissions:
+      contents: read
     runs-on: ubuntu-22.04
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - name: Checkout source
+        uses: actions/checkout@v5
       - name: Install required packages
         run: |
           until sudo apt-get update; do sleep 1; done
@@ -72,19 +67,11 @@ jobs:
             echo "Unable to determine package manager"
             exit 1
           fi
-      - name: Setup Node
-        uses: actions/setup-node@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
         with:
-          node-version: "20"
+          node-version: 24
           cache: ${{ steps.detect-package-manager.outputs.manager }}
-      - name: Setup Pages
-        uses: actions/configure-pages@v5
-        with:
-          # Automatically inject basePath in your Next.js configuration file and disable
-          # server side image optimization (https://nextjs.org/docs/api-reference/next/image#unoptimized).
-          #
-          # You may remove this line if you want to manage the configuration yourself.
-          static_site_generator: next
       - name: Restore cache
         uses: actions/cache@v4
         with:
@@ -98,22 +85,37 @@ jobs:
       - name: Install dependencies
         run: ${{ steps.detect-package-manager.outputs.manager }} ${{ steps.detect-package-manager.outputs.command }}
       - name: Build with Next.js
+        env:
+          NEXT_BASE_PATH: ${{ github.event.repository.name }}
         run: ${{ steps.detect-package-manager.outputs.runner }} next build
       - name: Download DocumentDB packages from latest release
         run: .github/scripts/download_packages.sh
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
           path: ./out
-
   # Deployment job
   deploy:
+    name: Publish site to GitHub Pages
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
-    needs: build
+    needs:
+      - build
+    # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+    permissions:
+      pages: write
+      id-token: write
     steps:
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+        with:
+          # Automatically inject basePath in your Next.js configuration file and disable
+          # server side image optimization (https://nextjs.org/docs/api-reference/next/image#unoptimized).
+          #
+          # You may remove this line if you want to manage the configuration yourself.
+          static_site_generator: next
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4

.github/workflows/continuous-integration.yml

@@ -0,0 +1,27 @@
+name: Validate structured content
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+jobs:
+  yaml-schema-validation:
+    name: Validate YAML files against schemas
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+      - name: Set up Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: 24
+      - name: Install dependencies
+        run: |
+          npm install yaml-ls-check
+      - name: Validate YAML files
+        run: |
+          npx yaml-ls-check .\articles
+          npx yaml-ls-check .\blogs
+          npx yaml-ls-check .\reference

.gitignore

@@ -0,0 +1,37 @@
+# Sourced from https://github.com/github/gitignore/blob/main/Nextjs.gitignore
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+.env
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

.vscode/settings.json

@@ -0,0 +1,21 @@
+{
+  "yaml.schemas": {
+    "./schema/blog.content.schema.json": [
+      "blogs/content.{yml,yaml}"
+    ],
+    "./schema/reference.content.schema.json": [
+      "reference/content.{yml,yaml}"
+    ],
+    "./schema/reference.data.schema.json": [
+      "reference/*/**/*.{yml,yaml}"
+    ],
+    "./schema/articles.content.schema.json": [
+      "articles/**/content.{yml,yaml}"
+    ],
+    "./schema/articles.navigation.schema.json": [
+      "articles/**/navigation.{yml,yaml}"
+    ]
+  },
+  "editor.tabSize": 2,
+  "editor.insertSpaces": true
+}