feat(mdx): add remark plugin for automatic link transformation (#1003)

## What

Adds automatic link transformation for aggregated documentation from
multiple sources. Internal links are transformed based on content
section:
- `/docs/...` in ATK content → `/asset-tokenization-kit/...`
- `/docs/...` in SDK content → `/sdk/...`
- `/docs/...` in blockchain-platform content →
`/blockchain-platform/...`

Also adds a link validation script that runs in CI to catch broken
internal links.

## Why

Documentation is aggregated from multiple sources (ATK via Docker, SDK
from npm packages, blockchain-platform static content). Each source may
use different link conventions (e.g., `/docs/...`) that need to be
normalized for the unified documentation site.

## How

- **remark-transform-links.ts**: A remark plugin that detects the
content section from file path and applies section-specific URL
transformations. Handles both standard markdown links and MDX JSX
component `href` attributes.
- **check-links.ts**: Script to validate internal links at build time
- **migrate-links.ts**: Utility script to assist with link format
migration

## Files Changed

- `src/lib/remark-transform-links.ts` - Core remark plugin (new)
- `source.config.ts` - Plugin integration
- `scripts/check-links.ts` - Link validation script (new)
- `scripts/migrate-links.ts` - Link migration utility (new)
- `.github/workflows/qa.yml` - Added link checking step
- `package.json` - Added dependencies and script
- `.gitignore` - Ignore generated directories

## Breaking Changes

None

## Testing

- [x] Type checking passes
- [x] Link transformation working in dev server
- [x] Glossary links correctly resolve to
`/documentation/asset-tokenization-kit/executive-overview/glossary`

## Related Linear Issues

None

## Summary by Sourcery

Introduce automatic link transformation and validation for aggregated
documentation content and update content sourcing configuration.

New Features:
- Add a remark plugin to normalize internal documentation links based on
their content section.
- Add a link validation script to check internal links across MDX
documentation files at build/CI time.
- Add a link migration utility to bulk-update legacy internal links to
the new base path format.

Enhancements:
- Wire the new remark link transformation plugin into the MDX
configuration so all docs content uses normalized URLs.
- Adjust Docker content sourcing for the asset tokenization kit to use
the updated content image and export additional docs assets.

Build:
- Add package scripts and dependencies required for link checking and
migration, and update the Bun lockfile accordingly.

CI:
- Extend the QA GitHub Actions workflow to run internal link validation
on pushes and pull requests.

Chores:
- Update docker-compose service configuration for asset-tokenization-kit
content handling and adjust .gitignore entries.









<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds a remark plugin that rewrites internal links per content section
and a CI link checker to catch broken URLs across aggregated docs.

- **New Features**
- Remark plugin transforms internal links (/docs, /api) to section paths
(/asset-tokenization-kit, /sdk, /blockchain-platform,
/asset-tokenization-kit-legacy) for both Markdown links and MDX hrefs.
- Link validation script (bun run check-links) scans MDX files and runs
in the QA workflow.
- Integrated plugin in MDX config so all sourced docs use normalized
URLs.

- **Migration**
  - Preview changes: bun scripts/migrate-links.ts --dry-run
  - Apply changes: bun scripts/migrate-links.ts

<sup>Written for commit 768afcc.
Summary will update automatically on new commits.</sup>

<!-- End of auto-generated description by cubic. -->

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: roderik

.github/workflows/qa.yml

@@ -162,6 +162,11 @@ jobs:
           NEXT_PUBLIC_POSTHOG_KEY: ${{ secrets.NEXT_PUBLIC_POSTHOG_KEY }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Check links
+        if: github.event_name == 'pull_request' || github.event_name == 'push'
+        run: |
+          bun run check-links
+
       - name: Build Docker container
         if: github.event_name == 'pull_request' || github.event_name == 'push'
         run: |

.gitignore

@@ -34,3 +34,7 @@ content/docs/sdk/*
 
 public/images/screenshots/*
 public/atk
+public/docs
+
+# AI planning docs
+plans/

bun.lock

@@ -11,6 +11,7 @@
     "lint": "eslint",
     "check-types": "tsc --noEmit",
     "format": "prettier --write .",
+    "check-links": "bun scripts/check-links.ts",
     "generate-sdk-docs": "bun scripts/generate-sdk-docs.ts",
     "docker": "bash -c \"docker buildx build . --provenance true --sbom true --platform=linux/amd64,linux/arm64 -t ghcr.io/settlemint/btp-docs:${VERSION:-7.0.0-dev.$(date +%s)} --push --progress=plain\""
   },
@@ -41,6 +42,7 @@
     "lucide-react": "0.559.0",
     "mermaid": "11.12.2",
     "next": "16.0.8",
+    "next-validate-link": "1.6.3",
     "posthog-js": "1.304.0",
     "react": "19.2.1",
     "react-dom": "19.2.1",
@@ -53,6 +55,7 @@
     "zod": "4.1.13"
   },
   "devDependencies": {
+    "glob": "13.0.0",
     "@tailwindcss/postcss": "4.1.17",
     "@types/mdx": "2.0.13",
     "@types/node": "25.0.0",
@@ -66,4 +69,4 @@
     "@eslint/eslintrc": "3.3.3",
     "prettier": "3.7.4"
   }
-}
+}

package.json

@@ -0,0 +1,69 @@
+import { scanURLs, validateFiles, printErrors } from "next-validate-link";
+import { source } from "../src/lib/source";
+import { glob } from "glob";
+
+const BASE_PATH = "/documentation";
+
+async function getFiles(): Promise<string[]> {
+  return glob("content/docs/**/*.mdx", { cwd: process.cwd() });
+}
+
+async function checkLinks() {
+  console.log("[Check Links] Starting link validation...");
+
+  const pages = source.getPages();
+  console.log(`[Check Links] Found ${pages.length} pages in source`);
+
+  // Build the URL map for validation
+  // For catch-all routes [[...slug]], value should be string[] directly
+  const populate: Record<
+    string,
+    Array<{ value: string[]; hashes: string[] }>
+  > = {
+    "[[...slug]]": pages.map((page) => ({
+      value: page.slugs,
+      hashes: [], // Skip heading validation for now
+    })),
+  };
+
+  const scanned = await scanURLs({
+    preset: "next",
+    populate,
+  });
+
+  const files = await getFiles();
+  console.log(`[Check Links] Validating ${files.length} MDX files`);
+
+  const errors = await validateFiles(files, {
+    scanned,
+    pathToUrl: (path: string) => {
+      // Transform file path to URL
+      const slug = path
+        .replace("content/docs/", "")
+        .replace(/\.mdx?$/, "")
+        .replace(/\/index$/, "");
+      return `${BASE_PATH}/${slug}`;
+    },
+    markdown: {
+      components: {
+        Card: { attributes: ["href"] },
+        Cards: { attributes: ["href"] },
+      },
+    },
+    checkExternal: false, // External links checked separately
+    checkRelativePaths: "as-url",
+  });
+
+  if (errors.length > 0) {
+    console.log(`\n[Check Links] Found ${errors.length} link errors:\n`);
+    printErrors(errors, true);
+    process.exit(1);
+  }
+
+  console.log("[Check Links] All links validated successfully!");
+}
+
+checkLinks().catch((error) => {
+  console.error("[Check Links] Error:", error);
+  process.exit(1);
+});

scripts/check-links.ts

@@ -0,0 +1,108 @@
+import { glob } from "glob";
+import { readFile, writeFile } from "node:fs/promises";
+
+const BASE_PATH = "/documentation";
+const DRY_RUN = process.argv.includes("--dry-run");
+
+/**
+ * Migrate internal links in MDX files to use the basePath prefix.
+ *
+ * This script finds all root-relative links that don't already have
+ * the /documentation/ prefix and adds it.
+ *
+ * IMPORTANT: This script is designed for one-time migration of legacy content.
+ * The remark-transform-links plugin handles link transformation at build time,
+ * so this script should NOT be run on content that will be processed by that plugin.
+ * Running both would result in double-prefixed links.
+ *
+ * Usage:
+ *   bun scripts/migrate-links.ts          # Apply changes
+ *   bun scripts/migrate-links.ts --dry-run # Preview changes without writing
+ */
+
+// Type for replacement functions that match String.replace callback signature
+type ReplaceFn = (substring: string, ...args: string[]) => string;
+
+// Patterns to transform (root-relative without basePath)
+// These patterns match links that start with / but NOT /documentation/, /images/, /api/, etc.
+const LINK_PATTERNS: Array<{ regex: RegExp; replace: ReplaceFn }> = [
+  // Markdown links: [text](/path) - but not [text](/documentation/...) or [text](/images/...) etc.
+  {
+    regex:
+      /(\[[^\]]+\]\()\/(?!documentation\/|images\/|api\/|ingest\/|_next\/)([^)]+\))/g,
+    replace: (_match: string, prefix: string, path: string) =>
+      `${prefix}${BASE_PATH}/${path}`,
+  },
+  // JSX href in Card/other components: href="/path" - but not href="/documentation/..." etc.
+  {
+    regex:
+      /href="\/(?!documentation\/|images\/|api\/|ingest\/|_next\/)([^"]+)"/g,
+    replace: (_match: string, path: string) => `href="${BASE_PATH}/${path}"`,
+  },
+];
+
+async function migrateLinks() {
+  console.log("[Migrate Links] Starting link migration...");
+  if (DRY_RUN) {
+    console.log("[Migrate Links] DRY RUN MODE - no files will be modified\n");
+  }
+
+  const files = await glob("content/docs/**/*.mdx", { cwd: process.cwd() });
+  console.log(`[Migrate Links] Found ${files.length} MDX files to scan\n`);
+
+  let totalChanges = 0;
+  let filesChanged = 0;
+
+  for (const file of files) {
+    const content = await readFile(file, "utf-8");
+    let newContent = content;
+    let fileChanges = 0;
+
+    for (const pattern of LINK_PATTERNS) {
+      const matches = [...newContent.matchAll(pattern.regex)];
+      fileChanges += matches.length;
+
+      newContent = newContent.replace(pattern.regex, pattern.replace);
+    }
+
+    if (fileChanges > 0) {
+      filesChanged++;
+      totalChanges += fileChanges;
+
+      if (DRY_RUN) {
+        console.log(`[DRY RUN] ${file}: ${fileChanges} links would be updated`);
+
+        // Show the actual changes for this file
+        const originalLines = content.split("\n");
+        const newLines = newContent.split("\n");
+
+        for (let i = 0; i < originalLines.length; i++) {
+          if (originalLines[i] !== newLines[i]) {
+            console.log(`  Line ${i + 1}:`);
+            console.log(`    - ${originalLines[i].trim()}`);
+            console.log(`    + ${newLines[i].trim()}`);
+          }
+        }
+        console.log("");
+      } else {
+        await writeFile(file, newContent);
+        console.log(`[Migrate Links] ${file}: ${fileChanges} links updated`);
+      }
+    }
+  }
+
+  console.log(
+    `\n[Migrate Links] Summary: ${totalChanges} links ${DRY_RUN ? "would be" : ""} updated across ${filesChanged} files`
+  );
+
+  if (DRY_RUN && totalChanges > 0) {
+    console.log(
+      "\n[Migrate Links] Run without --dry-run to apply these changes"
+    );
+  }
+}
+
+migrateLinks().catch((error) => {
+  console.error("[Migrate Links] Error:", error);
+  process.exit(1);
+});

scripts/migrate-links.ts

@@ -3,13 +3,14 @@ import {
   defineDocs,
   frontmatterSchema,
   metaSchema,
-} from 'fumadocs-mdx/config';
+} from "fumadocs-mdx/config";
 import { z } from "zod";
+import { remarkTransformLinks } from "@/lib/remark-transform-links";
 
 // You can customise Zod schemas for frontmatter and `meta.json` here
 // see https://fumadocs.dev/docs/mdx/collections
 export const docs = defineDocs({
-  dir: 'content/docs',
+  dir: "content/docs",
   docs: {
     schema: frontmatterSchema.extend({
       /**
@@ -40,6 +41,6 @@ export const docs = defineDocs({
 
 export default defineConfig({
   mdxOptions: {
-    // MDX options
+    remarkPlugins: [remarkTransformLinks],
   },
 });