npm - jamdesk - Versions diffs - 1.0.12 → 1.0.13 - Mend

jamdesk 1.0.12 → 1.0.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/dist/lib/deps.js +3 -3
package/package.json +2 -2
package/vendored/app/layout.tsx +9 -119
package/vendored/lib/analytics-script.ts +147 -0
package/vendored/lib/heading-extractor.ts +117 -0
package/vendored/lib/mdx.ts +1 -1
package/vendored/scripts/validate-links.cjs +216 -48

package/dist/lib/deps.js CHANGED Viewed

@@ -54,7 +54,7 @@ const REQUIRED_DEPS = {
     'remark-math': '^6.0.0',
     'remark-smartypants': '^3.0.2',
     // Math/LaTeX rendering
-    'katex': '^0.16.28',
+    'katex': '^0.16.33',
     // Diagrams
     'mermaid': '^11.12.2',
     // YAML parsing (for OpenAPI specs)
@@ -70,8 +70,8 @@ const REQUIRED_DEPS = {
     'unist-util-visit': '^5.0.0',
     'hast': '^1.0.0',
     // CSS
-    'tailwindcss': '^4.2.0',
-    '@tailwindcss/postcss': '^4.2.0',
+    'tailwindcss': '^4.2.1',
+    '@tailwindcss/postcss': '^4.2.1',
     '@tailwindcss/typography': '^0.5.10',
     'postcss': '^8.4.32',
     'autoprefixer': '^10.4.24',

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "CLI for Jamdesk — build, preview, and deploy documentation sites from MDX. Dev server with hot reload, 50+ components, OpenAPI support, AI search, and Mintlify migration",
   "keywords": [
     "jamdesk",
@@ -93,7 +93,7 @@
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
-    "@inquirer/prompts": "^8.1.0",
+    "@inquirer/prompts": "^8.3.0",
     "ajv": "^8.17.1",
     "chalk": "^5.3.0",
     "commander": "^14.0.3",

package/vendored/app/layout.tsx CHANGED Viewed

@@ -16,6 +16,7 @@ import path from 'path';
 import type { DocsConfig, Favicon, FontConfig } from '@/lib/docs-types';
 import { ASSET_PREFIX, transformConfigImagePath } from '@/lib/docs-types';
 import { LinkPrefixProvider } from '@/lib/link-prefix-context';
+import { getAnalyticsScript } from '@/lib/analytics-script';
 // Pre-load fonts - Next.js will tree-shake unused ones
 const inter = Inter({
@@ -223,9 +224,11 @@ export default async function RootLayout({
 }) {
   // Get config - from R2 in ISR mode, from filesystem in static mode
   let config: DocsConfig;
+  let resolvedProjectSlug: string | null = null;
   if (isIsrMode()) {
     const headersList = await headers();
     const projectSlug = getProjectFromRequest(headersList);
+    resolvedProjectSlug = projectSlug;
     const hostAtDocs = getHostAtDocs(headersList);
     if (projectSlug) {
       try {
@@ -279,9 +282,10 @@ export default async function RootLayout({
   // Link prefix for hostAtDocs: when true, MDX component links need /docs prefix
   const linkPrefix = config.hostAtDocs ? '/docs' : '';
-  // Jamdesk Analytics - built-in tracking for all documentation sites
-  // Tracks page views and sends to dashboard analytics endpoint
-  const analyticsEnabled = config.analytics?.enabled !== false; // Default true
+  // Jamdesk Analytics - enabled by default, opt-out via analytics.enabled: false
+  const analyticsScript = config.analytics?.enabled !== false
+    ? getAnalyticsScript(resolvedProjectSlug)
+    : null;
   return (
     <html lang="en" suppressHydrationWarning>
@@ -420,122 +424,8 @@ export default async function RootLayout({
           <style dangerouslySetInnerHTML={{ __html: customCss }} />
         )}
         {/* Jamdesk Analytics - tracks page views for analytics dashboard */}
-        {analyticsEnabled && (
-          <script
-            dangerouslySetInnerHTML={{
-              __html: `
-(function() {
-  // Extract project slug from hostname (e.g., "acme" from "acme.jamdesk.com")
-  var h = location.hostname;
-  var parts = h.split('.');
-  var slug = null;
-  // Check for *.jamdesk.com, *.jamdesk.dev, or *.jamdesk.app subdomains
-  if ((h.endsWith('.jamdesk.com') || h.endsWith('.jamdesk.dev') || h.endsWith('.jamdesk.app')) && parts.length >= 3) {
-    slug = parts[0];
-  }
-  // Skip tracking for localhost or if no valid slug
-  if (!slug || h.indexOf('localhost') !== -1) {
-    console.log('[Jamdesk Analytics] Skipped: no valid project slug');
-    return;
-  }
-  // Generate session ID (persisted for 30 minutes of inactivity)
-  var SESSION_KEY = 'jd_sid';
-  var SESSION_TIMEOUT = 30 * 60 * 1000; // 30 minutes
-  function getSessionId() {
-    var stored = sessionStorage.getItem(SESSION_KEY);
-    var data = stored ? JSON.parse(stored) : null;
-    var now = Date.now();
-    if (data && (now - data.lastActivity) < SESSION_TIMEOUT) {
-      data.lastActivity = now;
-      sessionStorage.setItem(SESSION_KEY, JSON.stringify(data));
-      return data.id;
-    }
-    // New session
-    var newId = Math.random().toString(36).substr(2, 9) + Date.now().toString(36);
-    sessionStorage.setItem(SESSION_KEY, JSON.stringify({ id: newId, lastActivity: now }));
-    return newId;
-  }
-  // Get timezone for country fallback
-  function getTimezone() {
-    try {
-      return Intl.DateTimeFormat().resolvedOptions().timeZone;
-    } catch (e) {
-      return null;
-    }
-  }
-  // Track page view
-  function trackPageView() {
-    var data = {
-      projectSlug: slug,
-      path: location.pathname,
-      referrer: document.referrer || null,
-      userAgent: navigator.userAgent,
-      sessionId: getSessionId(),
-      type: 'pageview',
-      eventId: slug + '-' + location.pathname + '-' + Date.now(),
-      timezone: getTimezone()
-    };
-    // Send to analytics endpoint (proxied via first-party domain to avoid ad blockers)
-    fetch('/_jd/ev', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(data),
-      keepalive: true
-    }).catch(function() { /* Ignore errors */ });
-  }
-  // Track current path to avoid duplicate tracking
-  var lastTrackedPath = location.pathname;
-  // Track page view (with deduplication)
-  function trackIfNewPath() {
-    var currentPath = location.pathname;
-    if (currentPath !== lastTrackedPath) {
-      lastTrackedPath = currentPath;
-      trackPageView();
-    }
-  }
-  // Track initial page view
-  trackPageView();
-  // Track SPA navigation (History API)
-  var origPushState = history.pushState;
-  history.pushState = function() {
-    origPushState.apply(this, arguments);
-    setTimeout(trackIfNewPath, 0);
-  };
-  var origReplaceState = history.replaceState;
-  history.replaceState = function() {
-    origReplaceState.apply(this, arguments);
-    setTimeout(trackIfNewPath, 0);
-  };
-  window.addEventListener('popstate', function() {
-    setTimeout(trackIfNewPath, 0);
-  });
-  // Fallback: Poll for URL changes (catches Next.js soft navigation)
-  setInterval(function() {
-    if (location.pathname !== lastTrackedPath) {
-      lastTrackedPath = location.pathname;
-      trackPageView();
-    }
-  }, 1000);
-})();
-              `,
-            }}
-          />
+        {analyticsScript && (
+          <script dangerouslySetInnerHTML={{ __html: analyticsScript }} />
         )}
       </head>
       <body className={fontClassName} data-theme={themeName || 'jam'}>

package/vendored/lib/analytics-script.ts ADDED Viewed

@@ -0,0 +1,147 @@
+/**
+ * Analytics script generation for ISR layout
+ *
+ * Generates the inline tracking script injected into documentation pages.
+ * The slug can be server-injected (ISR mode) or null (static mode, uses
+ * client-side hostname detection as fallback).
+ */
+/** Same pattern as validSlugPattern in path-safety.ts */
+const SAFE_SLUG_PATTERN = /^[a-z0-9-]+$/;
+/**
+ * Sanitize a project slug for safe injection into an inline <script>.
+ * Only allows lowercase alphanumeric characters and hyphens.
+ * Returns null if the slug is invalid, empty, or contains unsafe characters.
+ */
+export function sanitizeSlugForScript(slug: string | null | undefined): string | null {
+  if (!slug || typeof slug !== 'string') return null;
+  return SAFE_SLUG_PATTERN.test(slug) ? slug : null;
+}
+/**
+ * Generate the analytics tracking script content for inline injection.
+ *
+ * When slug is provided (ISR mode), it's injected directly — works on any domain
+ * including bare domains (jamdesk.com) and custom domains (docs.acme.com).
+ * When slug is null (static mode), falls back to client-side subdomain detection.
+ */
+export function getAnalyticsScript(rawSlug: string | null): string {
+  const slug = sanitizeSlugForScript(rawSlug);
+  const slugLiteral = slug ? `'${slug}'` : 'null';
+  return `
+(function() {
+  var h = location.hostname;
+  // Server-injected slug (ISR mode) or client-side detection (static mode)
+  var slug = ${slugLiteral};
+  // Fallback: extract from subdomain (static/dev mode)
+  if (!slug) {
+    var parts = h.split('.');
+    if ((h.endsWith('.jamdesk.com') || h.endsWith('.jamdesk.dev') || h.endsWith('.jamdesk.app')) && parts.length >= 3) {
+      slug = parts[0];
+    }
+  }
+  // Skip tracking for localhost or if no valid slug
+  if (!slug || h.indexOf('localhost') !== -1) {
+    console.log('[Jamdesk Analytics] Skipped: no valid project slug');
+    return;
+  }
+  // Generate session ID (persisted for 30 minutes of inactivity)
+  var SESSION_KEY = 'jd_sid';
+  var SESSION_TIMEOUT = 30 * 60 * 1000; // 30 minutes
+  function getSessionId() {
+    var stored = sessionStorage.getItem(SESSION_KEY);
+    var data = stored ? JSON.parse(stored) : null;
+    var now = Date.now();
+    if (data && (now - data.lastActivity) < SESSION_TIMEOUT) {
+      data.lastActivity = now;
+      sessionStorage.setItem(SESSION_KEY, JSON.stringify(data));
+      return data.id;
+    }
+    // New session
+    var newId = Math.random().toString(36).substr(2, 9) + Date.now().toString(36);
+    sessionStorage.setItem(SESSION_KEY, JSON.stringify({ id: newId, lastActivity: now }));
+    return newId;
+  }
+  // Get timezone for country fallback
+  function getTimezone() {
+    try {
+      return Intl.DateTimeFormat().resolvedOptions().timeZone;
+    } catch (e) {
+      return null;
+    }
+  }
+  // Track page view
+  function trackPageView() {
+    var data = {
+      projectSlug: slug,
+      path: location.pathname,
+      referrer: document.referrer || null,
+      userAgent: navigator.userAgent,
+      sessionId: getSessionId(),
+      type: 'pageview',
+      eventId: slug + '-' + location.pathname + '-' + Date.now(),
+      timezone: getTimezone()
+    };
+    // Send to analytics endpoint (proxied via first-party domain to avoid ad blockers)
+    fetch('/_jd/ev', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+      keepalive: true
+    }).catch(function() { /* Ignore errors */ });
+  }
+  // Track current path to avoid duplicate tracking
+  var lastTrackedPath = location.pathname;
+  // Track page view (with deduplication)
+  function trackIfNewPath() {
+    var currentPath = location.pathname;
+    if (currentPath !== lastTrackedPath) {
+      lastTrackedPath = currentPath;
+      trackPageView();
+    }
+  }
+  // Track initial page view
+  trackPageView();
+  // Track SPA navigation (History API)
+  var origPushState = history.pushState;
+  history.pushState = function() {
+    origPushState.apply(this, arguments);
+    setTimeout(trackIfNewPath, 0);
+  };
+  var origReplaceState = history.replaceState;
+  history.replaceState = function() {
+    origReplaceState.apply(this, arguments);
+    setTimeout(trackIfNewPath, 0);
+  };
+  window.addEventListener('popstate', function() {
+    setTimeout(trackIfNewPath, 0);
+  });
+  // Fallback: Poll for URL changes (catches Next.js soft navigation)
+  setInterval(function() {
+    if (location.pathname !== lastTrackedPath) {
+      lastTrackedPath = location.pathname;
+      trackPageView();
+    }
+  }, 1000);
+})();
+`;
+}

package/vendored/lib/heading-extractor.ts ADDED Viewed

@@ -0,0 +1,117 @@
+/**
+ * Heading extractor for link validation.
+ * Extracts heading slugs from MDX content to validate #fragment links.
+ *
+ * Uses the same slug generation as TableOfContents.tsx (client-side DOM IDs).
+ */
+export interface HeadingInfo {
+  id: string;
+  text: string;
+  level: number;
+  line: number; // 1-indexed
+}
+/**
+ * Generate a URL-friendly slug from heading text.
+ * Must stay in sync with TableOfContents.tsx:207-209.
+ */
+export function generateSlug(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+const HEADING_REGEX = /^(#{1,6})\s+(.+)$/;
+const FENCE_REGEX = /^(`{3,}|~{3,})/;
+const UPDATE_LABEL_REGEX = /<Update\s+label=["']([^"']+)["']/;
+/**
+ * Extract all heading slugs from MDX content.
+ * Includes markdown headings and <Update label="..."> component anchors.
+ * Skips content inside fenced code blocks.
+ */
+export function extractHeadings(content: string): HeadingInfo[] {
+  const headings: HeadingInfo[] = [];
+  const lines = content.split('\n');
+  let inCodeBlock = false;
+  let fencePattern = '';
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fenceMatch = line.match(FENCE_REGEX);
+    if (fenceMatch) {
+      if (!inCodeBlock) {
+        inCodeBlock = true;
+        fencePattern = fenceMatch[1];
+        continue;
+      } else if (line.startsWith(fencePattern)) {
+        inCodeBlock = false;
+        fencePattern = '';
+        continue;
+      }
+    }
+    if (inCodeBlock) continue;
+    const headingMatch = line.match(HEADING_REGEX);
+    if (headingMatch) {
+      const level = headingMatch[1].length;
+      const text = headingMatch[2].trim();
+      const id = generateSlug(text);
+      if (id) {
+        headings.push({ id, text, level, line: i + 1 });
+      }
+    }
+    const updateMatch = line.match(UPDATE_LABEL_REGEX);
+    if (updateMatch) {
+      const text = updateMatch[1];
+      const id = generateSlug(text);
+      if (id) {
+        headings.push({ id, text, level: 2, line: i + 1 });
+      }
+    }
+  }
+  return headings;
+}
+/**
+ * Check if MDX content has api: or openapi: in its frontmatter.
+ * API endpoint pages generate dynamic anchor IDs at render time (#param-*, etc.)
+ * that aren't in the MDX source, so fragment validation is skipped for them.
+ */
+function hasApiFrontmatter(content: string): boolean {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return false;
+  return /^(openapi|api):/m.test(match[1]);
+}
+/**
+ * Build a map of page path -> heading slug set.
+ * Keys are page paths without .mdx extension (matching docs.json navigation format).
+ * Skips API endpoint pages (they generate dynamic anchors at render time).
+ *
+ * Unlike buildHeadingMapFromFiles() in validate-links.cjs, this doesn't add dual
+ * keys for index pages. The CJS validator handles index resolution via
+ * getTargetHeadingSlugs() which derives the key from the filesystem path.
+ *
+ * @param fileContents - Map of relative file paths (with .mdx) to content.
+ *   Keys come from build.ts fileContents Map (e.g., 'getting-started.mdx', 'api/auth.mdx').
+ */
+export function buildHeadingMap(
+  fileContents: Map<string, string>
+): Map<string, Set<string>> {
+  const map = new Map<string, Set<string>>();
+  for (const [filePath, content] of fileContents) {
+    if (hasApiFrontmatter(content)) continue;
+    const headings = extractHeadings(content);
+    const slugs = new Set(headings.map((h) => h.id));
+    const pagePath = filePath.replace(/\.mdx$/, '');
+    map.set(pagePath, slugs);
+  }
+  return map;
+}

package/vendored/lib/mdx.ts CHANGED Viewed

@@ -68,7 +68,7 @@ export function generateTableOfContents(content: string): { id: string; text: st
     const id = text
       .toLowerCase()
       .replace(/[^a-z0-9]+/g, '-')
-      .replace(/(^-|-$)/g, '');
+      .replace(/^-+|-+$/g, '');
     headings.push({ id, text, level });
   }

package/vendored/scripts/validate-links.cjs CHANGED Viewed

@@ -65,10 +65,10 @@ function getProjectDir() {
  * - MDX/JSX href props: href="/docs/path" or href="./relative"
  */
 const LINK_PATTERNS = [
-  // Markdown links: [text](href) - capture the href
-  /\[(?:[^\]]*)\]\(([^)#\s][^)#]*)\)/g,
+  // Markdown links: [text](href) - capture href including optional #fragment
+  /\[(?:[^\]]*)\]\(([^)\s]+)\)/g,
   // JSX href attribute: href="..." or href='...'
-  /href=["']([^"'#\s][^"'#]*)["']/g,
+  /href=["']([^"'\s]+)["']/g,
 ];
 /**
@@ -82,8 +82,8 @@ function shouldSkipLink(href) {
   if (/^mailto:/.test(href)) return true;
   if (/^tel:/.test(href)) return true;
-  // Skip anchor-only links
-  if (href.startsWith('#')) return true;
+  // Skip empty anchor (#) - fragment-only links (#heading) are validated separately
+  if (href === '#') return true;
   // Skip image/asset paths (handles dimension syntax like =500x, =x200, =300x200)
   // Strips any trailing dimension suffix before checking extension
@@ -96,6 +96,22 @@ function shouldSkipLink(href) {
   return false;
 }
+/**
+ * Split href into path and fragment parts.
+ * '#heading' → { path: null, fragment: 'heading' }
+ * '/page#heading' → { path: '/page', fragment: 'heading' }
+ * '/page' → { path: '/page', fragment: null }
+ * '#' → { path: null, fragment: null } (empty fragment)
+ */
+function splitFragment(href) {
+  const hashIndex = href.indexOf('#');
+  if (hashIndex === -1) return { path: href, fragment: null };
+  return {
+    path: hashIndex === 0 ? null : href.substring(0, hashIndex),
+    fragment: href.substring(hashIndex + 1) || null,
+  };
+}
 /**
  * Resolve a link to a file path
  * @param {string} href - The link href
@@ -191,46 +207,192 @@ function isInCodeBlock(lineNumber, ranges) {
   return ranges.some(([start, end]) => lineNumber >= start && lineNumber <= end);
 }
+/**
+ * Generate URL-friendly slug. Must match TableOfContents.tsx:207-209.
+ */
+function generateSlug(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+/**
+ * Extract heading slugs from MDX content.
+ * Includes markdown headings and <Update label="..."> component anchors.
+ * Skips content inside fenced code blocks.
+ *
+ * Uses single-pass fence tracking (matches heading-extractor.ts pattern).
+ */
+function extractHeadingSlugs(content) {
+  const slugs = new Set();
+  const lines = content.split('\n');
+  let inCodeBlock = false;
+  let fencePattern = '';
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fenceMatch = line.match(/^(`{3,}|~{3,})/);
+    if (fenceMatch) {
+      if (!inCodeBlock) {
+        inCodeBlock = true;
+        fencePattern = fenceMatch[1];
+        continue;
+      } else if (line.startsWith(fencePattern)) {
+        inCodeBlock = false;
+        fencePattern = '';
+        continue;
+      }
+    }
+    if (inCodeBlock) continue;
+    const headingMatch = line.match(/^#{1,6}\s+(.+)$/);
+    if (headingMatch) {
+      const slug = generateSlug(headingMatch[1].trim());
+      if (slug) slugs.add(slug);
+    }
+    const updateMatch = line.match(/<Update\s+label=["']([^"']+)["']/);
+    if (updateMatch) {
+      const slug = generateSlug(updateMatch[1]);
+      if (slug) slugs.add(slug);
+    }
+  }
+  return slugs;
+}
+/**
+ * Check if MDX content has api: or openapi: in its frontmatter.
+ * API endpoint pages generate dynamic anchor IDs at render time (#param-*, etc.)
+ * that aren't in the MDX source, so fragment validation is skipped for them.
+ */
+function hasApiFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return false;
+  return /^(openapi|api):/m.test(match[1]);
+}
+/**
+ * Build heading map for all navigation pages by reading files from disk.
+ * Used by CLI path (no cached fileContents available).
+ * Handles directory index pages: if "api" is in navigation but only api/index.mdx
+ * exists, stores headings under both "api" (navigation key) and "api/index"
+ * (resolved key used by getTargetHeadingSlugs).
+ * Skips API endpoint pages (they generate dynamic anchors at render time).
+ */
+function buildHeadingMapFromFiles(contentDir, navigationPages) {
+  const map = new Map();
+  for (const pagePath of navigationPages) {
+    const mdxPath = path.join(contentDir, pagePath + '.mdx');
+    const indexPath = path.join(contentDir, pagePath, 'index.mdx');
+    if (fs.existsSync(mdxPath)) {
+      const content = fs.readFileSync(mdxPath, 'utf8');
+      if (hasApiFrontmatter(content)) continue;
+      map.set(pagePath, extractHeadingSlugs(content));
+    } else if (fs.existsSync(indexPath)) {
+      const content = fs.readFileSync(indexPath, 'utf8');
+      if (hasApiFrontmatter(content)) continue;
+      const slugs = extractHeadingSlugs(content);
+      map.set(pagePath, slugs);             // nav key: "api"
+      map.set(pagePath + '/index', slugs);  // resolved key: "api/index"
+    }
+  }
+  return map;
+}
+/**
+ * Look up heading slugs for a resolved target path.
+ * Derives the page path key from the resolved filesystem path.
+ * Falls back to pagePath/index for directory index pages.
+ */
+function getTargetHeadingSlugs(targetPath, contentDir, headingMap) {
+  let resolvedFile = null;
+  if (fs.existsSync(targetPath) && fs.statSync(targetPath).isFile()) {
+    resolvedFile = targetPath;
+  } else if (fs.existsSync(targetPath + '.mdx')) {
+    resolvedFile = targetPath + '.mdx';
+  } else if (fs.existsSync(path.join(targetPath, 'index.mdx'))) {
+    resolvedFile = path.join(targetPath, 'index.mdx');
+  }
+  if (!resolvedFile) return null;
+  const pagePath = path.relative(contentDir, resolvedFile).replace(/\.mdx$/, '');
+  return headingMap.get(pagePath) || null;
+}
 /**
  * Find all links in an MDX file and validate them
  */
-function validateFile(filePath, contentDir, results) {
+function validateFile(filePath, contentDir, results, headingMap) {
   const content = fs.readFileSync(filePath, 'utf8');
   const relativePath = path.relative(contentDir, filePath);
-  // Get code block ranges to skip links inside them
+  const currentPagePath = relativePath.replace(/\.mdx$/, '');
   const codeBlockRanges = getCodeBlockRanges(content);
   for (const pattern of LINK_PATTERNS) {
-    // Reset regex state
     pattern.lastIndex = 0;
     let match;
     while ((match = pattern.exec(content)) !== null) {
-      const href = match[1];
-      // Calculate line number first (needed for code block check)
+      const rawHref = match[1];
       const upToMatch = content.substring(0, match.index);
       const lineNumber = upToMatch.split('\n').length;
-      // Skip links inside code blocks
       if (isInCodeBlock(lineNumber, codeBlockRanges)) continue;
-      // Skip links we shouldn't validate
-      if (shouldSkipLink(href)) continue;
+      // Split href into path and fragment BEFORE any other processing
+      const { path: linkPath, fragment } = splitFragment(rawHref);
+      // Same-page fragment only (e.g., #heading)
+      // currentSlugs is null for API pages (skipped during heading map construction)
+      if (!linkPath && fragment) {
+        const currentSlugs = headingMap.get(currentPagePath);
+        if (currentSlugs && !currentSlugs.has(fragment)) {
+          results.push({
+            type: 'broken_link',
+            file: relativePath,
+            line: lineNumber,
+            link: rawHref,
+            message: 'Fragment #' + fragment + ' not found in headings',
+          });
+        }
+        continue;
+      }
+      // Has path component — validate path first
+      if (!linkPath) continue;
-      // Resolve the link to a file path
-      const targetPath = resolveLink(href, filePath, contentDir);
+      if (shouldSkipLink(linkPath)) continue;
+      const targetPath = resolveLink(linkPath, filePath, contentDir);
       if (!targetPath) continue;
-      // Check if target exists
       if (!targetExists(targetPath)) {
+        // Page missing — report without fragment message
         results.push({
           type: 'broken_link',
           file: relativePath,
           line: lineNumber,
-          link: href,
+          link: rawHref,
         });
+        continue;
+      }
+      // Page exists + has fragment — validate fragment
+      if (fragment) {
+        const targetSlugs = getTargetHeadingSlugs(targetPath, contentDir, headingMap);
+        if (targetSlugs && !targetSlugs.has(fragment)) {
+          results.push({
+            type: 'broken_link',
+            file: relativePath,
+            line: lineNumber,
+            link: rawHref,
+            message: 'Fragment #' + fragment + ' not found in headings',
+          });
+        }
       }
     }
   }
@@ -338,7 +500,8 @@ function getNavigationPages(contentDir) {
 function validateNavigation(contentDir, navigationPages, results) {
   for (const pagePath of navigationPages) {
     const mdxPath = path.join(contentDir, pagePath + '.mdx');
-    if (!fs.existsSync(mdxPath)) {
+    const indexPath = path.join(contentDir, pagePath, 'index.mdx');
+    if (!fs.existsSync(mdxPath) && !fs.existsSync(indexPath)) {
       results.push({
         type: 'broken_link',
         file: 'docs.json',
@@ -354,7 +517,8 @@ function validateNavigation(contentDir, navigationPages, results) {
  * Only validates pages that are part of docs.json navigation.
  * Files that exist but aren't in the navigation are ignored.
  */
-function validateProject() {
+function validateProject(options) {
+  options = options || {};
   const contentDir = getProjectDir();
   const results = [];
@@ -365,45 +529,49 @@ function validateProject() {
     return results;
   }
-  // Get all pages from docs.json navigation
   const navigationPages = getNavigationPages(contentDir);
-  // Validate that all navigation pages exist
   validateNavigation(contentDir, navigationPages, results);
-  // Only validate links within files that are part of the navigation
-  // This ignores orphan files (like ar/ translations not in docs.json)
+  // Build heading map: use provided one or build from files
+  const headingMap = options.headingMap || buildHeadingMapFromFiles(contentDir, navigationPages);
   for (const pagePath of navigationPages) {
     const mdxPath = path.join(contentDir, pagePath + '.mdx');
+    const indexPath = path.join(contentDir, pagePath, 'index.mdx');
     if (fs.existsSync(mdxPath)) {
-      validateFile(mdxPath, contentDir, results);
+      validateFile(mdxPath, contentDir, results, headingMap);
+    } else if (fs.existsSync(indexPath)) {
+      validateFile(indexPath, contentDir, results, headingMap);
     }
   }
   return results;
 }
-// Main execution
-const warnings = validateProject();
-if (jsonOutput) {
-  // Output JSON for programmatic use
-  console.log(JSON.stringify(warnings, null, 2));
-} else if (warnings.length > 0) {
-  // Human-readable output
-  console.log(`\n⚠️  Found ${warnings.length} broken internal link(s):\n`);
-  for (const w of warnings) {
-    const location = w.line ? `${w.file}:${w.line}` : w.file;
-    console.log(`  ${location}`);
-    console.log(`    Missing page: ${w.link}`);
-    console.log('');
-  }
+// Main execution (CLI mode only)
+if (require.main === module) {
+  const warnings = validateProject();
+  if (jsonOutput) {
+    console.log(JSON.stringify(warnings, null, 2));
+  } else if (warnings.length > 0) {
+    console.log(`\n⚠️  Found ${warnings.length} broken internal link(s):\n`);
+    for (const w of warnings) {
+      const location = w.line ? `${w.file}:${w.line}` : w.file;
+      console.log(`  ${location}`);
+      if (w.message) {
+        console.log(`    ${w.message}: ${w.link}`);
+      } else {
+        console.log(`    Missing page: ${w.link}`);
+      }
+      console.log('');
+    }
-  console.log('  These pages are referenced but do not exist.');
-  console.log('  Please check for typos or create the missing pages.\n');
-} else {
-  console.log('✓ No broken internal links found');
+    console.log('  Please check for typos, create missing pages, or fix broken anchors.\n');
+  } else {
+    console.log('✓ No broken internal links found');
+  }
 }
 // Export for programmatic use