@djangocfg/seo 2.1.50

package/src/content/link-checker.ts

@@ -0,0 +1,182 @@
+/**
+ * Link checker for MDX documentation
+ * Checks all internal links in content/ folder and verifies pages exist
+ * Properly handles Nextra's routing behavior for relative links
+ */
+
+import fs from 'fs';
+import path from 'path';
+import type {
+  ContentConfig,
+  ExtractedLink,
+  BrokenLink,
+  LinkCheckResult,
+  LinkType,
+  DEFAULT_CONFIG,
+} from './types.js';
+import { getAllMdxFiles, getFileInfo, pathExists } from './scanner.js';
+
+// Link patterns for MDX files (handles optional #anchor)
+const LINK_PATTERNS: { regex: RegExp; type: LinkType }[] = [
+  // Absolute links: [text](/docs/path)
+  { regex: /\]\(\/docs\/([^)#\s"]+)/g, type: 'absolute' },
+  { regex: /href="\/docs\/([^"#]+)"/g, type: 'absolute' },
+  { regex: /to="\/docs\/([^"#]+)"/g, type: 'absolute' },
+  // Dot-slash relative: [text](./path)
+  { regex: /\]\(\.\/([^)#\s"]+)(?:#[^)]*)?\)/g, type: 'dotslash' },
+  { regex: /href="\.\/([^"#]+)"/g, type: 'dotslash' },
+  // Parent relative: [text](../path)
+  { regex: /\]\(\.\.\/([^)#\s"]+)(?:#[^)]*)?\)/g, type: 'parent' },
+  { regex: /href="\.\.\/([^"#]+)"/g, type: 'parent' },
+  // Simple relative (no prefix): [text](path)
+  { regex: /\]\((?!\/|http|#|\.|\[)([a-zA-Z][^)#\s"]*)(?:#[^)]*)?\)/g, type: 'simple' },
+  { regex: /href="(?!\/|http|#|\.)([a-zA-Z][^"#]*)"/g, type: 'simple' },
+];
+
+/**
+ * Check if link points to an asset file
+ */
+function isAssetLink(linkPath: string, assetExtensions: string[]): boolean {
+  return assetExtensions.some(ext => linkPath.toLowerCase().endsWith(ext));
+}
+
+/**
+ * Resolve a link to an absolute docs path
+ * Mimics how Nextra/browser resolves links
+ */
+function resolveLink(
+  fromFilePath: string,
+  linkPath: string,
+  linkType: LinkType,
+  contentDir: string
+): string {
+  if (linkType === 'absolute') {
+    return linkPath;
+  }
+
+  const { isIndex, folder: sourceFolder, name: fileName } = getFileInfo(fromFilePath, contentDir);
+  const sourceParts = sourceFolder ? sourceFolder.split('/') : [];
+
+  if (linkType === 'dotslash' || linkType === 'simple') {
+    // ./ or simple relative
+    if (isIndex) {
+      // index.mdx at /foo/ -> ./bar resolves to /foo/bar
+      return sourceFolder ? `${sourceFolder}/${linkPath}` : linkPath;
+    } else {
+      // page.mdx at /foo/page -> ./bar resolves to /foo/page/bar (browser behavior!)
+      return sourceFolder ? `${sourceFolder}/${fileName}/${linkPath}` : `${fileName}/${linkPath}`;
+    }
+  }
+
+  if (linkType === 'parent') {
+    // ../bar
+    if (isIndex) {
+      // index.mdx at /foo/ -> ../bar resolves to /bar (go up from foo)
+      const newParts = [...sourceParts];
+      newParts.pop();
+      return newParts.length ? `${newParts.join('/')}/${linkPath}` : linkPath;
+    } else {
+      // page.mdx at /foo/page -> ../bar resolves to /foo/bar
+      return sourceParts.length ? `${sourceParts.join('/')}/${linkPath}` : linkPath;
+    }
+  }
+
+  return linkPath;
+}
+
+/**
+ * Extract all links from a file
+ */
+function extractLinks(
+  filePath: string,
+  contentDir: string,
+  assetExtensions: string[]
+): ExtractedLink[] {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const links: ExtractedLink[] = [];
+
+  for (const { regex, type } of LINK_PATTERNS) {
+    regex.lastIndex = 0;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+      const rawLink = match[1];
+      if (!rawLink) continue;
+
+      // Skip asset links
+      if (isAssetLink(rawLink, assetExtensions)) continue;
+
+      const resolved = resolveLink(filePath, rawLink, type, contentDir);
+      links.push({
+        raw: rawLink,
+        resolved,
+        type,
+        line: content.substring(0, match.index).split('\n').length,
+      });
+    }
+  }
+
+  return links;
+}
+
+/**
+ * Check all links in content directory
+ */
+export function checkContentLinks(
+  contentDir: string,
+  config?: Partial<ContentConfig>
+): LinkCheckResult {
+  const assetExtensions = config?.assetExtensions || [
+    '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico', '.pdf', '.zip', '.tar', '.gz'
+  ];
+  const basePath = config?.basePath || '/docs';
+
+  const files = getAllMdxFiles(contentDir);
+  const brokenLinks: BrokenLink[] = [];
+  const checkedLinks = new Map<string, boolean>();
+
+  for (const file of files) {
+    const links = extractLinks(file, contentDir, assetExtensions);
+    const relativePath = path.relative(contentDir, file);
+
+    for (const link of links) {
+      // Check if we've already verified this path
+      if (!checkedLinks.has(link.resolved)) {
+        checkedLinks.set(link.resolved, pathExists(link.resolved, contentDir));
+      }
+
+      if (!checkedLinks.get(link.resolved)) {
+        brokenLinks.push({
+          file: relativePath,
+          link: `${basePath}/${link.resolved}`,
+          type: link.type,
+          raw: link.raw,
+          line: link.line,
+        });
+      }
+    }
+  }
+
+  return {
+    filesChecked: files.length,
+    uniqueLinks: checkedLinks.size,
+    brokenLinks,
+    success: brokenLinks.length === 0,
+  };
+}
+
+/**
+ * Group broken links by file for display
+ */
+export function groupBrokenLinksByFile(
+  brokenLinks: BrokenLink[]
+): Map<string, BrokenLink[]> {
+  const byFile = new Map<string, BrokenLink[]>();
+
+  for (const link of brokenLinks) {
+    const existing = byFile.get(link.file) || [];
+    existing.push(link);
+    byFile.set(link.file, existing);
+  }
+
+  return byFile;
+}

package/src/content/link-fixer.ts

@@ -0,0 +1,188 @@
+/**
+ * Link fixer for MDX documentation
+ * Converts absolute /docs/ links to relative when appropriate
+ *
+ * Nextra routing rules:
+ * - index.mdx at /foo/ -> ./bar resolves to /foo/bar ✓
+ * - page.mdx at /foo/page -> ./bar resolves to /foo/page/bar ✗ (browser behavior)
+ *
+ * So for non-index files linking to siblings, we need ../sibling
+ */
+
+import fs from 'fs';
+import path from 'path';
+import type { ContentConfig, LinkFix, LinkFixResult, FixLinksResult } from './types.js';
+import { getAllMdxFiles, getFileInfo, pathExists } from './scanner.js';
+
+/**
+ * Check if link points to an asset file
+ */
+function isAssetLink(linkPath: string, assetExtensions: string[]): boolean {
+  return assetExtensions.some(ext => linkPath.toLowerCase().endsWith(ext));
+}
+
+/**
+ * Calculate relative path from source to target, respecting Nextra routing
+ * Returns null if can't be relative (target is outside source's scope)
+ */
+function calculateRelativePath(
+  sourceFile: string,
+  targetDocsPath: string,
+  contentDir: string
+): string | null {
+  const { isIndex, folder: sourceFolder } = getFileInfo(sourceFile, contentDir);
+  const targetPath = targetDocsPath.replace(/^\//, '');
+
+  // Split paths into parts
+  const sourceParts = sourceFolder ? sourceFolder.split('/') : [];
+  const targetParts = targetPath.split('/');
+
+  // Find common prefix
+  let commonLength = 0;
+  for (let i = 0; i < Math.min(sourceParts.length, targetParts.length); i++) {
+    if (sourceParts[i] === targetParts[i]) {
+      commonLength++;
+    } else {
+      break;
+    }
+  }
+
+  // For index files: can use ./ for same folder or subfolders
+  // For non-index files: need to go up first with ../
+
+  if (isIndex) {
+    // index.mdx at /foo/ can use ./bar for /foo/bar
+    if (targetPath.startsWith(sourceFolder + '/') || sourceFolder === '') {
+      const relative = sourceFolder ? targetPath.slice(sourceFolder.length + 1) : targetPath;
+      return './' + relative;
+    }
+    // Target is outside - need ../
+    const upsNeeded = sourceParts.length - commonLength;
+    const downs = targetParts.slice(commonLength);
+    if (upsNeeded <= 1) {
+      return '../'.repeat(upsNeeded) + downs.join('/');
+    }
+    return null; // Too far up, keep absolute
+  } else {
+    // Non-index file at /foo/page needs ../bar for /foo/bar (sibling)
+    // and ./bar would go to /foo/page/bar which is wrong
+
+    if (targetPath.startsWith(sourceFolder + '/') || sourceFolder === '') {
+      // Same folder - target is sibling
+      const relative = sourceFolder ? targetPath.slice(sourceFolder.length + 1) : targetPath;
+      if (!relative.includes('/')) {
+        // Sibling file
+        return '../' + relative;
+      }
+      // Subfolder of same folder
+      return '../' + relative;
+    }
+
+    // Different folder
+    const upsNeeded = sourceParts.length - commonLength + 1; // +1 because non-index
+    const downs = targetParts.slice(commonLength);
+    if (upsNeeded <= 2) {
+      return '../'.repeat(upsNeeded) + downs.join('/');
+    }
+    return null; // Too far, keep absolute
+  }
+}
+
+/**
+ * Process a single file and find fixable links
+ */
+function processFile(
+  filePath: string,
+  contentDir: string,
+  assetExtensions: string[]
+): LinkFix[] {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const fixes: LinkFix[] = [];
+
+  const patterns = [
+    { regex: /(\]\()\/docs\/([^)#\s"]+)(\))/g },
+    { regex: /(href=")\/docs\/([^"#]+)(")/g },
+  ];
+
+  for (const { regex } of patterns) {
+    regex.lastIndex = 0;
+    let match;
+
+    while ((match = regex.exec(content)) !== null) {
+      const targetPath = match[2];
+      if (!targetPath) continue;
+
+      // Skip assets
+      if (isAssetLink(targetPath, assetExtensions)) continue;
+
+      // Skip if target doesn't exist
+      if (!pathExists(targetPath, contentDir)) continue;
+
+      const relativePath = calculateRelativePath(filePath, targetPath, contentDir);
+
+      if (relativePath) {
+        fixes.push({
+          from: `/docs/${targetPath}`,
+          to: relativePath,
+          line: content.substring(0, match.index).split('\n').length,
+        });
+      }
+    }
+  }
+
+  return fixes;
+}
+
+/**
+ * Apply fixes to a file
+ */
+function applyFixes(filePath: string, fixes: LinkFix[]): void {
+  let content = fs.readFileSync(filePath, 'utf-8');
+
+  for (const { from, to } of fixes) {
+    content = content.split(from).join(to);
+  }
+
+  fs.writeFileSync(filePath, content, 'utf-8');
+}
+
+/**
+ * Fix absolute links to relative in content directory
+ */
+export function fixContentLinks(
+  contentDir: string,
+  options: { apply?: boolean; config?: Partial<ContentConfig> } = {}
+): FixLinksResult {
+  const { apply = false, config } = options;
+  const assetExtensions = config?.assetExtensions || [
+    '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico', '.pdf'
+  ];
+
+  const files = getAllMdxFiles(contentDir);
+  let totalChanges = 0;
+  const fileChanges: LinkFixResult[] = [];
+
+  for (const file of files) {
+    const fixes = processFile(file, contentDir, assetExtensions);
+
+    if (fixes.length > 0) {
+      const relativePath = path.relative(contentDir, file);
+      fileChanges.push({
+        file: relativePath,
+        fullPath: file,
+        fixes,
+      });
+      totalChanges += fixes.length;
+
+      if (apply) {
+        applyFixes(file, fixes);
+      }
+    }
+  }
+
+  return {
+    totalChanges,
+    fileChanges,
+    applied: apply,
+  };
+}

package/src/content/scanner.ts

@@ -0,0 +1,200 @@
+/**
+ * Content scanner for MDX/Nextra projects
+ * Scans content/ and app/ directories for files
+ */
+
+import fs from 'fs';
+import path from 'path';
+import type { ContentConfig, FileInfo, ContentScanResult, DEFAULT_CONFIG } from './types.js';
+
+/**
+ * Detect project type based on directory structure
+ */
+export function detectProjectType(cwd: string): 'nextra' | 'nextjs' | 'unknown' {
+  const contentDir = path.join(cwd, 'content');
+  const appDir = path.join(cwd, 'app');
+
+  if (fs.existsSync(contentDir)) {
+    // Check for _meta.ts files (Nextra indicator)
+    if (hasMetaFiles(contentDir)) {
+      return 'nextra';
+    }
+  }
+
+  if (fs.existsSync(appDir)) {
+    return 'nextjs';
+  }
+
+  return 'unknown';
+}
+
+/**
+ * Check if directory contains _meta.ts files (Nextra pattern)
+ */
+export function hasMetaFiles(dir: string): boolean {
+  if (!fs.existsSync(dir)) return false;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.name === '_meta.ts' || entry.name === '_meta.tsx') {
+      return true;
+    }
+    if (entry.isDirectory() && !entry.name.startsWith('.')) {
+      const subDir = path.join(dir, entry.name);
+      if (hasMetaFiles(subDir)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Scan project and return content information
+ */
+export function scanProject(cwd: string, config?: Partial<ContentConfig>): ContentScanResult {
+  const contentDir = path.join(cwd, config?.contentDir || 'content');
+  const appDir = path.join(cwd, config?.appDir || 'app');
+  const extensions = config?.extensions || ['.mdx', '.md'];
+
+  const hasContent = fs.existsSync(contentDir);
+  const hasApp = fs.existsSync(appDir);
+  const projectType = detectProjectType(cwd);
+
+  const mdxFiles = hasContent ? getAllFiles(contentDir, extensions) : [];
+  const pageFiles = hasApp ? getPageFiles(appDir) : [];
+
+  return {
+    projectType,
+    hasContent,
+    hasApp,
+    mdxFiles,
+    pageFiles,
+  };
+}
+
+/**
+ * Get all files with given extensions recursively
+ */
+export function getAllFiles(dir: string, extensions: string[], files: string[] = []): string[] {
+  if (!fs.existsSync(dir)) return files;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      if (!entry.name.startsWith('.') && entry.name !== 'node_modules') {
+        getAllFiles(fullPath, extensions, files);
+      }
+    } else {
+      const ext = path.extname(entry.name).toLowerCase();
+      if (extensions.includes(ext)) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Get all MDX files in content directory
+ */
+export function getAllMdxFiles(contentDir: string): string[] {
+  return getAllFiles(contentDir, ['.mdx', '.md']);
+}
+
+/**
+ * Get all page.tsx files in app directory
+ */
+export function getPageFiles(appDir: string): string[] {
+  const pages: string[] = [];
+
+  function scan(dir: string) {
+    if (!fs.existsSync(dir)) return;
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      // Skip special directories
+      if (entry.name.startsWith('_') || entry.name.startsWith('.')) continue;
+
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        // Skip route groups for page detection but still scan them
+        scan(fullPath);
+      } else if (entry.name === 'page.tsx' || entry.name === 'page.ts') {
+        pages.push(fullPath);
+      }
+    }
+  }
+
+  scan(appDir);
+  return pages;
+}
+
+/**
+ * Get file info for link resolution
+ */
+export function getFileInfo(filePath: string, contentDir: string): FileInfo {
+  const relativePath = path.relative(contentDir, filePath);
+  const parsed = path.parse(relativePath);
+  const isIndex = parsed.name === 'index';
+  const folder = parsed.dir || '';
+
+  return {
+    fullPath: filePath,
+    relativePath,
+    isIndex,
+    folder,
+    name: parsed.name,
+  };
+}
+
+/**
+ * Check if a path exists as MDX file or directory with index
+ */
+export function pathExists(docsPath: string, contentDir: string): boolean {
+  const cleanPath = docsPath.replace(/\/$/, '').replace(/^\//, '');
+
+  const candidates = [
+    path.join(contentDir, cleanPath + '.mdx'),
+    path.join(contentDir, cleanPath + '.md'),
+    path.join(contentDir, cleanPath, 'index.mdx'),
+    path.join(contentDir, cleanPath, 'index.md'),
+  ];
+
+  return candidates.some(p => fs.existsSync(p));
+}
+
+/**
+ * Find content directory, looking in common locations
+ */
+export function findContentDir(cwd: string): string | null {
+  const candidates = [
+    path.join(cwd, 'content'),
+    path.join(cwd, 'docs'),
+    path.join(cwd, 'pages', 'docs'),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Find app directory
+ */
+export function findAppDir(cwd: string): string | null {
+  const appDir = path.join(cwd, 'app');
+  return fs.existsSync(appDir) ? appDir : null;
+}