docs: link-check unified site + fix systemic base-prefix bug (#75)

docs/astro.config.mjs

@@ -1,11 +1,15 @@
 // @ts-check
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
+import rehypeBaseUrl from '../packages/core/src/codegen/rehype-base-url.mjs';
 
 // https://astro.build/config
 export default defineConfig({
 	site: 'https://intentius.io',
 	base: '/chant',
+	markdown: {
+		rehypePlugins: [[rehypeBaseUrl, { base: '/chant' }]],
+	},
 	integrations: [
 		starlight({
 			title: 'chant',

justfile

@@ -65,6 +65,20 @@ docs-build:
 docs-serve: docs-build
     npx serve .docs-dist
 
+# Check internal doc links across the unified site (requires lychee: brew install lychee)
+docs-check-links: docs-build
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if ! command -v lychee >/dev/null 2>&1; then
+      echo "lychee not installed. Install with: brew install lychee" >&2
+      exit 127
+    fi
+    lychee --offline --no-progress \
+      --root-dir "$PWD/.docs-dist" \
+      --exclude '\.(css|js|mjs|svg|png|jpe?g|ico|woff2?|map|json|xml|webp|avif|gif)$' \
+      --exclude 'pagefind/' \
+      '.docs-dist/chant/**/*.html'
+
 # Build VS Code extension
 ext-vscode-build:
     cd editors/vscode && npm install && npm run build

lexicons/aws/docs/astro.config.mjs

@@ -1,9 +1,13 @@
 // @ts-check
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
+import rehypeBaseUrl from './src/rehype-base-url.mjs';
 
 export default defineConfig({
   base: '/chant/lexicons/aws/',
+  markdown: {
+    rehypePlugins: [[rehypeBaseUrl, { base: '/chant/lexicons/aws/', projectBase: '/chant' }]],
+  },
   integrations: [
     starlight({
       title: 'AWS CloudFormation',

lexicons/aws/docs/src/content/docs/index.mdx

@@ -17,9 +17,9 @@ npm install --save-dev @intentius/chant-lexicon-aws
 
 | Metric | Count |
 |--------|-------|
-| Resources | 1,500+ |
-| Property types | 13,000+ |
-| Services | 270+ |
+| Resources | 1592 |
+| Property types | 13357 |
+| Services | 278 |
 | Intrinsic functions | 9 |
 | Pseudo-parameters | 8 |
 | Lint rules | 32 |

lexicons/aws/docs/src/rehype-base-url.mjs

@@ -0,0 +1,68 @@
+/**
+ * Rehype plugin: prepend a configured `base` to root-relative `<a href>` attributes.
+ *
+ * Astro/Starlight only base-prefixes its own internal navigation (sidebar `link:`
+ * entries, `slug:` entries). Root-relative links written in MD/MDX content body
+ * — e.g. `[AWS](/lexicons/aws/)` — are emitted verbatim and 404 in production
+ * when the site is served from a non-root `base`.
+ *
+ * This plugin walks the HAST tree, finds `<a>` elements whose href starts with
+ * `/` (single leading slash, not `//`), and prepends the site's `base`. It
+ * idempotently skips hrefs that already start with the site's own base or the
+ * project-wide base.
+ *
+ * @typedef {Object} RehypeBaseUrlOptions
+ * @property {string} base - Site base, e.g. "/chant" or "/chant/lexicons/aws". Trailing/leading slashes optional.
+ * @property {string} [projectBase] - Project-wide base used to detect already-correctly-prefixed cross-site links.
+ */
+
+const PROTOCOL_RE = /^[a-z][a-z0-9+.-]*:/i;
+
+function normalizeBase(value) {
+  return "/" + value.replace(/^\/+|\/+$/g, "");
+}
+
+/**
+ * @param {RehypeBaseUrlOptions} opts
+ */
+export default function rehypeBaseUrl(opts) {
+  const base = normalizeBase(opts.base);
+  if (base === "/") {
+    return () => {};
+  }
+  const ownPrefix = base + "/";
+  const projectPrefix = opts.projectBase
+    ? normalizeBase(opts.projectBase) + "/"
+    : null;
+
+  function rewrite(node) {
+    if (
+      node &&
+      node.type === "element" &&
+      node.tagName === "a" &&
+      node.properties &&
+      typeof node.properties.href === "string"
+    ) {
+      const href = node.properties.href;
+      if (
+        href.length > 0 &&
+        !href.startsWith("//") &&
+        !PROTOCOL_RE.test(href) &&
+        !href.startsWith("#") &&
+        href.startsWith("/") &&
+        href !== base &&
+        !href.startsWith(ownPrefix) &&
+        !(projectPrefix && href.startsWith(projectPrefix))
+      ) {
+        node.properties.href = base + href;
+      }
+    }
+    if (node && node.children) {
+      for (const child of node.children) rewrite(child);
+    }
+  }
+
+  return (tree) => {
+    rewrite(tree);
+  };
+}

lexicons/azure/docs/astro.config.mjs

@@ -1,9 +1,13 @@
 // @ts-check
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
+import rehypeBaseUrl from './src/rehype-base-url.mjs';
 
 export default defineConfig({
   base: '/chant/lexicons/azure/',
+  markdown: {
+    rehypePlugins: [[rehypeBaseUrl, { base: '/chant/lexicons/azure/', projectBase: '/chant' }]],
+  },
   integrations: [
     starlight({
       title: 'Azure Resource Manager',

lexicons/azure/docs/src/content/docs/index.mdx

@@ -17,9 +17,9 @@ npm install --save-dev @intentius/chant-lexicon-azure
 
 | Metric | Count |
 |--------|-------|
-| Resources | 1,900+ |
-| Property types | 300,000+ |
-| Services | 230+ |
+| Resources | 2039 |
+| Property types | 312218 |
+| Services | 243 |
 | Intrinsic functions | 9 |
 | Pseudo-parameters | 6 |
 | Lint rules | 23 |

lexicons/azure/docs/src/rehype-base-url.mjs

@@ -0,0 +1,68 @@
+/**
+ * Rehype plugin: prepend a configured `base` to root-relative `<a href>` attributes.
+ *
+ * Astro/Starlight only base-prefixes its own internal navigation (sidebar `link:`
+ * entries, `slug:` entries). Root-relative links written in MD/MDX content body
+ * — e.g. `[AWS](/lexicons/aws/)` — are emitted verbatim and 404 in production
+ * when the site is served from a non-root `base`.
+ *
+ * This plugin walks the HAST tree, finds `<a>` elements whose href starts with
+ * `/` (single leading slash, not `//`), and prepends the site's `base`. It
+ * idempotently skips hrefs that already start with the site's own base or the
+ * project-wide base.
+ *
+ * @typedef {Object} RehypeBaseUrlOptions
+ * @property {string} base - Site base, e.g. "/chant" or "/chant/lexicons/aws". Trailing/leading slashes optional.
+ * @property {string} [projectBase] - Project-wide base used to detect already-correctly-prefixed cross-site links.
+ */
+
+const PROTOCOL_RE = /^[a-z][a-z0-9+.-]*:/i;
+
+function normalizeBase(value) {
+  return "/" + value.replace(/^\/+|\/+$/g, "");
+}
+
+/**
+ * @param {RehypeBaseUrlOptions} opts
+ */
+export default function rehypeBaseUrl(opts) {
+  const base = normalizeBase(opts.base);
+  if (base === "/") {
+    return () => {};
+  }
+  const ownPrefix = base + "/";
+  const projectPrefix = opts.projectBase
+    ? normalizeBase(opts.projectBase) + "/"
+    : null;
+
+  function rewrite(node) {
+    if (
+      node &&
+      node.type === "element" &&
+      node.tagName === "a" &&
+      node.properties &&
+      typeof node.properties.href === "string"
+    ) {
+      const href = node.properties.href;
+      if (
+        href.length > 0 &&
+        !href.startsWith("//") &&
+        !PROTOCOL_RE.test(href) &&
+        !href.startsWith("#") &&
+        href.startsWith("/") &&
+        href !== base &&
+        !href.startsWith(ownPrefix) &&
+        !(projectPrefix && href.startsWith(projectPrefix))
+      ) {
+        node.properties.href = base + href;
+      }
+    }
+    if (node && node.children) {
+      for (const child of node.children) rewrite(child);
+    }
+  }
+
+  return (tree) => {
+    rewrite(tree);
+  };
+}

lexicons/docker/docs/astro.config.mjs

@@ -1,9 +1,13 @@
 // @ts-check
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
+import rehypeBaseUrl from '../../../packages/core/src/codegen/rehype-base-url.mjs';
 
 export default defineConfig({
   base: '/chant/lexicons/docker/',
+  markdown: {
+    rehypePlugins: [[rehypeBaseUrl, { base: '/chant/lexicons/docker/', projectBase: '/chant' }]],
+  },
   integrations: [
     starlight({
       title: 'Docker',

lexicons/flyway/docs/astro.config.mjs

@@ -1,9 +1,13 @@
 // @ts-check
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
+import rehypeBaseUrl from './src/rehype-base-url.mjs';
 
 export default defineConfig({
   base: '/chant/lexicons/flyway/',
+  markdown: {
+    rehypePlugins: [[rehypeBaseUrl, { base: '/chant/lexicons/flyway/', projectBase: '/chant' }]],
+  },
   integrations: [
     starlight({
       title: 'Flyway',

lexicons/flyway/docs/src/rehype-base-url.mjs

@@ -0,0 +1,68 @@
+/**
+ * Rehype plugin: prepend a configured `base` to root-relative `<a href>` attributes.
+ *
+ * Astro/Starlight only base-prefixes its own internal navigation (sidebar `link:`
+ * entries, `slug:` entries). Root-relative links written in MD/MDX content body
+ * — e.g. `[AWS](/lexicons/aws/)` — are emitted verbatim and 404 in production
+ * when the site is served from a non-root `base`.
+ *
+ * This plugin walks the HAST tree, finds `<a>` elements whose href starts with
+ * `/` (single leading slash, not `//`), and prepends the site's `base`. It
+ * idempotently skips hrefs that already start with the site's own base or the
+ * project-wide base.
+ *
+ * @typedef {Object} RehypeBaseUrlOptions
+ * @property {string} base - Site base, e.g. "/chant" or "/chant/lexicons/aws". Trailing/leading slashes optional.
+ * @property {string} [projectBase] - Project-wide base used to detect already-correctly-prefixed cross-site links.
+ */
+
+const PROTOCOL_RE = /^[a-z][a-z0-9+.-]*:/i;
+
+function normalizeBase(value) {
+  return "/" + value.replace(/^\/+|\/+$/g, "");
+}
+
+/**
+ * @param {RehypeBaseUrlOptions} opts
+ */
+export default function rehypeBaseUrl(opts) {
+  const base = normalizeBase(opts.base);
+  if (base === "/") {
+    return () => {};
+  }
+  const ownPrefix = base + "/";
+  const projectPrefix = opts.projectBase
+    ? normalizeBase(opts.projectBase) + "/"
+    : null;
+
+  function rewrite(node) {
+    if (
+      node &&
+      node.type === "element" &&
+      node.tagName === "a" &&
+      node.properties &&
+      typeof node.properties.href === "string"
+    ) {
+      const href = node.properties.href;
+      if (
+        href.length > 0 &&
+        !href.startsWith("//") &&
+        !PROTOCOL_RE.test(href) &&
+        !href.startsWith("#") &&
+        href.startsWith("/") &&
+        href !== base &&
+        !href.startsWith(ownPrefix) &&
+        !(projectPrefix && href.startsWith(projectPrefix))
+      ) {
+        node.properties.href = base + href;
+      }
+    }
+    if (node && node.children) {
+      for (const child of node.children) rewrite(child);
+    }
+  }
+
+  return (tree) => {
+    rewrite(tree);
+  };
+}

lexicons/gcp/docs/astro.config.mjs

@@ -1,9 +1,13 @@
 // @ts-check
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
+import rehypeBaseUrl from './src/rehype-base-url.mjs';
 
 export default defineConfig({
   base: '/chant/lexicons/gcp/',
+  markdown: {
+    rehypePlugins: [[rehypeBaseUrl, { base: '/chant/lexicons/gcp/', projectBase: '/chant' }]],
+  },
   integrations: [
     starlight({
       title: 'GCP Config Connector',

lexicons/gcp/docs/src/content/docs/index.mdx

@@ -40,14 +40,14 @@ The lexicon provides **300+ resource types** across Compute, Storage, IAM, Netwo
 
 | Metric | Count |
 |--------|-------|
-| Resources | 450+ |
-| Property types | 1,200+ |
-| Services | 120+ |
+| Resources | 453 |
+| Property types | 1257 |
+| Services | 124 |
 | Intrinsic functions | 0 |
 | Pseudo-parameters | 3 |
 | Lint rules | 26 |
 
-**Lexicon version:** 0.1.5  
+**Lexicon version:** 0.1.6  
 **Namespace:** `GCP`
 
 - [Getting Started](./getting-started)