next-validate-link

next-validate-link

next-validate-link is a simple tool designed to verify that all Markdown links within your project are valid and up-to-date. It helps prevent broken links in your documentation or content repositories.

By default, next-validate-link assumes a Next.js routing structure. To use it with Nuxt, you must provide the nuxt framework preset to the scanURLs function. This tells the scanner how to identify and scan your application's pages.

import { scanURLs } from 'next-validate-link';

const scanned = await scanURLs({
  preset: 'nuxt',
});
// validate with the scanned urls

To use next-validate-link within a Fumadocs project, you can run the validation script (e.g., ./lint.ts) as part of your linting process or within a GitHub Action to ensure link integrity during CI/CD.

bun run ./lint.ts

To validate links, use readFiles to get your content and validateFiles to check them against the scanned URLs. Use printErrors to output the results. Setting the second argument of printErrors to true will cause the process to exit with code 1 if errors are detected, which is useful for CI/CD linting or build steps.

import { printErrors, validateFiles, readFiles } from 'next-validate-link';

// Assuming 'scanned' was generated via scanURLs
printErrors(
  await validateFiles(await readFiles('content/**/*.{md,mdx}'), {
    scanned,
  }),
  // exit with code 1 if errors detected
  true,
);

Install the package via npm to start validating links in your Markdown files.

npm i next-validate-link

By default, next-validate-link assumes a Next.js routing structure. To use it with Astro, you must provide the astro framework preset to the scanURLs function. This tells the scanner how to correctly identify and scan your Astro pages.

import { scanURLs } from 'next-validate-link';

const scanned = await scanURLs({
  preset: 'astro',
});
// validate with the scanned urls

The tool checks relative URLs (e.g., [Test](./my-page)) by default. To make these work, you must provide context so the tool can resolve them. You can either:

• Define file.url in the input file objects.
• Provide a pathToUrl option.
• Provide a baseUrl option.

To disable this check entirely, set checkRelativeUrls: false.

import { readFiles, validateFiles } from "next-validate-link";

// Disable relative URL checking
await validateFiles(await readFiles('content/**/*.{md,mdx}'), {
  checkRelativeUrls: false,
});

The onNode property in MarkdownConfig allows you to define custom logic for finding URLs within the Markdown/MDX Abstract Syntax Tree (AST).

If you do not provide onNode, the validator uses a default implementation that:

1. Extracts url from standard Markdown link nodes.
2. Scans MDX JSX elements (mdxJsxFlowElement or mdxJsxTextElement) if their name exists in the components configuration and the attribute name matches one of the specified attributes.

If you provide onNode, you take full responsibility for returning an object containing an array of strings: { hrefs: string[] } for every node you want to scan.

By default, the tool focuses on internal links. To validate external URLs, enable checkExternal in the validateFiles options. You can provide a custom validate function to define what constitutes a successful external link check.

import { validateFiles, readFiles } from 'next-validate-link';

// Simple external check
await validateFiles(await readFiles('content/**/*.{md,mdx}'), {
  scanned,
  checkExternal: true,
});

// Custom external validation logic
await validateFiles(await readFiles('content/**/*.{md,mdx}'), {
  scanned,
  checkExternal: {
    async validate(url) {
      return { success: true };
    }
  },
});

You can restrict which queries and URL fragments are considered valid for specific paths using the meta option in scanURLs.

import { scanURLs } from 'next-validate-link';

const scanned = await scanURLs({
  meta: {
    '/': {
      // allowed fragment strings
      hashes: ['fragment'],
      // allowed queries
      queries: [
        {
          search: 'fumadocs',
        },
      ],
    },
  },
});

To validate relative file paths (e.g., [Test](./another-file.md)), use the checkRelativePaths option in validateFiles. Supported values:

• exists: Checks if the referenced file exists on the file system.
• as-url: Resolves the file path as a URL. Requires providing a pathToUrl function that converts a file path to a valid URL/pathname.
• false (default): Ignores relative paths.

import path from "node:path";
import { readFiles, validateFiles } from "next-validate-link";

// Check if files exist
await validateFiles(await readFiles('content/**/*.{md,mdx}'), {
  checkRelativePaths: 'exists',
});

// Resolve paths as URLs
await validateFiles(await readFiles('content/**/*.{md,mdx}'), {
  checkRelativePaths: 'as-url',
  pathToUrl: (file) => {
    return path.dirname(file);
  },
});