@writechoice/mint-cli 0.0.10 → 0.0.12

package/README.md

@@ -32,6 +32,9 @@ writechoice check links docs.example.com http://localhost:3000
 # Fix broken anchor links
 writechoice fix links
 
+# Fix MDX parsing errors (void tags, stray angle brackets)
+writechoice fix parse
+
 # Generate config.json template
 writechoice config
 ```
@@ -94,6 +97,29 @@ writechoice fix links -r custom_report.json  # Use custom report
 
 **Note:** Requires JSON report from `check links` command.
 
+### `fix parse`
+
+Automatically fixes common MDX parsing errors: void HTML tags not self-closed and stray angle brackets in text.
+
+```bash
+writechoice fix parse                        # Fix from check parse report
+writechoice fix parse -f file.mdx            # Fix a single file directly
+writechoice fix parse -d docs                # Fix files in a directory
+writechoice fix parse -r custom_report.json  # Use custom report
+```
+
+**Common options:**
+- `-r, --report <path>` - Path to JSON report (default: `mdx_errors_report.json`)
+- `-f, --file <path>` - Fix a single MDX file directly
+- `-d, --dir <path>` - Fix MDX files in a directory
+- `--quiet` - Suppress output
+
+**What it fixes:**
+- Void tags: `<br>` → `<br />`, `<img src="x">` → `<img src="x" />`
+- Stray brackets: `x < 10` → `x &lt; 10`, `y > 5` → `y &gt; 5`
+
+Content inside code blocks and inline code is never modified.
+
 ### `update`
 
 Update CLI to latest version.
@@ -107,7 +133,8 @@ writechoice update
 - **MDX Parsing Validation** - Catch syntax errors before deployment
 - **Link Validation** - Test links against live websites with Playwright
 - **Two-Step Anchor Validation** - Compare production vs development anchors
-- **Auto-Fix** - Separate fix command to automatically correct broken anchor links
+- **Auto-Fix Links** - Automatically correct broken anchor links
+- **Auto-Fix Parsing** - Automatically fix void tags and stray angle brackets
 - **Dual Report Formats** - Generates both JSON (for automation) and Markdown (for humans)
 - **Configuration File** - Optional config.json for default settings
 - **CI/CD Ready** - Exit codes for pipeline integration
@@ -176,10 +203,21 @@ writechoice fix links
 # Fix from custom report
 writechoice fix links -r custom_report.json
 
+# Fix MDX parsing errors
+writechoice fix parse
+
+# Fix a single file directly
+writechoice fix parse -f docs/getting-started.mdx
+
 # Full workflow: validate -> fix -> re-validate
 writechoice check links docs.example.com
 writechoice fix links
 writechoice check links docs.example.com
+
+# Full parse workflow: validate -> fix -> re-validate
+writechoice check parse
+writechoice fix parse
+writechoice check parse
 ```
 
 ## Documentation
@@ -191,6 +229,7 @@ Detailed documentation is available in the [docs/](docs/) folder:
   - [check links](docs/commands/check-links.md) - Link validation
   - [check parse](docs/commands/check-parse.md) - MDX parsing validation
   - [fix links](docs/commands/fix-links.md) - Auto-fix broken links
+  - [fix parse](docs/commands/fix-parse.md) - Auto-fix MDX parsing errors
   - [update](docs/commands/update.md) - Update command
 - **Guides**
   - [Configuration File](docs/config-file.md) - Using config.json
@@ -222,7 +261,8 @@ writechoice-mint-cli/
 │   │   │   ├── links.js       # Link validation
 │   │   │   └── mdx.js         # MDX parsing validation
 │   │   └── fix/
-│   │       └── links.js       # Link fixing
+│   │       ├── links.js       # Link fixing
+│   │       └── parse.js       # Parse error fixing
 │   └── utils/
 │       ├── helpers.js         # Utility functions
 │       └── reports.js         # Report generation

package/bin/cli.js

@@ -95,6 +95,20 @@ fix
     await fixLinks(options);
   });
 
+// Fix parse subcommand
+fix
+  .command("parse")
+  .description("Fix common MDX parsing errors (void tags, stray angle brackets)")
+  .option("-r, --report <path>", "Path to parse validation report", "mdx_errors_report.json")
+  .option("-f, --file <path>", "Fix a single MDX file directly")
+  .option("-d, --dir <path>", "Fix MDX files in a specific directory")
+  .option("--quiet", "Suppress terminal output")
+  .action(async (options) => {
+    const { fixParse } = await import("../src/commands/fix/parse.js");
+    options.verbose = !options.quiet;
+    await fixParse(options);
+  });
+
 // Config command
 program
   .command("config")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writechoice/mint-cli",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "CLI tool for Mintlify documentation validation and utilities",
   "main": "src/index.js",
   "type": "module",

package/src/commands/fix/parse.js

@@ -0,0 +1,447 @@
+/**
+ * MDX Parse Fix Tool
+ *
+ * Fixes common MDX parsing errors in documentation files:
+ * 1. Void HTML tags not self-closed (<br> → <br />)
+ * 2. Stray < / > in text (escape to &lt; / &gt;)
+ *
+ * Skips content inside code fences and inline code.
+ */
+
+import { existsSync, readdirSync, statSync, readFileSync, writeFileSync } from "fs";
+import { join, relative, resolve } from "path";
+import chalk from "chalk";
+
+// Void HTML elements that must be self-closing in JSX/MDX
+const VOID_ELEMENTS = [
+  "area", "base", "br", "col", "embed", "hr", "img",
+  "input", "link", "meta", "source", "track", "wbr",
+];
+
+const VOID_PATTERN = new RegExp(
+  `<(${VOID_ELEMENTS.join("|")})(\\s[^>]*?)?\\s*(?<!\\/)>`,
+  "gi"
+);
+
+const EXCLUDED_DIRS = ["snippets", "node_modules", ".git"];
+
+/**
+ * Finds MDX files to process
+ */
+function findMdxFiles(repoRoot, directory = null, file = null) {
+  if (file) {
+    const fullPath = resolve(repoRoot, file);
+    return existsSync(fullPath) ? [fullPath] : [];
+  }
+
+  const searchDirs = directory
+    ? [resolve(repoRoot, directory)]
+    : [repoRoot];
+
+  const mdxFiles = [];
+
+  function walkDirectory(dir) {
+    const dirName = dir.split("/").pop();
+    if (EXCLUDED_DIRS.includes(dirName)) return;
+
+    try {
+      const entries = readdirSync(dir);
+      for (const entry of entries) {
+        const fullPath = join(dir, entry);
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+          walkDirectory(fullPath);
+        } else if (stat.isFile() && entry.endsWith(".mdx")) {
+          mdxFiles.push(fullPath);
+        }
+      }
+    } catch (error) {
+      console.error(`Error reading directory ${dir}: ${error.message}`);
+    }
+  }
+
+  for (const dir of searchDirs) {
+    if (existsSync(dir)) walkDirectory(dir);
+  }
+
+  return mdxFiles.sort();
+}
+
+/**
+ * Gets file list from a parse report (only files with errors)
+ */
+function getFilesFromReport(reportPath, repoRoot) {
+  if (!existsSync(reportPath)) return null;
+
+  try {
+    const report = JSON.parse(readFileSync(reportPath, "utf-8"));
+    const errorFiles = (report.errors || []).map((e) =>
+      resolve(repoRoot, e.filePath)
+    );
+    return errorFiles;
+  } catch (error) {
+    console.error(`Error reading report: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Splits file content into protected (code) and unprotected (text) segments.
+ * Returns an array of { text, protected } objects.
+ */
+function segmentContent(content) {
+  const segments = [];
+  let pos = 0;
+  const len = content.length;
+
+  // State tracking for fenced code blocks
+  let inFence = false;
+  let fenceMarker = "";
+
+  const lines = content.split("\n");
+  let lineStart = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineEnd = lineStart + line.length;
+    const trimmed = line.trimStart();
+
+    // Check for fenced code block boundaries
+    if (!inFence) {
+      const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/);
+      if (fenceMatch) {
+        // Push any text before this fence line
+        if (lineStart > pos) {
+          segments.push({ text: content.slice(pos, lineStart), protected: false });
+        }
+        inFence = true;
+        fenceMarker = fenceMatch[1][0].repeat(fenceMatch[1].length);
+        // This line is protected
+        segments.push({ text: content.slice(lineStart, lineEnd), protected: true });
+        pos = lineEnd;
+        lineStart = lineEnd + 1; // +1 for newline
+        continue;
+      }
+    } else {
+      // Check for closing fence
+      const closeMatch = trimmed.match(/^(`{3,}|~{3,})\s*$/);
+      if (closeMatch && closeMatch[1][0] === fenceMarker[0] && closeMatch[1].length >= fenceMarker.length) {
+        // Include this line as protected, then exit fence
+        segments.push({ text: content.slice(pos, lineEnd), protected: true });
+        pos = lineEnd;
+        inFence = false;
+        fenceMarker = "";
+        lineStart = lineEnd + 1;
+        continue;
+      }
+      // Still inside fence, continue
+      lineStart = lineEnd + 1;
+      continue;
+    }
+
+    lineStart = lineEnd + 1;
+  }
+
+  // Push remaining content
+  if (pos < content.length) {
+    segments.push({ text: content.slice(pos), protected: inFence });
+  }
+
+  return segments;
+}
+
+/**
+ * Fixes void HTML tags in a text segment (not inside inline code).
+ * Returns { text, count }.
+ */
+function fixVoidTags(text) {
+  let count = 0;
+
+  // Process the text but protect inline code spans
+  const parts = [];
+  let lastIndex = 0;
+
+  // Match inline code: `...`
+  const inlineCodeRegex = /`[^`]+`/g;
+  let match;
+
+  while ((match = inlineCodeRegex.exec(text)) !== null) {
+    // Process text before this inline code
+    const before = text.slice(lastIndex, match.index);
+    const { text: fixed, count: c } = replaceVoidTags(before);
+    parts.push(fixed);
+    count += c;
+
+    // Keep inline code unchanged
+    parts.push(match[0]);
+    lastIndex = match.index + match[0].length;
+  }
+
+  // Process remaining text after last inline code
+  const remaining = text.slice(lastIndex);
+  const { text: fixed, count: c } = replaceVoidTags(remaining);
+  parts.push(fixed);
+  count += c;
+
+  return { text: parts.join(""), count };
+}
+
+/**
+ * Replaces non-self-closed void tags in a string
+ */
+function replaceVoidTags(text) {
+  let count = 0;
+  const result = text.replace(VOID_PATTERN, (match, tag, attrs) => {
+    // Already self-closing check (belt and suspenders)
+    if (match.trimEnd().endsWith("/>")) return match;
+    count++;
+    const attrStr = attrs ? attrs.trimEnd() : "";
+    return `<${tag}${attrStr} />`;
+  });
+  return { text: result, count };
+}
+
+/**
+ * Fixes stray < and > in a text segment (not inside inline code or tags).
+ * Returns { text, count }.
+ */
+function fixStrayAngleBrackets(text) {
+  let count = 0;
+
+  // Process the text but protect inline code spans and valid tags
+  const parts = [];
+  let lastIndex = 0;
+
+  // Match inline code or valid HTML/JSX tags (opening, closing, self-closing, comments)
+  const protectedRegex = /`[^`]+`|<\/[a-zA-Z][a-zA-Z0-9]*\s*>|<[a-zA-Z][a-zA-Z0-9]*(?:\s[^>]*)?\s*\/?>|<!--[\s\S]*?-->|<![^>]*>/g;
+  let match;
+
+  while ((match = protectedRegex.exec(text)) !== null) {
+    // Process text before this protected span
+    const before = text.slice(lastIndex, match.index);
+    const { text: fixed, count: c } = escapeStrayBrackets(before);
+    parts.push(fixed);
+    count += c;
+
+    // Keep protected span unchanged
+    parts.push(match[0]);
+    lastIndex = match.index + match[0].length;
+  }
+
+  // Process remaining text
+  const remaining = text.slice(lastIndex);
+  const { text: fixed, count: c } = escapeStrayBrackets(remaining);
+  parts.push(fixed);
+  count += c;
+
+  return { text: parts.join(""), count };
+}
+
+/**
+ * Escapes stray < and > in plain text (no tags or code present)
+ */
+function escapeStrayBrackets(text) {
+  let count = 0;
+
+  // Also protect MDX expressions {}, JSX attribute patterns, and frontmatter
+  // Escape < that is NOT the start of a valid tag
+  let result = text.replace(/</g, (match, offset) => {
+    const after = text.slice(offset + 1);
+    // Valid tag starts: letter, /, !
+    if (/^[a-zA-Z\/!]/.test(after)) return match;
+    count++;
+    return "&lt;";
+  });
+
+  // Escape > that is NOT part of a blockquote or tag end
+  // Only escape > that appears to be in running text (preceded by space/word char)
+  const srcText = result;
+  let countGt = 0;
+  result = result.replace(/>/g, (match, offset) => {
+    // Keep > at start of line (blockquote syntax)
+    const lineStart = srcText.lastIndexOf("\n", offset - 1) + 1;
+    const beforeOnLine = srcText.slice(lineStart, offset).trimStart();
+    if (beforeOnLine === "" || /^>+$/.test(beforeOnLine)) return match;
+
+    // Keep > that looks like it closes a tag (preceded by tag-like content)
+    // This shouldn't happen since valid tags are protected above, but be safe
+    const before = srcText.slice(Math.max(0, offset - 1), offset);
+    if (/[a-zA-Z0-9"'\/\-]/.test(before)) {
+      // Could be end of tag — but tags should already be protected.
+      // In plain text, this is likely stray (e.g., "a > b")
+      // Only escape if it looks like a comparison/text context
+      const surroundBefore = srcText.slice(Math.max(0, offset - 2), offset);
+      const afterChar = srcText[offset + 1] || "";
+      if (/\s/.test(surroundBefore[0]) && /[\s\w]/.test(afterChar)) {
+        countGt++;
+        return "&gt;";
+      }
+      return match;
+    }
+
+    countGt++;
+    return "&gt;";
+  });
+
+  return { text: result, count: count + countGt };
+}
+
+/**
+ * Applies all fixes to a single file
+ * Returns { voidTagFixes, strayBracketFixes }
+ */
+function fixFile(filePath) {
+  const content = readFileSync(filePath, "utf-8");
+  const segments = segmentContent(content);
+
+  let totalVoidFixes = 0;
+  let totalBracketFixes = 0;
+
+  const fixedSegments = segments.map((seg) => {
+    if (seg.protected) return seg.text;
+
+    // Apply void tag fixes first
+    const { text: afterVoid, count: voidCount } = fixVoidTags(seg.text);
+    totalVoidFixes += voidCount;
+
+    // Then apply stray bracket fixes
+    const { text: afterBrackets, count: bracketCount } = fixStrayAngleBrackets(afterVoid);
+    totalBracketFixes += bracketCount;
+
+    return afterBrackets;
+  });
+
+  const fixedContent = fixedSegments.join("");
+
+  if (fixedContent !== content) {
+    writeFileSync(filePath, fixedContent, "utf-8");
+  }
+
+  return { voidTagFixes: totalVoidFixes, strayBracketFixes: totalBracketFixes };
+}
+
+/**
+ * Main CLI function for fixing parse errors
+ */
+export async function fixParse(options) {
+  const repoRoot = process.cwd();
+
+  if (!options.quiet) {
+    console.log(chalk.bold("\n\uD83D\uDD27 MDX Parse Fixer\n"));
+  }
+
+  // Determine which files to fix
+  let files;
+
+  if (options.file || options.dir) {
+    // Direct file/dir mode — no report needed
+    files = findMdxFiles(repoRoot, options.dir, options.file);
+
+    if (files.length === 0) {
+      console.error("No MDX files found.");
+      process.exit(1);
+    }
+
+    if (!options.quiet) {
+      console.log(`Found ${files.length} MDX file(s) to process\n`);
+    }
+  } else {
+    // Report mode
+    const reportPath = options.report || "mdx_errors_report.json";
+
+    if (!existsSync(reportPath)) {
+      console.error(chalk.red(`\n\u2717 Error: Report file not found: ${reportPath}`));
+
+      if (reportPath.endsWith(".md")) {
+        const jsonPath = reportPath.replace(/\.md$/, ".json");
+        console.error(chalk.yellow(`\n\u26A0\uFE0F  The fix command requires a JSON report file.`));
+        console.error(chalk.yellow(`Try using: ${chalk.cyan(jsonPath)}`));
+      } else {
+        console.error(chalk.yellow(`\n\u26A0\uFE0F  Make sure to run the validation command first:`));
+        console.error(chalk.gray(`  writechoice check parse`));
+      }
+
+      process.exit(1);
+    }
+
+    if (!reportPath.endsWith(".json")) {
+      console.error(chalk.red(`\n\u2717 Error: The fix command requires a JSON report file.`));
+      console.error(chalk.yellow(`\nProvided file: ${reportPath}`));
+
+      if (reportPath.endsWith(".md")) {
+        const jsonPath = reportPath.replace(/\.md$/, ".json");
+        console.error(chalk.yellow(`\nThe markdown (.md) report is for human readability only.`));
+        console.error(chalk.yellow(`Please use the JSON report instead: ${chalk.cyan(jsonPath)}`));
+      }
+
+      process.exit(1);
+    }
+
+    if (!options.quiet) {
+      console.log(`Reading report: ${chalk.cyan(reportPath)}`);
+    }
+
+    files = getFilesFromReport(reportPath, repoRoot);
+
+    if (!files || files.length === 0) {
+      if (!options.quiet) {
+        console.log(chalk.yellow("\n\u26A0\uFE0F  No files with errors found in report."));
+      }
+      return;
+    }
+
+    if (!options.quiet) {
+      console.log(`Found ${files.length} file(s) with errors\n`);
+    }
+  }
+
+  // Apply fixes
+  const results = {};
+  let totalVoid = 0;
+  let totalBracket = 0;
+
+  for (const filePath of files) {
+    if (!existsSync(filePath)) {
+      if (options.verbose) {
+        console.log(`Warning: File not found: ${filePath}`);
+      }
+      continue;
+    }
+
+    const { voidTagFixes, strayBracketFixes } = fixFile(filePath);
+    const totalFixes = voidTagFixes + strayBracketFixes;
+
+    if (totalFixes > 0) {
+      const relPath = relative(repoRoot, filePath);
+      results[relPath] = { voidTagFixes, strayBracketFixes };
+      totalVoid += voidTagFixes;
+      totalBracket += strayBracketFixes;
+
+      if (options.verbose) {
+        console.log(`Fixed ${chalk.cyan(relPath)}: ${voidTagFixes} void tag(s), ${strayBracketFixes} stray bracket(s)`);
+      }
+    }
+  }
+
+  // Summary
+  if (!options.quiet) {
+    const fileCount = Object.keys(results).length;
+    const totalFixes = totalVoid + totalBracket;
+
+    if (fileCount > 0) {
+      console.log(chalk.green(`\n\u2713 Fixed ${totalFixes} issue(s) in ${fileCount} file(s):\n`));
+
+      for (const [filePath, counts] of Object.entries(results)) {
+        const details = [];
+        if (counts.voidTagFixes > 0) details.push(`${counts.voidTagFixes} void tag(s)`);
+        if (counts.strayBracketFixes > 0) details.push(`${counts.strayBracketFixes} stray bracket(s)`);
+        console.log(`  ${chalk.cyan(filePath)}: ${details.join(", ")}`);
+      }
+
+      console.log(chalk.yellow("\n\u26A0\uFE0F  Run validation again to verify the fixes:"));
+      console.log(chalk.gray("  writechoice check parse"));
+    } else {
+      console.log(chalk.yellow("\n\u26A0\uFE0F  No fixable issues found."));
+    }
+  }
+}

package/src/commands/validate/links.js

@@ -398,6 +398,76 @@ function findMdxFiles(repoRoot, directory = null, file = null) {
 
 // Playwright Validation Functions
 
+/**
+ * Find a heading on the page by matching its text with the link text.
+ * Considers exact matches, partial matches, and phrase variations.
+ *
+ * @param {Page} page - Playwright page object
+ * @param {string} linkText - The text from the link (e.g., "Document Picker Security Settings")
+ * @param {boolean} verbose - Whether to log verbose output
+ * @returns {Promise<{heading: ElementHandle|null, text: string|null, index: number}>}
+ */
+async function findHeadingByText(page, linkText, verbose = false) {
+  const allHeadings = await page.$$("h1, h2, h3, h4, h5, h6");
+
+  // Normalize the link text for comparison
+  const normalizedLinkText = linkText.toLowerCase().trim();
+
+  // Store potential matches with their scores
+  const matches = [];
+
+  for (let i = 0; i < allHeadings.length; i++) {
+    const heading = allHeadings[i];
+    const headingText = await heading.innerText();
+    const headingTextClean = cleanHeadingText(headingText);
+    const normalizedHeadingText = headingTextClean.toLowerCase().trim();
+
+    // Exact match (highest priority)
+    if (normalizedHeadingText === normalizedLinkText) {
+      matches.push({ heading, text: headingTextClean, index: i, score: 100 });
+      continue;
+    }
+
+    // Check if link text is contained in heading (complete phrase match)
+    if (normalizedHeadingText.includes(normalizedLinkText)) {
+      matches.push({ heading, text: headingTextClean, index: i, score: 80 });
+      continue;
+    }
+
+    // Check if heading is contained in link text (link text might be more specific)
+    if (normalizedLinkText.includes(normalizedHeadingText)) {
+      matches.push({ heading, text: headingTextClean, index: i, score: 70 });
+      continue;
+    }
+
+    // Check word-by-word match (all words from link text appear in heading)
+    const linkWords = normalizedLinkText.split(/\s+/);
+    const headingWords = normalizedHeadingText.split(/\s+/);
+    const matchingWords = linkWords.filter(word => headingWords.includes(word));
+
+    if (matchingWords.length === linkWords.length && linkWords.length >= 2) {
+      // All words match
+      matches.push({ heading, text: headingTextClean, index: i, score: 60 });
+    } else if (matchingWords.length >= Math.ceil(linkWords.length * 0.7) && linkWords.length >= 3) {
+      // At least 70% of words match (for longer phrases)
+      matches.push({ heading, text: headingTextClean, index: i, score: 50 });
+    }
+  }
+
+  // Sort by score (highest first)
+  matches.sort((a, b) => b.score - a.score);
+
+  if (matches.length > 0) {
+    const bestMatch = matches[0];
+    if (verbose) {
+      console.log(`${DEFAULT_SPACE}Found heading by text match (score: ${bestMatch.score}): "${bestMatch.text}"`);
+    }
+    return { heading: bestMatch.heading, text: bestMatch.text, index: bestMatch.index };
+  }
+
+  return { heading: null, text: null, index: -1 };
+}
+
 async function validateAnchor(page, link, baseUrl, validationBaseUrl, repoRoot, verbose = false, progress = "") {
   const startTime = Date.now();
 
@@ -475,22 +545,39 @@ async function validateAnchor(page, link, baseUrl, validationBaseUrl, repoRoot,
       }
     }
 
+    // If anchor not found by ID, try to find heading by text
     if (!targetHeading) {
-      const validationTargetUrl = link.basePath.replace(baseUrl, validationBaseUrl);
-      return new ValidationResult(
-        link.source,
-        link.targetUrl, // sourceUrl (production)
-        validationTargetUrl, // targetUrl (validation)
-        link.basePath,
-        link.anchor,
-        link.expectedSlug,
-        "failure",
-        null,
-        null,
-        null,
-        `Anchor #${link.anchor} not found on base URL page`,
-        Date.now() - startTime,
-      );
+      if (verbose) {
+        console.log(`${DEFAULT_SPACE}Anchor #${link.anchor} not found by ID, searching by text...`);
+      }
+
+      // Try to find the heading by matching the link text
+      const textMatch = await findHeadingByText(page, link.source.linkText, verbose);
+
+      if (!textMatch.heading) {
+        const validationTargetUrl = link.basePath.replace(baseUrl, validationBaseUrl);
+        return new ValidationResult(
+          link.source,
+          link.targetUrl, // sourceUrl (production)
+          validationTargetUrl, // targetUrl (validation)
+          link.basePath,
+          link.anchor,
+          link.expectedSlug,
+          "failure",
+          null,
+          null,
+          null,
+          `Anchor #${link.anchor} not found on base URL page. Also could not find a heading matching "${link.source.linkText}"`,
+          Date.now() - startTime,
+        );
+      }
+
+      // Found a heading by text! Use it as the target
+      targetHeading = textMatch.heading;
+
+      if (verbose) {
+        console.log(`${DEFAULT_SPACE}✓ Using heading found by text match: "${textMatch.text}"`);
+      }
     }
 
     // Get the actual heading text from the base URL
@@ -552,20 +639,37 @@ async function validateAnchor(page, link, baseUrl, validationBaseUrl, repoRoot,
 
     if (matchingHeadings.length === 0) {
       const validationTargetUrl = validationUrl;
-      return new ValidationResult(
-        link.source,
-        link.targetUrl, // sourceUrl (production)
-        validationTargetUrl, // targetUrl (validation)
-        link.basePath,
-        link.anchor,
-        link.expectedSlug,
-        "failure",
-        null,
-        actualHeadingTextClean,
-        null,
-        `Heading "${actualHeadingTextClean}" found on base URL but not on validation URL`,
-        Date.now() - startTime,
-      );
+
+      // Try to find heading by text on validation page as well
+      if (verbose) {
+        console.log(`${DEFAULT_SPACE}Heading not found by text on validation page, trying broader search...`);
+      }
+
+      const validationTextMatch = await findHeadingByText(page, link.source.linkText, verbose);
+
+      if (validationTextMatch.heading) {
+        if (verbose) {
+          console.log(`${DEFAULT_SPACE}Found alternative heading on validation page: "${validationTextMatch.text}"`);
+        }
+
+        // Use this heading instead
+        matchingHeadings.push(validationTextMatch.heading);
+      } else {
+        return new ValidationResult(
+          link.source,
+          link.targetUrl, // sourceUrl (production)
+          validationTargetUrl, // targetUrl (validation)
+          link.basePath,
+          link.anchor,
+          link.expectedSlug,
+          "failure",
+          null,
+          actualHeadingTextClean,
+          null,
+          `Heading "${actualHeadingTextClean}" found on base URL but not on validation URL`,
+          Date.now() - startTime,
+        );
+      }
     }
 
     // Use the same index to handle duplicate headings
@@ -614,6 +718,10 @@ async function validateAnchor(page, link, baseUrl, validationBaseUrl, repoRoot,
 
     if (!generatedAnchor) {
       const validationTargetUrl = validationUrl;
+
+      // Suggest a kebab-case anchor based on the heading text
+      const suggestedAnchor = toKebabCase(actualHeadingTextClean);
+
       return new ValidationResult(
         link.source,
         link.targetUrl, // sourceUrl (production)
@@ -625,7 +733,7 @@ async function validateAnchor(page, link, baseUrl, validationBaseUrl, repoRoot,
         null,
         actualHeadingTextClean,
         null,
-        `Could not extract generated anchor after clicking heading "${actualHeadingTextClean}"`,
+        `Could not extract generated anchor after clicking heading "${actualHeadingTextClean}". Suggested anchor based on heading: #${suggestedAnchor}`,
         Date.now() - startTime,
       );
     }
@@ -661,7 +769,7 @@ async function validateAnchor(page, link, baseUrl, validationBaseUrl, repoRoot,
         null,
         actualHeadingTextClean,
         generatedAnchor,
-        `Expected anchor "#${link.anchor}" but page generates "#${generatedAnchor}" for heading "${actualHeadingTextClean}"`,
+        `Expected anchor "#${link.anchor}" but page generates "#${generatedAnchor}" for heading "${actualHeadingTextClean}". Suggestion: Update link to use #${generatedAnchor}`,
         Date.now() - startTime,
       );
     }