validate-mdx-links 1.0.8 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# validate-mdx-links
+
+## 1.2.0
+
+### Features
+
+- Auto-detects content-based frameworks (Fumadocs). Projects with `content/**/*.mdx` files get proper URL scanning without Next.js `app/` or `pages/` routes.
+- `--content-dir` CLI flag to set the content directory for URL scanning.
+- `--files` defaults to `${contentDir}/**/*.mdx` when `--content-dir` is set without `--files`.
+- Framework detection reads `package.json` dependencies (`fumadocs-core`, `fumadocs-mdx`, `fumadocs-ui`, `next`) before falling back to directory heuristics.
+- Extracts headings for `#id` fragment validation via `github-slugger` — matches Fumadocs/GitHub ID generation (duplicate tracking, non-ASCII preservation).
+- TanStack Router route scanning — parses `src/routes/` using TanStack conventions (`_prefix` layout segments stripped, `$` splat routes become fallback regex patterns, `[.]` literal dots). Gated on `@tanstack/react-start`, `@tanstack/start`, or `@tanstack/react-router` in `package.json`.
+- Resolves relative links (`./sibling-post`, `../other-dir/page`) in content-based projects via `pathToUrl`.
+
+### API Changes
+
+- `ValidateMdxLinksOptions` accepts a new optional `contentDir: string` field.
+
+## 1.1.0
+
+Initial public release. Next.js App Router and Nextra link validation with false-positive filtering for relative links.

package/README.md

@@ -6,7 +6,7 @@ Handles relative links, with and without `.mdx` extension, and treats `page.mdx`
 ## Install
 
 ```bash
-pnpm add -D validate-mdx-links
+bun add -D validate-mdx-links
 ```
 
 ## CLI

package/dist/bin.js

@@ -8,6 +8,7 @@
  *
  * Usage:
  * validate-mdx-links --cwd <path> --files "content/**\/*.mdx" --verbose
+ * validate-mdx-links --files "content/docs/**\/*.mdx" --content-dir content
  */
 import { parseArgs } from "node:util";
 import { validateMdxLinks, printErrors } from "./index.js";
@@ -18,6 +19,7 @@ const args = (() => {
                 cwd: { type: "string", default: process.cwd() },
                 files: { type: "string" },
                 verbose: { type: "boolean", default: false, allowNegative: true },
+                "content-dir": { type: "string" },
                 help: { type: "boolean", default: false },
             },
             strict: true,
@@ -30,20 +32,22 @@ const args = (() => {
         process.exit(1);
     }
 })();
-const { values: { help, cwd, verbose, files }, } = args;
+const { values: { help, cwd, verbose, files, "content-dir": contentDir }, } = args;
 if (help) {
-    console.log('Usage: validate-mdx-links --cwd <path> --files "content/**/*.mdx" --verbose');
+    console.log('Usage: validate-mdx-links --cwd <path> --files "content/**/*.mdx" [--content-dir content] --verbose');
     process.exit(0);
 }
-if (!files) {
-    console.error("No files passed. Please pass the --files option.");
+const resolvedFiles = files ?? (contentDir ? `${contentDir}/**/*.mdx` : undefined);
+if (!resolvedFiles) {
+    console.error("No files passed. Please pass --files or --content-dir.");
     process.exit(1);
 }
 try {
     const errors = await validateMdxLinks({
         cwd,
-        files,
+        files: resolvedFiles,
         verbose,
+        contentDir,
     });
     if (errors.length > 0) {
         printErrors(errors);

package/dist/index.js

@@ -1,9 +1,187 @@
-import { globSync } from "node:fs";
+import { existsSync, globSync, readFileSync } from "node:fs";
 import { stat } from "node:fs/promises";
-import { dirname, resolve, basename } from "node:path";
+import { dirname, resolve, basename, relative } from "node:path";
+import GithubSlugger from "github-slugger";
 import { scanURLs, validateFiles, } from "next-validate-link";
 export { printErrors } from "next-validate-link";
-export async function validateMdxLinks({ cwd = process.cwd(), files: filesGlob, verbose = false, }) {
+function readDeps(cwd) {
+    try {
+        const pkg = JSON.parse(readFileSync(resolve(cwd, "package.json"), "utf-8"));
+        return new Set([
+            ...Object.keys(pkg.dependencies ?? {}),
+            ...Object.keys(pkg.devDependencies ?? {}),
+        ]);
+    }
+    catch {
+        return new Set();
+    }
+}
+function detectFramework(cwd, deps) {
+    const isFumadocs = deps.has("fumadocs-core") || deps.has("fumadocs-mdx") || deps.has("fumadocs-ui");
+    // If fumadocs is present, prefer content-based scanning
+    if (isFumadocs) {
+        // Find content dir: check common locations
+        for (const dir of ["content", "content/docs"]) {
+            if (existsSync(resolve(cwd, dir))) {
+                const mdxFiles = globSync(`${dir}/**/*.mdx`, { cwd });
+                if (mdxFiles.length > 0) {
+                    return { type: "content", contentDir: dir };
+                }
+            }
+        }
+    }
+    // Check for Next.js dirs (also validates against package.json if available)
+    const nextDirs = ["app", "src/app", "pages", "src/pages"];
+    for (const dir of nextDirs) {
+        if (existsSync(resolve(cwd, dir))) {
+            return { type: "nextjs" };
+        }
+    }
+    // Fallback: content dir with MDX files (no fumadocs dep but has content)
+    if (existsSync(resolve(cwd, "content"))) {
+        const mdxFiles = globSync("content/**/*.mdx", { cwd });
+        if (mdxFiles.length > 0) {
+            return { type: "content", contentDir: "content" };
+        }
+    }
+    return { type: "nextjs" };
+}
+const HEADING_REGEX = /^#{1,6}\s+(.+)$/gm;
+function extractHashes(content) {
+    const slugger = new GithubSlugger();
+    const hashes = [];
+    let match;
+    while ((match = HEADING_REGEX.exec(content)) !== null) {
+        hashes.push(slugger.slug(match[1]));
+    }
+    return hashes;
+}
+/**
+ * Convert a TanStack Router file path to a URL path.
+ * - Strips `_prefix` layout segments (pathless routes)
+ * - `index.tsx` → parent path
+ * - `$.tsx` → null (handled as fallbackUrl)
+ * - `[.]` → literal dot
+ * - Strips extensions
+ * Returns null for splat routes (caller handles as fallbackUrl),
+ * or undefined for files that shouldn't produce routes (layouts, tests, api).
+ */
+function tanstackRouteToUrl(filePath, routesDir) {
+    const rel = relative(routesDir, filePath);
+    // Skip root layout, test files, api routes
+    if (rel.startsWith("__") ||
+        rel.includes(".test.") ||
+        rel.startsWith("api/") ||
+        rel.startsWith("api\\")) {
+        return undefined;
+    }
+    // Strip extension
+    const withoutExt = rel.replace(/\.(tsx?|jsx?)$/, "");
+    const segments = withoutExt.split(/[/\\]/);
+    const urlSegments = [];
+    let isSplat = false;
+    for (const seg of segments) {
+        // Layout files (e.g. _landing.tsx) — skip as a route themselves
+        // but as directories they wrap children
+        if (seg.startsWith("_")) {
+            continue;
+        }
+        // Splat route
+        if (seg === "$") {
+            isSplat = true;
+            continue;
+        }
+        // Dynamic param like $slug — skip, produces fallback
+        if (seg.startsWith("$")) {
+            isSplat = true;
+            continue;
+        }
+        // index → parent
+        if (seg === "index") {
+            continue;
+        }
+        // [.] → literal dot
+        let processed = seg.replace(/\[\.\]/g, ".");
+        urlSegments.push(processed);
+    }
+    if (isSplat) {
+        return null; // caller creates fallbackUrl regex
+    }
+    return "/" + urlSegments.join("/") || "/";
+}
+function scanRoutes(routesDir, cwd, urls, fallbackUrls) {
+    const absRoutesDir = resolve(cwd, routesDir);
+    if (!existsSync(absRoutesDir))
+        return;
+    const routeFiles = globSync(`${routesDir}/**/*.{tsx,ts,jsx,js}`, { cwd });
+    for (const file of routeFiles) {
+        const result = tanstackRouteToUrl(file, routesDir);
+        if (result === undefined) {
+            // Skip (layout, test, api)
+            continue;
+        }
+        if (result === null) {
+            // Splat route — build a regex fallback from the non-splat prefix
+            const rel = relative(routesDir, file).replace(/\.(tsx?|jsx?)$/, "");
+            const segments = rel.split(/[/\\]/);
+            const prefixSegments = [];
+            for (const seg of segments) {
+                if (seg.startsWith("_"))
+                    continue;
+                if (seg === "$" || seg.startsWith("$") || seg === "index")
+                    break;
+                prefixSegments.push(seg.replace(/\[\.\]/g, "."));
+            }
+            const prefix = "/" + prefixSegments.join("/");
+            const pattern = new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(/.*)?$`);
+            fallbackUrls.push({ url: pattern, meta: {} });
+            continue;
+        }
+        if (!urls.has(result)) {
+            urls.set(result, {});
+        }
+    }
+}
+function contentPathToUrl(filePath, contentDir) {
+    let urlPath = "/" + relative(contentDir, filePath);
+    urlPath = urlPath.replace(/\.mdx$/, "");
+    if (urlPath.endsWith("/index")) {
+        urlPath = urlPath.slice(0, -"/index".length) || "/";
+    }
+    return urlPath;
+}
+function buildContentScanResult(contentDir, cwd, verbose, deps) {
+    const urls = new Map();
+    const fallbackUrls = [];
+    const mdxFiles = globSync(`${contentDir}/**/*.mdx`, { cwd });
+    for (const file of mdxFiles) {
+        const urlPath = contentPathToUrl(file, contentDir);
+        const content = readFileSync(resolve(cwd, file), "utf-8");
+        const hashes = extractHashes(content);
+        urls.set(urlPath, { hashes: hashes.length > 0 ? hashes : undefined });
+    }
+    // Scan TanStack Router routes if TanStack Start is a dependency
+    const isTanStack = deps?.has("@tanstack/react-start") ||
+        deps?.has("@tanstack/start") ||
+        deps?.has("@tanstack/react-router");
+    if (isTanStack) {
+        for (const routesDir of ["src/routes", "app/routes"]) {
+            scanRoutes(routesDir, cwd, urls, fallbackUrls);
+        }
+    }
+    if (verbose) {
+        console.log("\n" +
+            "Scanned content routes:\n" +
+            [...urls.keys()].map((x) => `"${x}"`).join(", ") +
+            (fallbackUrls.length > 0
+                ? "\nFallback patterns:\n" +
+                    fallbackUrls.map((x) => `${x.url}`).join(", ")
+                : "") +
+            "\n");
+    }
+    return { urls, fallbackUrls };
+}
+export async function validateMdxLinks({ cwd = process.cwd(), files: filesGlob, verbose = false, contentDir, }) {
     const originalCwd = process.cwd();
     process.chdir(cwd);
     const files = globSync(filesGlob);
@@ -14,16 +192,37 @@ export async function validateMdxLinks({ cwd = process.cwd(), files: filesGlob,
     else if (verbose) {
         console.log(`Found ${files.length} markdown files to validate.\n`);
     }
-    const scanned = await scanURLs();
-    if (verbose) {
-        console.log("\n" +
-            "Scanned routes from the file system:\n" +
-            [...scanned.urls.keys(), ...scanned.fallbackUrls.map((x) => x.url)]
-                .map((x) => `"${x}"`)
-                .join(", ") +
-            "\n");
+    let scanned;
+    let effectiveContentDir = contentDir;
+    const deps = readDeps(cwd);
+    if (contentDir) {
+        scanned = buildContentScanResult(contentDir, cwd, verbose, deps);
     }
-    const validations = await validateFiles(files, { scanned });
+    else {
+        const framework = detectFramework(cwd, deps);
+        if (framework.type === "content") {
+            effectiveContentDir = framework.contentDir;
+            scanned = buildContentScanResult(framework.contentDir, cwd, verbose, deps);
+        }
+        else {
+            scanned = await scanURLs();
+            if (verbose) {
+                console.log("\n" +
+                    "Scanned routes from the file system:\n" +
+                    [
+                        ...scanned.urls.keys(),
+                        ...scanned.fallbackUrls.map((x) => x.url),
+                    ]
+                        .map((x) => `"${x}"`)
+                        .join(", ") +
+                    "\n");
+            }
+        }
+    }
+    const pathToUrl = effectiveContentDir
+        ? (filePath) => contentPathToUrl(filePath, effectiveContentDir)
+        : undefined;
+    const validations = await validateFiles(files, { scanned, pathToUrl });
     const withoutFalsePositives = await Promise.all(validations.map(async ({ file, detected }) => {
         const filteredDetected = [];
         for (const error of detected) {
@@ -39,6 +238,19 @@ export async function validateMdxLinks({ cwd = process.cwd(), files: filesGlob,
                         continue;
                     }
                 }
+                // if the file is called index.mdx and is in content dir, it turns out
+                // both `./dirname/foo` and `./foo` links work and point to the same file and
+                if (basename(file) === "index.mdx") {
+                    const dir = basename(dirname(file));
+                    const isSameDir = dir === basename(dirname(link));
+                    if (isSameDir) {
+                        const path = resolve(dirname(file), "..", `${link}.mdx`);
+                        if (await fileExists(path)) {
+                            // file exists, the error is a false positive
+                            continue;
+                        }
+                    }
+                }
                 // relative links can lose their .mdx extension
                 if (!link.endsWith(".mdx")) {
                     const dest = resolve(dirname(file), `${link}.mdx`);

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "validate-mdx-links",
-  "version": "1.0.8",
+  "version": "1.2.0",
   "license": "ISC",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "validate-mdx-links": "./dist/bin.js"
+    "validate-mdx-links": "dist/bin.js"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/hasparus/eclectic.git",
+    "url": "git+https://github.com/hasparus/eclectic.git",
     "directory": "packages/validate-mdx-links"
   },
   "exports": {
@@ -20,14 +20,16 @@
     "email": "hasparus@gmail.com",
     "url": "https://haspar.us"
   },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  },
   "dependencies": {
-    "next-validate-link": "^1.4.1"
+    "github-slugger": "^2.0.0",
+    "next-validate-link": "1.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.7",
     "typescript": "^5.7.3"
-  },
-  "scripts": {
-    "build": "tsc"
   }
-}
+}

package/src/bin.ts

@@ -9,6 +9,7 @@
  *
  * Usage:
  * validate-mdx-links --cwd <path> --files "content/**\/*.mdx" --verbose
+ * validate-mdx-links --files "content/docs/**\/*.mdx" --content-dir content
  */
 import { parseArgs } from "node:util";
 import { validateMdxLinks, printErrors } from "./index.js";
@@ -20,6 +21,7 @@ const args = (() => {
         cwd: { type: "string", default: process.cwd() },
         files: { type: "string" },
         verbose: { type: "boolean", default: false, allowNegative: true },
+        "content-dir": { type: "string" },
         help: { type: "boolean", default: false },
       },
       strict: true,
@@ -33,26 +35,29 @@ const args = (() => {
 })();
 
 const {
-  values: { help, cwd, verbose, files },
+  values: { help, cwd, verbose, files, "content-dir": contentDir },
 } = args;
 
 if (help) {
   console.log(
-    'Usage: validate-mdx-links --cwd <path> --files "content/**/*.mdx" --verbose'
+    'Usage: validate-mdx-links --cwd <path> --files "content/**/*.mdx" [--content-dir content] --verbose'
   );
   process.exit(0);
 }
 
-if (!files) {
-  console.error("No files passed. Please pass the --files option.");
+const resolvedFiles = files ?? (contentDir ? `${contentDir}/**/*.mdx` : undefined);
+
+if (!resolvedFiles) {
+  console.error("No files passed. Please pass --files or --content-dir.");
   process.exit(1);
 }
 
 try {
   const errors = await validateMdxLinks({
     cwd,
-    files,
+    files: resolvedFiles,
     verbose,
+    contentDir,
   });
 
   if (errors.length > 0) {

package/src/index.ts

@@ -1,12 +1,19 @@
-import { globSync } from "node:fs";
+import { existsSync, globSync, readFileSync } from "node:fs";
 import { stat } from "node:fs/promises";
-import { dirname, resolve, basename } from "node:path";
+import { dirname, resolve, basename, relative } from "node:path";
+import GithubSlugger from "github-slugger";
 import {
   scanURLs,
   validateFiles,
   type DetectedError,
+  type ScanResult,
 } from "next-validate-link";
 
+type UrlMeta = {
+  hashes?: string[];
+  queries?: Record<string, string>[];
+};
+
 export { printErrors } from "next-validate-link";
 
 export type ValidationResult = {
@@ -18,12 +25,243 @@ export interface ValidateMdxLinksOptions {
   cwd?: string;
   files: string;
   verbose?: boolean;
+  contentDir?: string;
+}
+
+type FrameworkKind =
+  | { type: "nextjs" }
+  | { type: "content"; contentDir: string };
+
+function readDeps(cwd: string): Set<string> {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(cwd, "package.json"), "utf-8"));
+    return new Set([
+      ...Object.keys(pkg.dependencies ?? {}),
+      ...Object.keys(pkg.devDependencies ?? {}),
+    ]);
+  } catch {
+    return new Set();
+  }
+}
+
+function detectFramework(cwd: string, deps: Set<string>): FrameworkKind {
+  const isFumadocs =
+    deps.has("fumadocs-core") || deps.has("fumadocs-mdx") || deps.has("fumadocs-ui");
+
+  // If fumadocs is present, prefer content-based scanning
+  if (isFumadocs) {
+    // Find content dir: check common locations
+    for (const dir of ["content", "content/docs"]) {
+      if (existsSync(resolve(cwd, dir))) {
+        const mdxFiles = globSync(`${dir}/**/*.mdx`, { cwd });
+        if (mdxFiles.length > 0) {
+          return { type: "content", contentDir: dir };
+        }
+      }
+    }
+  }
+
+  // Check for Next.js dirs (also validates against package.json if available)
+  const nextDirs = ["app", "src/app", "pages", "src/pages"];
+  for (const dir of nextDirs) {
+    if (existsSync(resolve(cwd, dir))) {
+      return { type: "nextjs" };
+    }
+  }
+
+  // Fallback: content dir with MDX files (no fumadocs dep but has content)
+  if (existsSync(resolve(cwd, "content"))) {
+    const mdxFiles = globSync("content/**/*.mdx", { cwd });
+    if (mdxFiles.length > 0) {
+      return { type: "content", contentDir: "content" };
+    }
+  }
+
+  return { type: "nextjs" };
+}
+
+const HEADING_REGEX = /^#{1,6}\s+(.+)$/gm;
+
+function extractHashes(content: string): string[] {
+  const slugger = new GithubSlugger();
+  const hashes: string[] = [];
+  let match;
+  while ((match = HEADING_REGEX.exec(content)) !== null) {
+    hashes.push(slugger.slug(match[1]!));
+  }
+  return hashes;
+}
+
+/**
+ * Convert a TanStack Router file path to a URL path.
+ * - Strips `_prefix` layout segments (pathless routes)
+ * - `index.tsx` → parent path
+ * - `$.tsx` → null (handled as fallbackUrl)
+ * - `[.]` → literal dot
+ * - Strips extensions
+ * Returns null for splat routes (caller handles as fallbackUrl),
+ * or undefined for files that shouldn't produce routes (layouts, tests, api).
+ */
+function tanstackRouteToUrl(
+  filePath: string,
+  routesDir: string
+): string | null | undefined {
+  const rel = relative(routesDir, filePath);
+
+  // Skip root layout, test files, api routes
+  if (
+    rel.startsWith("__") ||
+    rel.includes(".test.") ||
+    rel.startsWith("api/") ||
+    rel.startsWith("api\\")
+  ) {
+    return undefined;
+  }
+
+  // Strip extension
+  const withoutExt = rel.replace(/\.(tsx?|jsx?)$/, "");
+
+  const segments = withoutExt.split(/[/\\]/);
+  const urlSegments: string[] = [];
+  let isSplat = false;
+
+  for (const seg of segments) {
+    // Layout files (e.g. _landing.tsx) — skip as a route themselves
+    // but as directories they wrap children
+    if (seg.startsWith("_")) {
+      continue;
+    }
+
+    // Splat route
+    if (seg === "$") {
+      isSplat = true;
+      continue;
+    }
+
+    // Dynamic param like $slug — skip, produces fallback
+    if (seg.startsWith("$")) {
+      isSplat = true;
+      continue;
+    }
+
+    // index → parent
+    if (seg === "index") {
+      continue;
+    }
+
+    // [.] → literal dot
+    let processed = seg.replace(/\[\.\]/g, ".");
+
+    urlSegments.push(processed);
+  }
+
+  if (isSplat) {
+    return null; // caller creates fallbackUrl regex
+  }
+
+  return "/" + urlSegments.join("/") || "/";
+}
+
+function scanRoutes(
+  routesDir: string,
+  cwd: string,
+  urls: Map<string, UrlMeta>,
+  fallbackUrls: { url: RegExp; meta: UrlMeta }[]
+): void {
+  const absRoutesDir = resolve(cwd, routesDir);
+  if (!existsSync(absRoutesDir)) return;
+
+  const routeFiles = globSync(`${routesDir}/**/*.{tsx,ts,jsx,js}`, { cwd });
+
+  for (const file of routeFiles) {
+    const result = tanstackRouteToUrl(file, routesDir);
+
+    if (result === undefined) {
+      // Skip (layout, test, api)
+      continue;
+    }
+
+    if (result === null) {
+      // Splat route — build a regex fallback from the non-splat prefix
+      const rel = relative(routesDir, file).replace(/\.(tsx?|jsx?)$/, "");
+      const segments = rel.split(/[/\\]/);
+      const prefixSegments: string[] = [];
+      for (const seg of segments) {
+        if (seg.startsWith("_")) continue;
+        if (seg === "$" || seg.startsWith("$") || seg === "index") break;
+        prefixSegments.push(seg.replace(/\[\.\]/g, "."));
+      }
+      const prefix = "/" + prefixSegments.join("/");
+      const pattern = new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(/.*)?$`);
+      fallbackUrls.push({ url: pattern, meta: {} });
+      continue;
+    }
+
+    if (!urls.has(result)) {
+      urls.set(result, {});
+    }
+  }
+}
+
+function contentPathToUrl(filePath: string, contentDir: string): string {
+  let urlPath = "/" + relative(contentDir, filePath);
+  urlPath = urlPath.replace(/\.mdx$/, "");
+  if (urlPath.endsWith("/index")) {
+    urlPath = urlPath.slice(0, -"/index".length) || "/";
+  }
+  return urlPath;
+}
+
+function buildContentScanResult(
+  contentDir: string,
+  cwd: string,
+  verbose?: boolean,
+  deps?: Set<string>
+): ScanResult {
+  const urls = new Map<string, UrlMeta>();
+  const fallbackUrls: { url: RegExp; meta: UrlMeta }[] = [];
+  const mdxFiles = globSync(`${contentDir}/**/*.mdx`, { cwd });
+
+  for (const file of mdxFiles) {
+    const urlPath = contentPathToUrl(file, contentDir);
+    const content = readFileSync(resolve(cwd, file), "utf-8");
+    const hashes = extractHashes(content);
+
+    urls.set(urlPath, { hashes: hashes.length > 0 ? hashes : undefined });
+  }
+
+  // Scan TanStack Router routes if TanStack Start is a dependency
+  const isTanStack =
+    deps?.has("@tanstack/react-start") ||
+    deps?.has("@tanstack/start") ||
+    deps?.has("@tanstack/react-router");
+  if (isTanStack) {
+    for (const routesDir of ["src/routes", "app/routes"]) {
+      scanRoutes(routesDir, cwd, urls, fallbackUrls);
+    }
+  }
+
+  if (verbose) {
+    console.log(
+      "\n" +
+        "Scanned content routes:\n" +
+        [...urls.keys()].map((x) => `"${x}"`).join(", ") +
+        (fallbackUrls.length > 0
+          ? "\nFallback patterns:\n" +
+            fallbackUrls.map((x) => `${x.url}`).join(", ")
+          : "") +
+        "\n"
+    );
+  }
+
+  return { urls, fallbackUrls };
 }
 
 export async function validateMdxLinks({
   cwd = process.cwd(),
   files: filesGlob,
   verbose = false,
+  contentDir,
 }: ValidateMdxLinksOptions): Promise<ValidationResult[]> {
   const originalCwd = process.cwd();
   process.chdir(cwd);
@@ -36,20 +274,40 @@ export async function validateMdxLinks({
     console.log(`Found ${files.length} markdown files to validate.\n`);
   }
 
-  const scanned = await scanURLs();
+  let scanned: ScanResult;
+  let effectiveContentDir: string | undefined = contentDir;
+  const deps = readDeps(cwd);
 
-  if (verbose) {
-    console.log(
-      "\n" +
-        "Scanned routes from the file system:\n" +
-        [...scanned.urls.keys(), ...scanned.fallbackUrls.map((x) => x.url)]
-          .map((x) => `"${x}"`)
-          .join(", ") +
-        "\n"
-    );
+  if (contentDir) {
+    scanned = buildContentScanResult(contentDir, cwd, verbose, deps);
+  } else {
+    const framework = detectFramework(cwd, deps);
+    if (framework.type === "content") {
+      effectiveContentDir = framework.contentDir;
+      scanned = buildContentScanResult(framework.contentDir, cwd, verbose, deps);
+    } else {
+      scanned = await scanURLs();
+      if (verbose) {
+        console.log(
+          "\n" +
+            "Scanned routes from the file system:\n" +
+            [
+              ...scanned.urls.keys(),
+              ...scanned.fallbackUrls.map((x) => x.url),
+            ]
+              .map((x) => `"${x}"`)
+              .join(", ") +
+            "\n"
+        );
+      }
+    }
   }
 
-  const validations = await validateFiles(files, { scanned });
+  const pathToUrl = effectiveContentDir
+    ? (filePath: string) => contentPathToUrl(filePath, effectiveContentDir!)
+    : undefined;
+
+  const validations = await validateFiles(files, { scanned, pathToUrl });
 
   const withoutFalsePositives = await Promise.all(
     validations.map(async ({ file, detected }) => {
@@ -72,6 +330,21 @@ export async function validateMdxLinks({
             }
           }
 
+          // if the file is called index.mdx and is in content dir, it turns out
+          // both `./dirname/foo` and `./foo` links work and point to the same file and
+          if (basename(file) === "index.mdx") {
+            const dir = basename(dirname(file));
+            const isSameDir = dir === basename(dirname(link));
+
+            if (isSameDir) {
+              const path = resolve(dirname(file), "..", `${link}.mdx`);
+              if (await fileExists(path)) {
+                // file exists, the error is a false positive
+                continue;
+              }
+            }
+          }
+
           // relative links can lose their .mdx extension
           if (!link.endsWith(".mdx")) {
             const dest = resolve(dirname(file), `${link}.mdx`);