@writechoice/mint-cli 0.0.6 → 0.0.7

package/README.md

@@ -91,6 +91,20 @@ writechoice check links docs.example.com https://staging.example.com
 
 The validation base URL is only used for online checks. Local file validation remains unchanged for optimal performance.
 
+**How the two-step validation works:**
+
+For anchor links, the tool performs a smart validation:
+
+1. Navigates to your production docs (base URL) to find the actual heading the anchor points to
+2. Then navigates to your local dev server (validation URL) and clicks the same heading to see what anchor it generates
+3. Compares the two anchors to detect mismatches
+
+This is useful because:
+
+- Link text in MDX files may differ from actual heading text
+- Handles pages with duplicate headings correctly by matching position
+- Validates against your local development environment before deploying
+
 ### Common Options
 
 ```bash
@@ -165,14 +179,13 @@ The tool extracts internal links from MDX files in the following formats:
 1. **Local Validation**: First checks if the target MDX file exists locally
    - For normal links: Verifies the file exists in the repository
    - For anchor links: Checks if the heading exists in the MDX file with matching kebab-case format
-2. **Online Validation**: If local check fails, uses Playwright to navigate to the validation base URL
-   - For normal links: Verifies the page loads successfully
-   - For anchor links:
-     - Finds the heading on the page by text matching
-     - Clicks on the heading to trigger anchor generation
-     - Extracts the generated anchor from the URL or href attribute
-     - Compares the generated anchor with the expected anchor
-3. **Validation Base URL**: By default uses `http://localhost:3000` for online validation, or you can specify a custom URL (e.g., staging environment)
+2. **Online Validation**: If local check fails, performs a two-step validation process
+   - For normal links: Navigates to the validation base URL and verifies the page loads successfully
+   - For anchor links (two-step process):
+     1. **Step 1 - Find the target heading**: Navigates to the base URL (production docs) with the anchor to identify which heading the anchor points to and its position (handles duplicate headings)
+     2. **Step 2 - Get generated anchor**: Navigates to the validation base URL (e.g., localhost:3000), finds the same heading (by text and position), clicks it to trigger anchor generation, and extracts the generated anchor from the URL
+     3. Compares the generated anchor with the expected anchor from the MDX file
+3. **Validation Base URL**: By default uses `http://localhost:3000` for online validation, or you can specify a custom URL (e.g., staging environment). This allows testing against a local development server or staging environment while validating links meant for production.
 4. **Auto-Fix**: When issues are found, can automatically update MDX files with the correct anchors
 
 ### Report Format
@@ -195,14 +208,6 @@ The tool generates a JSON report with the following structure:
     "failure": 8,
     "error": 2
   },
-  "summary_by_file": {
-    "docs/getting-started.mdx": {
-      "total": 10,
-      "success": 9,
-      "failure": 1,
-      "error": 0
-    }
-  },
   "results_by_file": {
     "docs/getting-started.mdx": [
       {

package/package.json

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

package/src/commands/validate/links.js

@@ -26,6 +26,8 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 // Configuration
+
+const DEFAULT_SPACE = "                   ";
 const DEFAULT_BASE_URL = "https://docs.nebius.com";
 const EXCLUDED_DIRS = ["snippets"];
 const MDX_DIRS = ["."];
@@ -44,12 +46,14 @@ const LINK_PATTERNS = {
 
 // Data Structures
 class LinkLocation {
-  constructor(filePath, lineNumber, linkText, rawHref, linkType) {
+  constructor(filePath, lineNumber, linkText, rawHref, linkType, sourceUrl, targetUrl) {
     this.filePath = filePath;
     this.lineNumber = lineNumber;
     this.linkText = linkText;
     this.rawHref = rawHref;
     this.linkType = linkType;
+    this.sourceUrl = sourceUrl;
+    this.targetUrl = targetUrl;
   }
 }
 
@@ -66,6 +70,7 @@ class Link {
 class ValidationResult {
   constructor(
     source,
+    sourceUrl,
     targetUrl,
     basePath,
     anchor,
@@ -73,11 +78,12 @@ class ValidationResult {
     status,
     actualUrl = null,
     actualHeading = null,
-    actualHeadingKebab = null,
+    actualHeadingAnchor = null,
     errorMessage = null,
     validationTimeMs = 0,
   ) {
     this.source = source;
+    this.sourceUrl = sourceUrl;
     this.targetUrl = targetUrl;
     this.basePath = basePath;
     this.anchor = anchor;
@@ -85,7 +91,7 @@ class ValidationResult {
     this.status = status;
     this.actualUrl = actualUrl;
     this.actualHeading = actualHeading;
-    this.actualHeadingKebab = actualHeadingKebab;
+    this.actualHeadingAnchor = actualHeadingAnchor;
     this.errorMessage = errorMessage;
     this.validationTimeMs = validationTimeMs;
   }
@@ -199,7 +205,7 @@ function extractMdxHeadings(filePath) {
   }
 }
 
-function extractLinksFromFile(filePath, baseUrl, repoRoot, verbose = false) {
+function extractLinksFromFile(filePath, baseUrl, validationBaseUrl, repoRoot, verbose = false) {
   if (verbose) {
     console.log(`  Extracting links from ${relative(repoRoot, filePath)}`);
   }
@@ -215,6 +221,12 @@ function extractLinksFromFile(filePath, baseUrl, repoRoot, verbose = false) {
   const { cleanedContent } = removeCodeBlocksAndFrontmatter(content);
   const links = [];
 
+  // Calculate source URLs from file path
+  const relativeFilePath = relative(repoRoot, filePath);
+  const urlPath = relativeFilePath.replace(/\.mdx$/, "").replace(/\/index$/, "");
+  const fileSourceUrl = normalizeUrl(`${baseUrl}/${urlPath}`);
+  const fileTargetUrl = normalizeUrl(`${validationBaseUrl}/${urlPath}`);
+
   // Collect all image positions to skip them
   const imagePositions = new Set();
 
@@ -253,6 +265,8 @@ function extractLinksFromFile(filePath, baseUrl, repoRoot, verbose = false) {
         linkText.trim(),
         href,
         "markdown",
+        fileSourceUrl,
+        fileTargetUrl,
       );
 
       const [basePath, anchor = ""] = targetUrl.split("#");
@@ -278,6 +292,8 @@ function extractLinksFromFile(filePath, baseUrl, repoRoot, verbose = false) {
         linkText.trim(),
         href,
         "html",
+        fileSourceUrl,
+        fileTargetUrl,
       );
 
       const [basePath, anchor = ""] = targetUrl.split("#");
@@ -303,6 +319,8 @@ function extractLinksFromFile(filePath, baseUrl, repoRoot, verbose = false) {
         linkText.trim(),
         href,
         "jsx",
+        fileSourceUrl,
+        fileTargetUrl,
       );
 
       const [basePath, anchor = ""] = targetUrl.split("#");
@@ -328,6 +346,8 @@ function extractLinksFromFile(filePath, baseUrl, repoRoot, verbose = false) {
         linkText.trim(),
         href,
         "jsx",
+        fileSourceUrl,
+        fileTargetUrl,
       );
 
       const [basePath, anchor = ""] = targetUrl.split("#");
@@ -382,7 +402,7 @@ async function validateAnchor(page, link, baseUrl, validationBaseUrl, repoRoot,
 
   try {
     if (verbose) {
-      console.log(`${progress}    Validating anchor: ${link.anchor}`);
+      console.log(`${progress} -> Validating anchor: ${link.anchor}`);
     }
 
     // OPTIMIZATION: Check if anchor exists in local MDX file first (local validation)
@@ -394,11 +414,14 @@ async function validateAnchor(page, link, baseUrl, validationBaseUrl, repoRoot,
       if (mdxHeadingsKebab.includes(link.anchor)) {
         const heading = mdxHeadings.find((h) => toKebabCase(h) === link.anchor);
         if (verbose) {
-          console.log(`${progress}      ✓ Anchor validated locally in MDX file`);
+          console.log(`${DEFAULT_SPACE}✓ Anchor validated locally in MDX file`);
         }
+        // Construct validation URL
+        const validationTargetUrl = link.targetUrl.replace(baseUrl, validationBaseUrl);
         return new ValidationResult(
           link.source,
-          link.targetUrl,
+          link.targetUrl, // sourceUrl (production)
+          validationTargetUrl, // targetUrl (validation)
           link.basePath,
           link.anchor,
           link.expectedSlug,
@@ -410,50 +433,53 @@ async function validateAnchor(page, link, baseUrl, validationBaseUrl, repoRoot,
           Date.now() - startTime,
         );
       } else if (verbose) {
-        console.log(`${progress}      Anchor not found in local MDX, checking online...`);
+        console.log(`${DEFAULT_SPACE}Anchor not found in local MDX, checking online...`);
       }
     }
 
-    // ONLINE VALIDATION: Use validation base URL to navigate and click on headings
-    // Convert the base path to use the validation base URL
-    const validationUrl = link.basePath.replace(baseUrl, validationBaseUrl);
-
+    // ONLINE VALIDATION: Two-step process
+    // Step 1: Navigate to the base URL (production docs) to find the actual heading
     if (verbose) {
-      console.log(`${progress}      Navigating to: ${validationUrl}`);
+      console.log(`${DEFAULT_SPACE}Step 1: Navigating to base URL to find heading: ${link.targetUrl}`);
     }
 
-    // Navigate to validation page
-    await page.goto(validationUrl, { waitUntil: "networkidle", timeout: DEFAULT_TIMEOUT });
-
-    // Extract headings from the MDX file to find the matching heading text
-    let targetHeadingText = null;
+    await page.goto(link.targetUrl, { waitUntil: "networkidle", timeout: DEFAULT_TIMEOUT });
 
-    if (mdxFilePath && existsSync(mdxFilePath)) {
-      const mdxHeadings = extractMdxHeadings(mdxFilePath);
-      const mdxHeadingsKebab = mdxHeadings.map((h) => toKebabCase(h));
-
-      // Find the heading that matches our anchor
-      const headingIndex = mdxHeadingsKebab.indexOf(link.anchor);
-      if (headingIndex !== -1) {
-        targetHeadingText = mdxHeadings[headingIndex];
-        if (verbose) {
-          console.log(`${progress}      Looking for heading: "${targetHeadingText}"`);
-        }
-      }
+    // Try to find the heading by the anchor ID
+    let targetHeading = await page.$(`#${link.anchor}`);
+    if (!targetHeading) {
+      targetHeading = await page.$(`[id="${link.anchor}"]`);
     }
 
-    // If we couldn't find the heading text from MDX, try to find it by the link text
-    if (!targetHeadingText && link.source.linkText) {
-      targetHeadingText = link.source.linkText;
+    // If we still can't find it, try scrolling to the anchor via hash navigation
+    if (!targetHeading) {
       if (verbose) {
-        console.log(`${progress}      Using link text as heading: "${targetHeadingText}"`);
+        console.log(`${DEFAULT_SPACE}Heading not found by ID, checking if page scrolled to anchor...`);
+      }
+
+      // Get all headings and see if any are in the viewport (likely scrolled to)
+      const headings = await page.$$("h1, h2, h3, h4, h5, h6");
+      for (const heading of headings) {
+        const isInViewport = await heading.isVisible();
+        const boundingBox = await heading.boundingBox();
+
+        // Check if heading is near the top of the viewport (likely the anchor target)
+        if (isInViewport && boundingBox && boundingBox.y < 300) {
+          const headingId = await heading.getAttribute("id");
+          if (headingId === link.anchor) {
+            targetHeading = heading;
+            break;
+          }
+        }
       }
     }
 
-    if (!targetHeadingText) {
+    if (!targetHeading) {
+      const validationTargetUrl = link.basePath.replace(baseUrl, validationBaseUrl);
       return new ValidationResult(
         link.source,
-        link.targetUrl,
+        link.targetUrl, // sourceUrl (production)
+        validationTargetUrl, // targetUrl (validation)
         link.basePath,
         link.anchor,
         link.expectedSlug,
@@ -461,128 +487,163 @@ async function validateAnchor(page, link, baseUrl, validationBaseUrl, repoRoot,
         null,
         null,
         null,
-        `Could not determine heading text to search for anchor #${link.anchor}`,
+        `Anchor #${link.anchor} not found on base URL page`,
         Date.now() - startTime,
       );
     }
 
-    // Find all headings on the page
-    const headings = await page.$$("h1, h2, h3, h4, h5, h6");
-    let matchedHeading = null;
-    let matchedHeadingText = null;
+    // Get the actual heading text from the base URL
+    const actualHeadingText = await targetHeading.innerText();
+    const actualHeadingTextClean = cleanHeadingText(actualHeadingText);
 
-    // Try to find the heading by text matching
-    for (const heading of headings) {
-      const headingText = await heading.innerText();
+    if (verbose) {
+      console.log(`${DEFAULT_SPACE}Found heading on base URL: "${actualHeadingTextClean}"`);
+    }
+
+    // Get all headings on the page to determine the index of this heading (for duplicates)
+    const allHeadings = await page.$$("h1, h2, h3, h4, h5, h6");
+    let targetHeadingIndex = -1;
+    const headingsWithSameText = [];
+
+    for (let i = 0; i < allHeadings.length; i++) {
+      const headingText = await allHeadings[i].innerText();
       const headingTextClean = cleanHeadingText(headingText);
 
-      // Try exact match first
-      if (headingTextClean.toLowerCase() === targetHeadingText.toLowerCase()) {
-        matchedHeading = heading;
-        matchedHeadingText = headingTextClean;
-        if (verbose) {
-          console.log(`${progress}      Found exact match: "${headingTextClean}"`);
+      if (headingTextClean.toLowerCase() === actualHeadingTextClean.toLowerCase()) {
+        headingsWithSameText.push(i);
+
+        // Check if this is our target heading
+        const isSameElement = await page.evaluate(({ h1, h2 }) => h1 === h2, { h1: targetHeading, h2: allHeadings[i] });
+
+        if (isSameElement) {
+          targetHeadingIndex = headingsWithSameText.length - 1; // Index within headings with same text
         }
-        break;
       }
+    }
 
-      // Try partial match
-      if (
-        headingTextClean.toLowerCase().includes(targetHeadingText.toLowerCase()) ||
-        targetHeadingText.toLowerCase().includes(headingTextClean.toLowerCase())
-      ) {
-        if (!matchedHeading) {
-          matchedHeading = heading;
-          matchedHeadingText = headingTextClean;
-          if (verbose) {
-            console.log(`${progress}      Found partial match: "${headingTextClean}"`);
-          }
-        }
+    if (verbose) {
+      console.log(
+        `${DEFAULT_SPACE}Heading occurrence: ${targetHeadingIndex + 1} of ${headingsWithSameText.length} with text "${actualHeadingTextClean}"`,
+      );
+    }
+
+    // Step 2: Navigate to the validation URL (localhost) to get the generated anchor
+    const validationUrl = link.basePath.replace(baseUrl, validationBaseUrl);
+
+    if (verbose) {
+      console.log(`${DEFAULT_SPACE}Step 2: Navigating to validation URL: ${validationUrl}`);
+    }
+
+    await page.goto(validationUrl, { waitUntil: "networkidle", timeout: DEFAULT_TIMEOUT });
+
+    // Find the same heading on the validation page (by text and index)
+    const validationHeadings = await page.$$("h1, h2, h3, h4, h5, h6");
+    const matchingHeadings = [];
+
+    for (const heading of validationHeadings) {
+      const headingText = await heading.innerText();
+      const headingTextClean = cleanHeadingText(headingText);
+
+      if (headingTextClean.toLowerCase() === actualHeadingTextClean.toLowerCase()) {
+        matchingHeadings.push(heading);
       }
     }
 
-    if (!matchedHeading) {
+    if (matchingHeadings.length === 0) {
+      const validationTargetUrl = validationUrl;
       return new ValidationResult(
         link.source,
-        link.targetUrl,
+        link.targetUrl, // sourceUrl (production)
+        validationTargetUrl, // targetUrl (validation)
         link.basePath,
         link.anchor,
         link.expectedSlug,
         "failure",
         null,
+        actualHeadingTextClean,
         null,
-        null,
-        `Heading "${targetHeadingText}" not found on page`,
+        `Heading "${actualHeadingTextClean}" found on base URL but not on validation URL`,
         Date.now() - startTime,
       );
     }
 
-    // Click the heading to trigger anchor generation
+    // Use the same index to handle duplicate headings
+    const targetValidationHeading = matchingHeadings[Math.min(targetHeadingIndex, matchingHeadings.length - 1)];
+
     if (verbose) {
-      console.log(`${progress}      Clicking heading to get generated anchor...`);
+      console.log(
+        `${DEFAULT_SPACE}Found matching heading on validation page (${targetHeadingIndex + 1} of ${matchingHeadings.length})`,
+      );
+      console.log(`${DEFAULT_SPACE}Clicking heading to get generated anchor...`);
     }
 
-    // Try to click on the heading element or a link inside it
-    let clickTarget = matchedHeading;
-    const linkInHeading = await matchedHeading.$("a");
+    // Click the heading to get the generated anchor
+    let clickTarget = targetValidationHeading;
+    const linkInHeading = await targetValidationHeading.$("a");
     if (linkInHeading) {
       clickTarget = linkInHeading;
     }
 
     await clickTarget.click();
 
-    // Wait a bit for any JavaScript to update the URL
+    // Wait for URL update
     await page.waitForTimeout(500);
 
-    // Get the current URL to extract the anchor
+    // Extract the generated anchor
     const currentUrl = page.url();
     let generatedAnchor = null;
 
     if (currentUrl.includes("#")) {
       generatedAnchor = currentUrl.split("#")[1];
       if (verbose) {
-        console.log(`${progress}      Generated anchor from URL: #${generatedAnchor}`);
+        console.log(`${DEFAULT_SPACE}Generated anchor from URL: #${generatedAnchor}`);
       }
     }
 
-    // If no anchor in URL, try to get it from the href attribute of the link
+    // If no anchor in URL, try to get it from the href attribute
     if (!generatedAnchor && linkInHeading) {
       const href = await linkInHeading.getAttribute("href");
       if (href && href.includes("#")) {
         generatedAnchor = href.split("#")[1];
         if (verbose) {
-          console.log(`${progress}      Generated anchor from href: #${generatedAnchor}`);
+          console.log(`${DEFAULT_SPACE}Generated anchor from href: #${generatedAnchor}`);
         }
       }
     }
 
     if (!generatedAnchor) {
+      const validationTargetUrl = validationUrl;
       return new ValidationResult(
         link.source,
-        link.targetUrl,
+        link.targetUrl, // sourceUrl (production)
+        validationTargetUrl, // targetUrl (validation)
         link.basePath,
         link.anchor,
         link.expectedSlug,
         "failure",
         null,
-        matchedHeadingText,
+        actualHeadingTextClean,
         null,
-        `Could not extract generated anchor after clicking heading "${matchedHeadingText}"`,
+        `Could not extract generated anchor after clicking heading "${actualHeadingTextClean}"`,
         Date.now() - startTime,
       );
     }
 
     // Compare the generated anchor with the expected anchor
+    // Construct the full validation URL with the generated anchor
+    const validationTargetUrl = generatedAnchor ? `${validationUrl}#${generatedAnchor}` : validationUrl;
+
     if (generatedAnchor === link.anchor) {
       return new ValidationResult(
         link.source,
-        link.targetUrl,
+        link.targetUrl, // sourceUrl (production)
+        validationTargetUrl, // targetUrl (validation with generated anchor)
         link.basePath,
         link.anchor,
         link.expectedSlug,
         "success",
         link.basePath,
-        matchedHeadingText,
+        actualHeadingTextClean,
         generatedAnchor,
         null,
         Date.now() - startTime,
@@ -590,22 +651,25 @@ async function validateAnchor(page, link, baseUrl, validationBaseUrl, repoRoot,
     } else {
       return new ValidationResult(
         link.source,
-        link.targetUrl,
+        link.targetUrl, // sourceUrl (production)
+        validationTargetUrl, // targetUrl (validation with generated anchor)
         link.basePath,
         link.anchor,
         link.expectedSlug,
         "failure",
         null,
-        matchedHeadingText,
+        actualHeadingTextClean,
         generatedAnchor,
-        `Expected anchor "#${link.anchor}" but page generates "#${generatedAnchor}" for heading "${matchedHeadingText}"`,
+        `Expected anchor "#${link.anchor}" but page generates "#${generatedAnchor}" for heading "${actualHeadingTextClean}"`,
         Date.now() - startTime,
       );
     }
   } catch (error) {
+    const validationTargetUrl = link.targetUrl.replace(baseUrl, validationBaseUrl);
     return new ValidationResult(
       link.source,
-      link.targetUrl,
+      link.targetUrl, // sourceUrl (production)
+      validationTargetUrl, // targetUrl (validation)
       link.basePath,
       link.anchor,
       link.expectedSlug,
@@ -624,18 +688,20 @@ async function validateNormalLink(page, link, baseUrl, validationBaseUrl, repoRo
 
   try {
     if (verbose) {
-      console.log(`${progress}    Validating link: ${link.targetUrl}`);
+      console.log(`${progress} -> Validating link: ${link.targetUrl}`);
     }
 
     // OPTIMIZATION: Check if target MDX file exists locally first
     const mdxFilePath = urlToFilePath(link.targetUrl, baseUrl, repoRoot);
     if (mdxFilePath && existsSync(mdxFilePath)) {
       if (verbose) {
-        console.log(`                   ✓ Link validated locally (file exists)`);
+        console.log(`${DEFAULT_SPACE}✓ Link validated locally (file exists)`);
       }
+      const validationTargetUrl = link.targetUrl.replace(baseUrl, validationBaseUrl);
       return new ValidationResult(
         link.source,
-        link.targetUrl,
+        link.targetUrl, // sourceUrl (production)
+        validationTargetUrl, // targetUrl (validation)
         link.basePath,
         link.anchor,
         link.expectedSlug,
@@ -647,14 +713,14 @@ async function validateNormalLink(page, link, baseUrl, validationBaseUrl, repoRo
         Date.now() - startTime,
       );
     } else if (verbose) {
-      console.log(`                   File not found locally, checking online...`);
+      console.log(`${DEFAULT_SPACE}File not found locally, checking online...`);
     }
 
     // Convert the target URL to use the validation base URL
     const validationUrl = link.targetUrl.replace(baseUrl, validationBaseUrl);
 
     if (verbose) {
-      console.log(`${progress}      Navigating to: ${validationUrl}`);
+      console.log(`${DEFAULT_SPACE}Navigating to: ${validationUrl}`);
     }
 
     // Navigate to the validation URL
@@ -663,7 +729,8 @@ async function validateNormalLink(page, link, baseUrl, validationBaseUrl, repoRo
     if (!response) {
       return new ValidationResult(
         link.source,
-        link.targetUrl,
+        link.targetUrl, // sourceUrl (production)
+        validationUrl, // targetUrl (validation)
         link.basePath,
         link.anchor,
         link.expectedSlug,
@@ -681,7 +748,8 @@ async function validateNormalLink(page, link, baseUrl, validationBaseUrl, repoRo
     if (response.status() >= 400) {
       return new ValidationResult(
         link.source,
-        link.targetUrl,
+        link.targetUrl, // sourceUrl (production)
+        validationUrl, // targetUrl (validation)
         link.basePath,
         link.anchor,
         link.expectedSlug,
@@ -696,7 +764,8 @@ async function validateNormalLink(page, link, baseUrl, validationBaseUrl, repoRo
 
     return new ValidationResult(
       link.source,
-      link.targetUrl,
+      link.targetUrl, // sourceUrl (production)
+      validationUrl, // targetUrl (validation)
       link.basePath,
       link.anchor,
       link.expectedSlug,
@@ -708,9 +777,11 @@ async function validateNormalLink(page, link, baseUrl, validationBaseUrl, repoRo
       Date.now() - startTime,
     );
   } catch (error) {
+    const validationTargetUrl = link.targetUrl.replace(baseUrl, validationBaseUrl);
     return new ValidationResult(
       link.source,
-      link.targetUrl,
+      link.targetUrl, // sourceUrl (production)
+      validationTargetUrl, // targetUrl (validation)
       link.basePath,
       link.anchor,
       link.expectedSlug,
@@ -922,7 +993,7 @@ function fixLinks(results, repoRoot, verbose = false) {
   const failuresByFile = {};
 
   for (const result of results) {
-    if (result.status !== "failure" || !result.actualHeadingKebab || !result.anchor) {
+    if (result.status !== "failure" || !result.actualHeadingAnchor || !result.anchor) {
       continue;
     }
 
@@ -969,7 +1040,7 @@ function fixLinks(results, repoRoot, verbose = false) {
         const linkType = failure.source.linkType;
 
         const pathPart = oldHref.includes("#") ? oldHref.split("#")[0] : oldHref;
-        const newHref = pathPart ? `${pathPart}#${failure.actualHeadingKebab}` : `#${failure.actualHeadingKebab}`;
+        const newHref = pathPart ? `${pathPart}#${failure.actualHeadingAnchor}` : `#${failure.actualHeadingAnchor}`;
 
         if (oldHref === newHref) {
           if (verbose) {
@@ -1073,7 +1144,6 @@ function generateReport(results, config, outputPath) {
       failure,
       error,
     },
-    summary_by_file: summaryByFile,
     results_by_file: resultsByFile,
   };
 
@@ -1138,13 +1208,27 @@ export async function validateLinks(baseUrl, options) {
     console.log(`Found ${mdxFiles.length} MDX files\n`);
   }
 
+  // Normalize validation base URL
+  let normalizedValidationBaseUrl = options.validationBaseUrl || "http://localhost:3000";
+  if (!normalizedValidationBaseUrl.startsWith("http://") && !normalizedValidationBaseUrl.startsWith("https://")) {
+    normalizedValidationBaseUrl = "https://" + normalizedValidationBaseUrl;
+  }
+  // Remove trailing slash
+  normalizedValidationBaseUrl = normalizeUrl(normalizedValidationBaseUrl);
+
   if (options.verbose && !options.quiet) {
     console.log("Extracting links...");
   }
 
   const allLinks = [];
   for (const mdxFile of mdxFiles) {
-    const links = extractLinksFromFile(mdxFile, normalizedBaseUrl, repoRoot, options.verbose && !options.quiet);
+    const links = extractLinksFromFile(
+      mdxFile,
+      normalizedBaseUrl,
+      normalizedValidationBaseUrl,
+      repoRoot,
+      options.verbose && !options.quiet,
+    );
     allLinks.push(...links);
   }
 
@@ -1177,14 +1261,6 @@ export async function validateLinks(baseUrl, options) {
     console.log("\nValidating links...");
   }
 
-  // Normalize validation base URL
-  let normalizedValidationBaseUrl = options.validationBaseUrl || "http://localhost:3000";
-  if (!normalizedValidationBaseUrl.startsWith("http://") && !normalizedValidationBaseUrl.startsWith("https://")) {
-    normalizedValidationBaseUrl = "https://" + normalizedValidationBaseUrl;
-  }
-  // Remove trailing slash
-  normalizedValidationBaseUrl = normalizedValidationBaseUrl.replace(/\/+$/, "");
-
   if (!options.quiet) {
     console.log(`\nUsing validation base URL: ${normalizedValidationBaseUrl}`);
   }

package/src/utils/helpers.js

@@ -8,6 +8,11 @@ import { URL } from 'url';
  * "Create resources\nCreate resources" -> "Create resources"
  */
 export function cleanHeadingText(text) {
+  // Remove zero-width characters and other invisible Unicode characters
+  // This includes: zero-width space, zero-width non-joiner, zero-width joiner,
+  // left-to-right mark, right-to-left mark, etc.
+  text = text.replace(/[\u200B-\u200D\u200E-\u200F\uFEFF]/g, '');
+
   // Split by newlines and get unique parts while preserving order
   const lines = text
     .split('\n')