@udx/md2html 1.0.0

package/index.js

@@ -0,0 +1,738 @@
+#!/usr/bin/env node
+
+/**
+ * UDX Markdown to HTML Converter (md2html)
+ * ========================================
+ * 
+ * ## Usage:
+ * 
+ * Basic conversion: 
+ *    node tools/md2html/index.js --src content/architecture/deploying-with-impunity --out site/static/docs/architecture/deploying-with-impunity/index.html
+ * 
+ * Watch mode: 
+ *    node tools/md2html/index.js --src content/architecture/devsoc-2025 --out site/static/docs/architecture/devsoc-2025/index.html --watch
+ * 
+ * Debug mode: 
+ *    node tools/md2html/index.js --src content/architecture/decentralized-devops --out site/static/docs/architecture/decentralized-devops/index.html --debug
+ * 
+ * ## Purpose:
+ * - Convert a directory of markdown files or a single markdown file into a styled HTML document
+ * - Generate documentation with Google Docs-like formatting for professional presentations
+ * - Support automatic rebuilding of documents when source files change (watch mode)
+ * - Automate documentation generation in CI/CD pipelines
+ * 
+ * ## Inputs:
+ * - Source directory containing markdown files OR a single markdown file
+ * - Output file path for the generated HTML document
+ * - Optional flags for watch mode and debug logging
+ * 
+ * ## Outputs:
+ * - A single HTML document with properly styled content, table of contents, and formatted code blocks
+ * - Debug logs when debug mode is enabled
+ * 
+ * ## Key Features:
+ * - Combines multiple markdown files into a single document, sorted by numeric prefixes
+ * - Extracts metadata from markdown comments (title, author, description, date, version)
+ * - Transforms internal links between markdown files into working anchor links
+ * - Handles images with support for various path resolution strategies
+ * - Generates a table of contents from headings
+ * - Applies syntax highlighting to code blocks
+ * - Supports watch mode for automatic rebuilding
+ * 
+ * @version 1.0.0
+ * @author UDX Team
+ * @copyright 2025
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { marked } from 'marked';
+import { program } from 'commander';
+import chokidar from 'chokidar';
+import Handlebars from 'handlebars';
+
+// Custom renderer for handling math blocks
+const renderer = new marked.Renderer();
+
+// Configure marked to properly handle math blocks
+marked.setOptions({
+  renderer: renderer,
+  gfm: true,
+  breaks: false,
+  pedantic: false,
+  sanitize: false,
+  smartLists: true,
+  smartypants: false
+});
+
+// Add a custom code renderer to handle math blocks
+const originalCodeRenderer = renderer.code.bind(renderer);
+renderer.code = function(code, language) {
+  // Handle math code blocks
+  if (language === 'math') {
+    // Clean up the code by removing any extra backticks or 'math' markers
+    const cleanCode = code.replace(/^```math\s*|```$/g, '');
+    return `<div class="math-block">$$
+${cleanCode}
+$$</div>`;
+  }
+  return originalCodeRenderer(code, language);
+};
+
+// File paths for external resources
+const TEMPLATE_PATH = path.join(path.dirname(new URL(import.meta.url).pathname), 'static/view.hbs');
+const STYLES_PATH = path.join(path.dirname(new URL(import.meta.url).pathname), 'static/styles.css');
+const CHAPTER_NAV_STYLES_PATH = path.join(path.dirname(new URL(import.meta.url).pathname), 'static/chapter-navigation.css');
+const SCRIPTS_PATH = path.join(path.dirname(new URL(import.meta.url).pathname), 'static/scripts.js');
+
+program
+  .version('1.0.0')
+  .description('Convert markdown files to a single HTML document with Google Docs styling')
+  .option('-s, --src <directory>', 'Source directory containing markdown files')
+  .option('-o, --out <file>', 'Output HTML file path')
+  .option('-w, --watch', 'Watch for changes and rebuild automatically', false)
+  .option('-d, --debug', 'Enable debug logging', false)
+  .parse(process.argv);
+
+const options = program.opts();
+
+if (!options.src || !options.out) {
+  console.error('Error: Source directory and output file are required');
+  program.help();
+  process.exit(1);
+}
+
+const srcPath = path.resolve(options.src);
+const outputFile = path.resolve(options.out);
+
+const debug = (message) => {
+  if (options.debug) {
+    console.log(`[DEBUG] ${message}`);
+  }
+};
+
+/**
+ * Builds the HTML document from markdown files
+ * @param {string} srcDir - Source directory containing markdown files
+ * @param {string} outputFile - Output HTML file path
+ * @returns {Promise<boolean>} Success status
+ */
+async function buildHtml(srcDir, outputFile) {
+  debug(`Building HTML from ${srcDir} to ${outputFile}`);
+  
+  try {
+    // Load external templates and styles
+    const templateSource = fs.readFileSync(TEMPLATE_PATH, 'utf8');
+    const cssStyles = fs.readFileSync(STYLES_PATH, 'utf8');
+    const chapterNavStyles = fs.readFileSync(CHAPTER_NAV_STYLES_PATH, 'utf8');
+    const jsScripts = fs.readFileSync(SCRIPTS_PATH, 'utf8');
+    
+    // Register custom Handlebars helpers
+    Handlebars.registerHelper('slugify', function(text) {
+      return text
+        .toString()
+        .toLowerCase()
+        .replace(/\s+/g, '-')           // Replace spaces with -
+        .replace(/[^\w\-]+/g, '')       // Remove all non-word chars
+        .replace(/\-\-+/g, '-')         // Replace multiple - with single -
+        .replace(/^-+/, '')             // Trim - from start of text
+        .replace(/-+$/, '')             // Trim - from end of text
+        .substring(0, 64);              // Limit length
+    });
+    
+    Handlebars.registerHelper('eq', function(a, b) {
+      return a === b;
+    });
+    
+    // Compile Handlebars template
+    const template = Handlebars.compile(templateSource);
+    
+    const srcStat = fs.statSync(srcDir);
+    let markdownFiles = [];
+    
+    if (srcStat.isDirectory()) {
+      const files = fs.readdirSync(srcDir);
+      markdownFiles = files
+        .filter(file => file.endsWith('.md'))
+        .sort((a, b) => {
+          const numA = parseInt(a.match(/^(\d+)_/) ? a.match(/^(\d+)_/)[1] : '999');
+          const numB = parseInt(b.match(/^(\d+)_/) ? b.match(/^(\d+)_/)[1] : '999');
+          return numA - numB;
+        })
+        .map(file => path.join(srcDir, file));
+      
+      debug(`Found ${markdownFiles.length} markdown files`);
+    } else if (srcStat.isFile() && srcDir.endsWith('.md')) {
+      markdownFiles = [srcDir];
+      debug('Processing single markdown file');
+    } else {
+      console.error('Error: Source must be a markdown file or directory containing markdown files');
+      return false;
+    }
+    
+    if (markdownFiles.length === 0) {
+      console.error('Error: No markdown files found');
+      return false;
+    }
+    
+    let combinedMarkdown = '';
+    let title = 'Documentation';
+    let description = 'Generated documentation';
+    let author = 'UDX';
+    let date = new Date().toLocaleDateString('en-US', {
+      year: 'numeric',
+      month: 'long',
+      day: 'numeric'
+    });
+    let version = 'v8';
+    
+    // Process each file and wrap its content in a section
+    for (const file of markdownFiles) {
+      debug(`Processing file: ${file}`);
+      const content = fs.readFileSync(file, 'utf8');
+      const fileName = path.basename(file, '.md');
+      const chapterId = fileName.replace(/^\d+_/, '');
+      
+      // Extract metadata from comments
+      const titleMatch = content.match(/<!--\s*title:\s*(.*?)\s*-->/i);
+      const descMatch = content.match(/<!--\s*description:\s*(.*?)\s*-->/i);
+      const authorMatch = content.match(/<!--\s*author:\s*(.*?)\s*-->/i);
+      const dateMatch = content.match(/<!--\s*date:\s*(.*?)\s*-->/i);
+      const versionMatch = content.match(/<!--\s*version:\s*(.*?)\s*-->/i);
+      
+      if (titleMatch && !title) title = titleMatch[1];
+      if (descMatch) description = descMatch[1];
+      if (authorMatch) author = authorMatch[1];
+      if (dateMatch) date = dateMatch[1];
+      if (versionMatch) version = versionMatch[1];
+      
+      // Extract first heading to use as section title if available
+      const headingMatch = content.match(/^#\s+(.*?)$/m);
+      const sectionTitle = headingMatch ? headingMatch[1] : chapterId;
+      
+      // Add section opening tag with appropriate attributes
+      combinedMarkdown += `<!-- START SECTION: ${fileName} -->\n`;
+      combinedMarkdown += `<section id="${chapterId}" class="content-section" data-chapter-id="${chapterId}" data-file="${fileName}">\n\n`;
+      
+      // Add the file content
+      combinedMarkdown += content;
+      
+      // Add section closing tag
+      combinedMarkdown += `\n\n</section>\n<!-- END SECTION: ${fileName} -->\n\n`;
+    }
+    
+    if (title === 'Documentation') {
+      const headingMatch = combinedMarkdown.match(/^#\s+(.*?)$/m);
+      if (headingMatch) {
+        title = headingMatch[1];
+      }
+    }
+    
+    // Process all mathematical formulas in the content (before image processing)
+    // This pattern matches: $formula$ for inline math
+    const inlineMathPattern = /\$(.*?)\$/g;
+    combinedMarkdown = combinedMarkdown.replace(inlineMathPattern, (match, formula) => {
+      // Skip if it's likely a currency symbol
+      if (/^\s*\d+(\.\d+)?\s*$/.test(formula)) {
+        return match;
+      }
+      return `\\(${formula}\\)`;
+    });
+    
+    // Process all image references in the markdown content
+    const imageMatches = [...combinedMarkdown.matchAll(/!\[(.*?)\]\((.*?)\)/g)];
+    for (const match of imageMatches) {
+      const imageAlt = match[1];
+      let imagePath = match[2];
+      
+      // Skip external URLs
+      if (imagePath.startsWith('http')) continue;
+      
+      // Try multiple path resolution strategies to find the image
+      const possiblePaths = [
+        // Strategy 1: Relative to parent directory of srcDir
+        path.resolve(path.dirname(srcDir), imagePath),
+        
+        // Strategy 2: Directly in srcDir
+        path.resolve(srcDir, path.basename(imagePath)),
+        
+        // Strategy 3: Looking in attachments folder inside srcDir
+        path.resolve(srcDir, 'attachments', path.basename(imagePath)),
+        
+        // Strategy 4: Looking in srcDir/attachments regardless of original path
+        path.resolve(srcDir, 'attachments', path.basename(imagePath).replace(/^.*[\\\/]/, '')),
+        
+        // Strategy 5: Looking in srcDir parent's attachments folder
+        path.resolve(path.dirname(srcDir), 'attachments', path.basename(imagePath)),
+      ];
+      
+      // Try each possible path until we find one that exists
+      let imageFound = false;
+      for (const testPath of possiblePaths) {
+        if (fs.existsSync(testPath)) {
+          imageFound = true;
+          debug(`Found image at: ${testPath}`);
+          break;
+        }
+      }
+      
+      if (!imageFound) {
+        console.warn(`Warning: Image not found: ${imagePath} (${imageAlt})`);
+      }
+    }
+    
+    // Process all links to markdown files within the same directory structure
+    // This ensures that links between markdown files in the same document 
+    // are converted to proper anchor links in the assembled HTML
+    let processedMarkdown = combinedMarkdown;
+    
+    // Build a map of files to section IDs for link transformation
+    
+    // Create a map of markdown filenames to their section IDs
+    const fileToSectionMap = new Map();
+    const fileNameRegex = /\d+_([\w-]+)\.md$/;
+    
+    // First pass: build a map of filenames to section IDs
+    for (let i = 0; i < markdownFiles.length; i++) {
+      const filePath = markdownFiles[i];
+      const fileName = path.basename(filePath);
+      const fileContent = fs.readFileSync(filePath, 'utf8');
+      
+      // Extract section ID from first heading or use filename
+      const headingMatch = fileContent.match(/^#\s+(.*?)$/m);
+      if (headingMatch) {
+        const headingText = headingMatch[1];
+        const sectionId = headingText.toLowerCase()
+          .replace(/[\s]+/g, '-')           // Replace spaces with hyphens
+          .replace(/[^\w\-]+/g, '')        // Remove non-word chars except hyphens
+          .replace(/--+/g, '-')            // Replace multiple hyphens with single
+          .replace(/^-+|-+$/g, '');       // Trim hyphens from start and end
+        
+        fileToSectionMap.set(fileName, sectionId);
+        debug(`Mapped file ${fileName} to section ID ${sectionId}`);
+      } else {
+        // If no heading found, use the filename without number prefix as fallback
+        const fileNameMatch = fileName.match(fileNameRegex);
+        let fallbackId = fileName.replace(/\.md$/, '');
+        if (fileNameMatch && fileNameMatch[1]) {
+          fallbackId = fileNameMatch[1];  // Use the part after number_ prefix
+        }
+        fallbackId = fallbackId.toLowerCase().replace(/[^\w\-]+/g, '-');
+        fileToSectionMap.set(fileName, fallbackId);
+        debug(`Mapped file ${fileName} to fallback ID ${fallbackId}`);
+      }
+    }
+    
+    // Process Markdown BEFORE converting to HTML to transform links
+    // This regex matches Markdown links: [text](link.md)
+    const markdownLinkRegex = /\[([^\]]+)\]\(([^\)]+\.md)\)/g;
+    
+    // Transform the markdown content to handle internal links
+    combinedMarkdown = combinedMarkdown.replace(markdownLinkRegex, (match, linkText, href) => {
+      // Get just the filename
+      const linkedFileName = path.basename(href);
+      
+      // Variable to store the section ID if we find a match
+      let targetSectionId = null;
+      
+      // Try direct match first using file base name without extension
+      const linkedFileBaseName = path.basename(linkedFileName, '.md');
+      if (fileToSectionMap.has(linkedFileBaseName)) {
+        targetSectionId = fileToSectionMap.get(linkedFileBaseName);
+        debug(`Direct match: ${linkedFileName} -> #${targetSectionId}`);
+      }
+      // Then try fuzzy match by ignoring numeric prefixes
+      else {
+        const baseNameMatch = linkedFileName.match(/^\d+_(.+)$/) || [null, linkedFileName];
+        const baseName = baseNameMatch[1];
+        
+        for (const [fileName, sectionId] of fileToSectionMap.entries()) {
+          const fileBaseMatch = fileName.match(/^\d+_(.+)$/) || [null, fileName];
+          const fileBase = fileBaseMatch[1];
+          
+          if (baseName === fileBase) {
+            targetSectionId = sectionId;
+            debug(`Fuzzy match: ${linkedFileName} -> #${targetSectionId}`);
+            break;
+          }
+        }
+      }
+      
+      // If we found a matching section, return the updated Markdown link
+      if (targetSectionId) {
+        return `[${linkText}](#${targetSectionId})`;
+      }
+      
+      // Otherwise return the original link unchanged
+      return match;
+    });
+    
+    // Remove the duplicate fileToSectionMap and use the chaptersInfo directly
+    // Map markdown files to section IDs and chapter structure
+    const chaptersInfo = [];
+    
+    // Build chapter structure information from markdown files
+    for (const file of markdownFiles) {
+      const fileName = path.basename(file, '.md');
+      const chapterId = fileName.replace(/^\d+_/, '');
+      const content = fs.readFileSync(file, 'utf8');
+      
+      // Extract headings from content (only H2 headings)
+      const headings = [...content.matchAll(/^(#{2})\s+(.+)$/gm)];
+      const sections = [];
+      
+      if (headings.length > 0) {
+        headings.forEach((match, index) => {
+          const title = match[2];
+          const headingId = title.toLowerCase()
+            .replace(/[^\w]+/g, '-')
+            .replace(/^-|-$/g, '');
+          
+          const excludedTitles = ['abstract', 'executive summary', 'introduction', 
+                                 'appendix', 'further reading', 'references'];
+          
+          if (!excludedTitles.includes(title.toLowerCase()) && 
+              title.toLowerCase() !== chapterId.toLowerCase()) {
+            sections.push({
+              id: `${chapterId}-${headingId}`,
+              title: title,
+              level: 2,
+              file: fileName
+            });
+          }
+        });
+        
+        // Add sections to chaptersInfo
+        chaptersInfo.push(...sections);
+      }
+      
+      // Update the existing fileToSectionMap
+      fileToSectionMap.set(fileName, chapterId);
+    }
+    
+    // Now convert the processed markdown to HTML
+    let htmlContent = marked.parse(combinedMarkdown);
+    
+    // Add file type indicators to code blocks with proper badges
+    const codeBlocksWithFileType = htmlContent.replace(
+      /<pre><code[^>]*>/g,
+      (match) => match.replace(/<pre>/, '<pre data-file-type="code">')
+    );
+    
+    // Extract file types from code blocks with comments and add language class for syntax highlighting
+    const codeBlocksWithComments = codeBlocksWithFileType.replace(
+      /<pre data-file-type="code"><code>([\s\S]*?)\n/g,
+      (match, codeContent) => {
+        const fileTypeMatch = codeContent.match(/^(?:\/\/|#|<!--) ?([a-zA-Z0-9-_.]+)\s/);
+        if (fileTypeMatch) {
+          const fileType = fileTypeMatch[1];
+          let langClass = '';
+          let langName = '';
+          
+          // Determine language class based on file extension or type
+          if (fileType.endsWith('.js') || fileType === 'javascript') {
+            langClass = ' class="language-javascript"';
+            langName = 'JavaScript';
+          } else if (fileType.endsWith('.py') || fileType === 'python') {
+            langClass = ' class="language-python"';
+            langName = 'Python';
+          } else if (fileType.endsWith('.sh') || fileType === 'bash' || fileType === 'shell') {
+            langClass = ' class="language-bash"';
+            langName = 'Shell';
+          } else if (fileType.endsWith('.yaml') || fileType.endsWith('.yml')) {
+            langClass = ' class="language-yaml"';
+            langName = 'YAML';
+          } else if (fileType.endsWith('.json')) {
+            langClass = ' class="language-json"';
+            langName = 'JSON';
+          } else if (fileType.endsWith('.html')) {
+            langClass = ' class="language-html"';
+            langName = 'HTML';
+          } else if (fileType.endsWith('.css')) {
+            langClass = ' class="language-css"';
+            langName = 'CSS';
+          } else if (fileType.endsWith('.md')) {
+            langClass = ' class="language-markdown"';
+            langName = 'Markdown';
+          } else {
+            langName = fileType;
+          }
+          
+          // Create code block with file type badge
+          return match.replace('<code>', `<code${langClass}>`)
+            .replace('data-file-type="code"', `data-file-type="${fileType}"`) + 
+            `<span class="file-type-badge">${langName}</span>`;
+        }
+        return match;
+      }
+    );
+    
+    // Process images with proper figure elements and accessible captions
+    const enhancedHtmlContent = codeBlocksWithComments.replace(
+      /<img src="([^"]+)" alt="([^"]+)">/g, 
+      '<figure class="image-container"><img src="$1" alt="$2"><figcaption>$2</figcaption></figure>'
+    );
+    
+    const tableAccessibilityContent = enhancedHtmlContent.replace(
+      /<table>/g,
+      '<table aria-hidden="true" role="presentation">'
+    );
+    
+    // Define processed content
+    // Process image URLs with imgix for proper sizing
+  const processedWithImageSizing = tableAccessibilityContent.replace(
+    /<img src="([^"]+imgix\.net[^"]+)"([^>]*)>/gi,
+    '<img src="$1" $2 width="1600">'  
+  );
+  
+  // Will be used for final content processing
+  let initialProcessedContent = processedWithImageSizing;
+    
+    const tocItems = [];
+    const headingMatches = [...combinedMarkdown.matchAll(/^(#{1,3})\s+(.*?)$/gm)];
+    for (const match of headingMatches) {
+      const level = match[1].length;
+      const text = match[2];
+      const id = text.toLowerCase().replace(/[^\w]+/g, '-');
+      tocItems.push({ level, text, id });
+    }
+    
+    // Generate initial TOC (will be possibly replaced later if <!-- TOC --> is found)
+    let tocHTML = '<div class="toc">\n<h2>Table of Contents</h2>\n<ul>\n';
+    for (const item of tocItems) {
+      const indent = '  '.repeat(item.level - 1);
+      tocHTML += `${indent}<li><a href="#${item.id}">${item.text}</a></li>\n`;
+    }
+    tocHTML += '</ul>\n</div>\n';
+    
+    // External files were loaded at the beginning of buildHtml
+  
+    // Convert Markdown to HTML and process it
+    let processedContent = marked(combinedMarkdown);
+    
+    // Add file type indicators to code blocks
+    processedContent = processedContent.replace(/<pre><code class="language-(\w+)">/g, (match, lang) => {
+      return `<pre data-file-type="${lang}"><code class="language-${lang}">`;
+    });
+    
+    // Extract file types from code blocks with comments and add language class for syntax highlighting
+    processedContent = processedContent.replace(/<pre><code>(```(\w+)[\s\S]*?```)<\/code><\/pre>/g, (match, content, lang) => {
+      return `<pre data-file-type="${lang}"><code class="language-${lang}">${content.replace(/```\w+\n|```$/g, '')}</code></pre>`;
+    });
+    
+    // Process generic code blocks without language specification
+    processedContent = processedContent.replace(/<pre><code>(?!<)/g, '<pre data-file-type="code"><code>');
+    
+    // Fix the image captions in content
+    processedContent = processedContent.replace(/<p><img src="([^"]+)"([^>]*)>\s*<\/p>\s*<p><em>([^<]+)<\/em><\/p>/g, (match, src, attrs, caption) => {
+      const altMatch = attrs.match(/alt="([^"]*)"/);  
+      const alt = altMatch ? altMatch[1] : '';
+      return `<figure><img src="${src}"${attrs}><figcaption>${caption}</figcaption><span class="visually-hidden">${alt}</span></figure>`;
+    });
+    
+    processedContent = processedContent.replace(/<table>/g, '<table aria-hidden="true" role="presentation">');
+
+    // If it's an imgix URL, add width parameter
+    processedContent = processedContent.replace(/src="(https:\/\/[^"]*imgix\.net\/[^"]+)(?:\?([^"]*))?"/g, (match, url, params) => {
+      if (params && params.includes('w=')) {
+        return match;
+      }
+      const separator = params ? '&' : '?';
+      return `src="${url}${params ? '?' + params : ''}${separator}w=1600"`;
+    });
+    
+    // Check if we need a custom TOC
+    if (combinedMarkdown.includes('<!-- TOC -->')) {
+      // Reset the TOC HTML
+      tocHTML = '<div class="toc">\n<h2>Table of Contents</h2>\n<ul>';
+      const headings = processedContent.match(/<h([2-3])\s+id="([^"]+)">([^<]+)<\/h\1>/g) || [];
+      for (const heading of headings) {
+        const levelMatch = heading.match(/<h([2-3])>/); 
+        const idMatch = heading.match(/id="([^"]+)"/); 
+        const textMatch = heading.match(/>([^<]+)<\/h/); 
+        if (levelMatch && idMatch && textMatch) {
+          const level = levelMatch[1];
+          const id = idMatch[1];
+          const text = textMatch[1];
+          const indent = level > 2 ? '  ' : '';
+          tocHTML += `\n${indent}<li><a href="#${id}">${text}</a></li>`;
+        }
+      }
+      tocHTML += '\n</ul>\n</div>\n';
+    }
+    
+    // Replace TOC placeholder
+    processedContent = processedContent.replace('<!-- TOC -->', tocHTML);
+    
+    // Process the HTML content to add chapter-aware section structure
+    let chapterAwareContent = processedContent;
+    let headingCounter = 0;
+    
+    // Create structured sections with proper data attributes for chapter identification
+    // This makes it easier for the annotation system to attach annotations to specific parts
+    chaptersInfo.forEach(chapter => {
+      const chapterHeadingRegex = new RegExp(
+        `<h1[^>]*>(${chapter.title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')})</h1>`,
+        'i'
+      );
+      
+      // Replace each main chapter heading with a properly structured section
+      // This adds data-chapter-id attributes used by the annotation system
+      if (chapterAwareContent.match(chapterHeadingRegex)) {
+        chapterAwareContent = chapterAwareContent.replace(
+          chapterHeadingRegex,
+          `<section id="${chapter.id}" class="content-section" data-chapter-id="${chapter.id}" data-file="${chapter.file}">
+            <h1 id="heading-${++headingCounter}">$1</h1>`
+        );
+        
+        // Close the section tag at an appropriate point
+        // Look for the next h1 or the end of the content
+        const nextH1Index = chapterAwareContent.indexOf('<h1', chapterAwareContent.indexOf(`<h1 id="heading-${headingCounter}">`) + 1);
+        
+        if (nextH1Index !== -1) {
+          // Insert closing section tag before the next h1
+          chapterAwareContent = chapterAwareContent.slice(0, nextH1Index) + '</section>\n' + chapterAwareContent.slice(nextH1Index);
+        } else {
+          // No more h1s, append closing section tag to the end
+          chapterAwareContent += '\n</section>';
+        }
+      }
+    });
+    
+    // Add data attributes to all heading elements for annotation targeting
+    let processedWithHeadingAttrs = chapterAwareContent.replace(
+      /<h([2-6])(?:[^>]*)>([^<]+)<\/h\1>/g,
+      (match, level, text) => {
+        const textContent = text.trim();
+        const headingId = chaptersInfo.find(ch => ch.title === textContent)?.id || `heading-${++headingCounter}`;
+        return `<h${level} id="${headingId}" data-heading="${textContent.replace(/"/g, '&quot;')}"><span>${textContent}</span></h${level}>`;
+      }
+    );
+    
+    // Add JSON data for chapter information in a hidden script tag
+    // This allows the annotation system to easily access the chapter structure
+    const chaptersJSON = JSON.stringify(chaptersInfo, null, 2);
+    processedWithHeadingAttrs += `\n<script type="application/json" id="document-chapters-data">${chaptersJSON}</script>\n`;
+    
+    // Prepare data for template
+    const templateData = {
+      title,
+      description,
+      author,
+      date,
+      version,
+      content: processedWithHeadingAttrs,
+      styles: cssStyles + '\n' + chapterNavStyles,
+      scripts: jsScripts,
+      chapters: chaptersInfo
+    };
+    
+    // Generate HTML using Handlebars template
+    const html = template(templateData);
+    
+    // Create output directory if it doesn't exist
+    const outputDir = path.dirname(outputFile);
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+    
+    // Write HTML to output file
+    fs.writeFileSync(outputFile, html);
+    
+    console.log(`HTML document generated successfully: ${outputFile}`);
+    return true;
+  } catch (error) {
+    console.error(`Error building HTML: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * Watches for changes in markdown files and rebuilds HTML
+ * @param {string} srcDir - Source directory containing markdown files
+ * @param {string} outputFile - Output HTML file path
+ */
+function watchMarkdown(srcDir, outputFile) {
+  console.log(`Watching for changes in ${srcDir}...`);
+  
+  // Build HTML initially
+  buildHtml(srcDir, outputFile);
+  
+  // Determine the pattern to watch based on whether srcDir is a file or directory
+  const resolvedSrcDir = path.resolve(srcDir);
+  const isDirectory = fs.statSync(resolvedSrcDir).isDirectory();
+  
+  // Set up the watcher with reliable configuration
+  const watcher = chokidar.watch(resolvedSrcDir, {
+    persistent: true,
+    ignoreInitial: true,
+    usePolling: true,         // More reliable but uses more CPU
+    interval: 1000,           // Poll every 1000ms = 1 second
+    awaitWriteFinish: {
+      stabilityThreshold: 2000, // Wait 2 seconds of stability before triggering
+      pollInterval: 500        // Poll every 500ms during stability wait
+    },
+    ignored: /(^|\/)\..|node_modules/, // Ignore dotfiles and node_modules
+    depth: isDirectory ? undefined : 0,
+    alwaysStat: false,
+    atomic: true               // Handle atomic writes reliably
+  });
+  
+  // Use debouncing to prevent multiple rebuilds for rapid changes
+  let debounceTimer;
+  const debouncedRebuild = () => {
+    clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(async () => {
+      console.log('\n⏳ Regenerating HTML document...');
+      try {
+        await buildHtml(srcDir, outputFile);
+        console.log(`✅ HTML document updated: ${outputFile}\n`);
+      } catch (error) {
+        console.error(`❌ Error rebuilding HTML: ${error.message}\n`);
+      }
+    }, 500); // 500ms debounce time
+  };
+  
+  // File change event handler
+  const handleChange = (filePath) => {
+    // Only process markdown files
+    if (isDirectory && !filePath.endsWith('.md')) {
+      return;
+    }
+    
+    console.log(`📄 File changed: ${path.relative(process.cwd(), filePath)}`);
+    debouncedRebuild();
+  };
+  
+  // Set up event handlers
+  watcher.on('change', handleChange);
+  watcher.on('add', (path) => {
+    if (path.endsWith('.md')) {
+      console.log(`📄 File added: ${path}`);
+      debouncedRebuild();
+    }
+  });
+  watcher.on('unlink', (path) => {
+    if (path.endsWith('.md')) {
+      console.log(`📄 File removed: ${path}`);
+      debouncedRebuild();
+    }
+  });
+  
+  // When ready, show a clear message
+  watcher.on('ready', () => {
+    console.log('👀 Watching for file changes. Press Ctrl+C to stop.\n');
+  });
+  
+  // Handle watch errors
+  watcher.on('error', (error) => {
+    console.error(`❌ Watch error: ${error}`);
+  });
+}
+
+// Watch for changes if enabled
+if (options.watch) {
+  watchMarkdown(srcPath, outputFile);
+} else {
+  buildHtml(srcPath, outputFile);
+}