ci: Add redirect target validator and fix 18 broken redirects

Add validate-redirects CI check that verifies all .gitbook.yaml
redirect targets resolve to existing pages. Fix 18 broken targets
caused by pages being moved or removed over time.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: louis-pre

.gitbook.yaml

@@ -4,7 +4,7 @@ root: ./docs/guides/
   readme: README.md
   summary: SUMMARY.md
 redirects:
-  latest/quickstart/get-api-key: latest/quickstart.md
+  latest/quickstart/get-api-key: quickstart.md
   quickstart/get-api-key: quickstart.md
   quickstart/installation: quickstart.md
   quickstart/authentication: quickstart.md
@@ -16,18 +16,18 @@ redirects:
   core-concepts/workspaces/personal-access-tokens: core-concepts/authentication/personal-access-tokens.md
   core-concepts/workspaces/client-session-tokens: core-concepts/authentication/client-session-tokens/README.md
   core-concepts/workspaces/client-session-tokens/implementing-client-sessions-for-device-management-in-the-backend: core-concepts/authentication/client-session-tokens/implementing-client-sessions-for-device-management-in-the-backend.md
-  products/access-systems/user-management: capability-guides/access-systems/user-management/README.md
-  capability-guides/access-systems/managing-credentials: capability-guides/access-systems/managing-credentials/README.md
+  products/access-systems/user-management: capability-guides/access-systems/user-management.md
+  capability-guides/access-systems/managing-credentials: capability-guides/access-systems/managing-credentials.md
   capability-guides/access-systems/assigning-credentials-to-users: capability-guides/access-systems/managing-credentials/assigning-credentials-to-users.md
   products/access-systems/suspending-and-unsuspending-users: capability-guides/access-systems/user-management/suspending-and-unsuspending-users.md
   products/seam-bridge-in-development: capability-guides/seam-bridge.md
   core-concepts/connect-webviews: core-concepts/connect-webviews/README.md
   device-guides/4suites-locks: device-and-system-integration-guides/4suites-locks/README.md
   device-guides/assa-abloy-visionline-access-control-system-in-development: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/README.md
-  device-guides/assa-abloy-visionline-access-control-system-in-development/credential-types: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/credential-types.md
-  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/visionline-credential-metadata: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-credential-metadata.md
+  device-guides/assa-abloy-visionline-access-control-system-in-development/credential-types: device-and-system-integration-guides/assa-abloy-visionline-access-control-system
+  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/visionline-credential-metadata: device-and-system-integration-guides/assa-abloy-visionline-access-control-system
   device-guides/assa-abloy-visionline-access-control-system-in-development/common-use-cases: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/common-use-cases.md
-  capability-guides/access-systems/understanding-acs-differences: capability-guides/access-systems/understanding-access-control-system-differences.md
+  capability-guides/access-systems/understanding-acs-differences: capability-guides/access-systems
   capability-guides/thermostats/creating-and-managing-climate-schedules: capability-guides/thermostats/creating-and-managing-thermostat-schedules.md
   device-guides/get-started-with-schlage-locks: device-and-system-integration-guides/schlage-locks/get-started-with-schlage-locks.md
   api-clients/access-codes/convert-an-unmanaged-access-code: api/access_codes/unmanaged/convert_to_managed.md
@@ -95,16 +95,16 @@ redirects:
   api-clients/connected-accounts/list-connected-accounts: api/connected_accounts/list.md
   api-clients/connected-accounts/update-a-connected-account: api/connected_accounts/update.md
   api-clients/connected-accounts: api/connected_accounts/README.md
-  api-clients/devices/delete-device: api/devices/delete.md
+  api-clients/devices/delete-device: api/devices
   api-clients/devices/get-device-1: api/devices/unmanaged/get.md
   api-clients/devices/get-device: api/devices/get.md
   api-clients/devices/list-device-providers: api/devices/list_device_providers.md
   api-clients/devices/list-devices: api/devices/list.md
   api-clients/devices/list-unmanaged-devices: api/devices/unmanaged/list.md
   api-clients/devices/update-device: api/devices/update.md
   api-clients/devices/update-unmanaged-device: api/devices/unmanaged/update.md
-  api-clients/events/get-an-event: api-clients/events/get.md
-  api-clients/events/list-events: api-clients/events/list.md
+  api-clients/events/get-an-event: api/events/get.md
+  api-clients/events/list-events: api/events/list.md
   api-clients/locks/get-lock: api/locks/get.md
   api-clients/locks/list-locks: api/locks/list.md
   api-clients/locks/lock-a-lock: api/locks/lock_door.md
@@ -114,7 +114,7 @@ redirects:
   api-clients/noise-sensors/list-noise-thresholds: api/noise_sensors/noise_thresholds/list.md
   api-clients/noise-sensors/update-noise-threshold: api/noise_sensors/noise_thresholds/update.md
   api-clients/noise-sensors: api/noise_sensors/README.md
-  api-clients/thermostats/get-thermostat: api/thermostats/get.md
+  api-clients/thermostats/get-thermostat: api/thermostats
   api-clients/thermostats/list-thermostats: api/thermostats/list.md
   api-clients/thermostats/set-fan-mode: api/thermostats/set_fan_mode.md
   api-clients/thermostats/set-to-cool-mode: api/thermostats/cool.md
@@ -136,7 +136,7 @@ redirects:
   api-clients/workspaces/get-workspace: api/workspaces/get.md
   api-clients/workspaces/reset-workspace: api/workspaces/reset_sandbox.md
   api-clients/phones/create-a-sandbox-phone: api/phones/simulate/create_sandbox_phone.md
-  device-and-system-integration-guides/assa-abloy-credential-services-credential-manager-in-development: device-and-system-integration-guides/assa-abloy-credential-services-credential-manager/README.md
+  device-and-system-integration-guides/assa-abloy-credential-services-credential-manager-in-development: device-and-system-integration-guides/assa-abloy-vingcard-credential-services.md
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/README.md
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/visionline-acs-setup-instructions: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/README.md
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/README.md
@@ -183,13 +183,13 @@ redirects:
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-7-purchase-and-import-the-callback-and-mobile-service-options-from-assa-abloy: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-7-purchase-and-import-the-callback-and-mobile-service-options-from-assa-abloy.md
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-8-create-a-production-workspace: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-8-create-a-production-workspace.md
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-9-connect-your-visionline-production-account-to-seam: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-9-connect-your-visionline-production-account-to-seam.md
-  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/credential-types/README.md
-  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/issuing-various-types-of-guest-mobile-credentials: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/credential-types/issuing-various-types-of-guest-mobile-credentials.md
-  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/issuing-various-types-of-guest-joiner-mobile-credentials: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/credential-types/issuing-various-types-of-guest-joiner-mobile-credentials.md
-  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/retrieving-guest-and-common-entrances: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/credential-types/retrieving-guest-and-common-entrances.md
-  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/checking-if-a-user-identity-has-a-phone-that-is-set-up-for-a-credential-manager: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/credential-types/checking-if-a-user-identity-has-a-phone-that-is-set-up-for-a-credential-manager.md
-  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/updating-guest-mobile-credentials: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/credential-types/updating-guest-mobile-credentials.md
-  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/revoking-mobile-credentials: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/credential-types/revoking-mobile-credentials.md
+  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types: device-and-system-integration-guides/assa-abloy-visionline-access-control-system
+  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/issuing-various-types-of-guest-mobile-credentials: device-and-system-integration-guides/assa-abloy-visionline-access-control-system
+  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/issuing-various-types-of-guest-joiner-mobile-credentials: device-and-system-integration-guides/assa-abloy-visionline-access-control-system
+  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/retrieving-guest-and-common-entrances: device-and-system-integration-guides/assa-abloy-visionline-access-control-system
+  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/checking-if-a-user-identity-has-a-phone-that-is-set-up-for-a-credential-manager: device-and-system-integration-guides/assa-abloy-visionline-access-control-system
+  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/updating-guest-mobile-credentials: device-and-system-integration-guides/assa-abloy-visionline-access-control-system
+  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/revoking-mobile-credentials: device-and-system-integration-guides/assa-abloy-visionline-access-control-system
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/mobile-credential-related-properties: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/mobile-credential-related-properties.md
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/common-use-cases: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/common-use-cases.md
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/special-requirements-for-android-mobile-access-sdk-development: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/special-requirements-for-android-mobile-access-sdk-development.md

.github/workflows/generate.yml

@@ -82,3 +82,5 @@ jobs:
         run: npm run validate-paths
       - name: Validate cross-site links
         run: npm run validate-links
+      - name: Validate redirect targets
+        run: npm run validate-redirects

codegen/validate-redirects.ts

@@ -0,0 +1,103 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { siteSections } from './lib/config.js'
+
+// Parse the redirects section from .gitbook.yaml.
+// Each redirect line is: "  source-path: target-path"
+const gitbookYaml = readFileSync('.gitbook.yaml', 'utf-8')
+const lines = gitbookYaml.split('\n')
+
+interface Redirect {
+  line: number
+  source: string
+  target: string
+}
+
+const redirects: Redirect[] = []
+let inRedirects = false
+
+for (let i = 0; i < lines.length; i++) {
+  const line = lines[i] ?? ''
+
+  if (line === 'redirects:') {
+    inRedirects = true
+    continue
+  }
+
+  // A non-indented, non-empty line ends the redirects section
+  if (inRedirects && line !== '' && !line.startsWith(' ')) {
+    break
+  }
+
+  if (!inRedirects) continue
+
+  const match = line.match(/^\s+(.+?):\s+(.+)$/)
+  if (match?.[1] != null && match[2] != null) {
+    redirects.push({ line: i + 1, source: match[1], target: match[2] })
+  }
+}
+
+// Check if a path resolves to a page as a file, URL slug, or directory index.
+function pageExists(fullPath: string): boolean {
+  // Exact file match (e.g., quickstart.md)
+  if (existsSync(fullPath)) return true
+  // Directory with README.md (e.g., core-concepts/ → core-concepts/README.md)
+  if (existsSync(join(fullPath, 'README.md'))) return true
+  // URL-style target without .md extension (e.g., api/devices → api/devices.md)
+  if (!fullPath.endsWith('.md') && existsSync(fullPath + '.md')) return true
+  return false
+}
+
+// Resolve a redirect target to check it points to a real page.
+// Targets may reference other site sections via URL prefix.
+function resolveTarget(target: string): boolean {
+  // Try matching against site sections by URL prefix (most specific first).
+  // The siteSections array is already ordered with more-specific prefixes first.
+  for (const section of siteSections) {
+    if (section.urlPrefix === '') continue
+
+    const prefix = section.urlPrefix.replace(/^\//, '') + '/'
+    if (target.startsWith(prefix)) {
+      const relativePath = target.slice(prefix.length)
+      return pageExists(join(section.root, relativePath))
+    }
+  }
+
+  // Fall back to the default section (Guides, urlPrefix '')
+  const guidesSection = siteSections.find((s) => s.urlPrefix === '')
+  if (guidesSection == null) return false
+
+  return pageExists(join(guidesSection.root, target))
+}
+
+interface BrokenRedirect {
+  line: number
+  source: string
+  target: string
+}
+
+const broken: BrokenRedirect[] = []
+
+for (const redirect of redirects) {
+  if (!resolveTarget(redirect.target)) {
+    broken.push(redirect)
+  }
+}
+
+if (broken.length > 0) {
+  // eslint-disable-next-line no-console
+  console.error(
+    `Found ${broken.length} redirect(s) with missing target(s) in .gitbook.yaml:\n`,
+  )
+  for (const { line, source, target } of broken) {
+    // eslint-disable-next-line no-console
+    console.error(`  line ${line}: ${source}`)
+    // eslint-disable-next-line no-console
+    console.error(`    target: ${target}\n`)
+  }
+  process.exit(1)
+} else {
+  // eslint-disable-next-line no-console
+  console.log('All .gitbook.yaml redirect targets are valid.')
+}

package.json

@@ -18,6 +18,7 @@
     "postgenerate": "npm run format",
     "validate-paths": "tsx codegen/validate-paths.ts",
     "validate-links": "tsx codegen/validate-links.ts",
+    "validate-redirects": "tsx codegen/validate-redirects.ts",
     "typecheck": "tsc",
     "lint": "eslint .",
     "postlint": "prettier --check --ignore-path .prettierignore .",