Merge pull request #36 from objectstack-ai/copilot/validate-links-integration

Author: hotlong

content/docs/integrations/meta.json

@@ -0,0 +1,6 @@
+{
+  "title": "Integrations",
+  "pages": [
+    "validate-links"
+  ]
+}

content/docs/integrations/validate-links.mdx

@@ -0,0 +1,95 @@
+---
+title: Validate Links
+description: Ensure your links are correct in documentation files.
+---
+
+# Validate Links
+
+Ensure your links are correct in your documentation.
+
+## Setup
+
+<Callout type="info">
+You can use [`next-validate-link`](https://next-validate-link.vercel.app) to validate your links in content files.
+</Callout>
+
+<Callout type="warn">
+This guide is mainly for **Fumadocs MDX**, see the docs of `next-validate-link` for other setups.
+</Callout>
+
+Create a script:
+
+```ts title="scripts/lint.ts"
+import { type FileObject, printErrors, scanURLs, validateFiles } from 'next-validate-link';
+import type { InferPageType } from 'fumadocs-core/source';
+import { source } from '@/lib/source';
+
+async function checkLinks() {
+  const scanned = await scanURLs({
+    // pick a preset for your React framework
+    preset: 'next',
+    populate: {
+      'docs/[[...slug]]': source.getPages().map((page) => {
+        return {
+          value: {
+            slug: page.slugs,
+          },
+          hashes: getHeadings(page),
+        };
+      }),
+    },
+  });
+
+  printErrors(
+    await validateFiles(await getFiles(), {
+      scanned,
+      // check `href` attributes in different MDX components
+      markdown: {
+        components: {
+          Card: { attributes: ['href'] },
+        },
+      },
+      // check relative paths
+      checkRelativePaths: 'as-url',
+    }),
+    true,
+  );
+}
+
+function getHeadings({ data }: InferPageType<typeof source>): string[] {
+  return data.toc.map((item) => item.url.slice(1));
+}
+
+function getFiles() {
+  const promises = source.getPages().map(
+    async (page): Promise<FileObject> => ({
+      path: page.absolutePath,
+      content: await page.data.getText('raw'),
+      url: page.url,
+      data: page.data,
+    }),
+  );
+
+  return Promise.all(promises);
+}
+
+void checkLinks();
+```
+
+## Running Lint
+
+<Callout type="info">
+To access the `source` object outside of app runtime, configure [Fumadocs MDX Loader](/docs/mdx/loader/bun) first.
+</Callout>
+
+Then, run the script to validate links:
+
+```bash
+bun ./scripts/lint.ts
+```
+
+<Callout type="warn">
+For Node.js, you might need to configure `tsconfig-paths`, TypeScript transpiling, and [Fumadocs MDX Loader](/docs/mdx/loader/node).
+
+Without special reasons, using Bun or [`tsx`](https://github.com/privatenumber/tsx) would be simpler.
+</Callout>

content/docs/meta.json

@@ -4,6 +4,7 @@
     "index",
     "getting-started",
     "components",
+    "integrations",
     "development-plan"
   ]
 }