@mgks/docmd 0.1.4 → 0.2.1

package/src/core/file-processor.js

@@ -1,461 +1,757 @@
-// src/core/file-processor.js
+// Source file from the docmd project — https://github.com/mgks/docmd
+
 const fs = require('fs-extra');
 const MarkdownIt = require('markdown-it');
 const matter = require('gray-matter');
 const hljs = require('highlight.js');
-const container = require('markdown-it-container');
 const attrs = require('markdown-it-attrs');
-const path = require('path'); // Add path module for findMarkdownFiles
+const path = require('path');
+const markdown_it_footnote = require('markdown-it-footnote');
+const markdown_it_task_lists = require('markdown-it-task-lists');
+const markdown_it_abbr = require('markdown-it-abbr');
+const markdown_it_deflist = require('markdown-it-deflist');
 
-// Function to format paths for display (relative to CWD)
+/**
+ * Formats an absolute path to be relative to the current working directory for cleaner logging.
+ */
 function formatPathForDisplay(absolutePath) {
   const CWD = process.cwd();
   const relativePath = path.relative(CWD, absolutePath);
-  
-  // If it's not a subdirectory, prefix with ./ for clarity
   if (!relativePath.startsWith('..') && !path.isAbsolute(relativePath)) {
     return `./${relativePath}`;
   }
-  
-  // Return the relative path
   return relativePath;
 }
 
-const md = new MarkdownIt({
-  html: true,
-  linkify: true,
-  typographer: true,
-  highlight: function (str, lang) {
-    if (lang && hljs.getLanguage(lang)) {
-      try {
-        return '<pre class="hljs"><code>' +
-               hljs.highlight(str, { language: lang, ignoreIllegals: true }).value +
-               '</code></pre>';
-      } catch (e) {
-        console.error(`Error highlighting language ${lang}:`, e);
+function createMarkdownItInstance(config) {
+  const mdOptions = {
+    html: true,
+    linkify: true,
+    typographer: true,
+    breaks: true,
+  };
+   
+  // Conditionally enable highlighting
+  if (config.theme?.codeHighlight !== false) {
+    mdOptions.highlight = function (str, lang) {
+      if (lang && hljs.getLanguage(lang)) {
+        try {
+          return `<pre class="hljs"><code>${hljs.highlight(str, { language: lang, ignoreIllegals: true }).value}</code></pre>`;
+        } catch (e) { console.error(`Highlighting error for lang ${lang}:`, e); }
+      }
+      return `<pre class="hljs"><code>${new MarkdownIt().utils.escapeHtml(str)}</code></pre>`;
+    };
+  }
+
+  const md = new MarkdownIt(mdOptions);
+
+  // --- Attach all plugins and rules to this instance ---
+  md.use(attrs, { leftDelimiter: '{', rightDelimiter: '}' });
+  md.use(markdown_it_footnote);
+  md.use(markdown_it_task_lists);
+  md.use(markdown_it_abbr);
+  md.use(markdown_it_deflist);
+
+  // Register renderers for all containers
+  Object.keys(containers).forEach(containerName => {
+    const container = containers[containerName];
+    md.renderer.rules[`container_${containerName}_open`] = container.render;
+    md.renderer.rules[`container_${containerName}_close`] = container.render;
+  });
+
+  // Register the enhanced rules
+  md.block.ruler.before('fence', 'steps_container', stepsContainerRule, {
+    alt: ['paragraph', 'reference', 'blockquote', 'list']
+  });
+  md.block.ruler.before('fence', 'enhanced_tabs', enhancedTabsRule, {
+    alt: ['paragraph', 'reference', 'blockquote', 'list']
+  });
+  md.block.ruler.before('paragraph', 'advanced_container', advancedContainerRule, {
+    alt: ['paragraph', 'reference', 'blockquote', 'list']
+  });
+
+  // Register all custom renderers
+  md.renderer.rules.ordered_list_open = customOrderedListOpenRenderer;
+  md.renderer.rules.list_item_open = customListItemOpenRenderer;
+  md.renderer.rules.image = customImageRenderer;
+  
+  // Register tabs renderers
+  md.renderer.rules.tabs_open = tabsOpenRenderer;
+  md.renderer.rules.tabs_nav_open = tabsNavOpenRenderer;
+  md.renderer.rules.tabs_nav_close = tabsNavCloseRenderer;
+  md.renderer.rules.tabs_nav_item = tabsNavItemRenderer;
+  md.renderer.rules.tabs_content_open = tabsContentOpenRenderer;
+  md.renderer.rules.tabs_content_close = tabsContentCloseRenderer;
+  md.renderer.rules.tab_pane_open = tabPaneOpenRenderer;
+  md.renderer.rules.tab_pane_close = tabPaneCloseRenderer;
+  md.renderer.rules.tabs_close = tabsCloseRenderer;
+  
+  // Register heading ID plugin
+  md.use(headingIdPlugin);
+  
+  // Register standalone closing rule
+  md.block.ruler.before('paragraph', 'standalone_closing', standaloneClosingRule, {
+    alt: ['paragraph', 'reference', 'blockquote', 'list']
+  });
+
+  return md;
+}
+
+// ===================================================================
+// --- ADVANCED NESTED CONTAINER SYSTEM ---
+// ===================================================================
+
+// Container definitions
+// To add a new container type:
+// 1. Add it to this containers object
+// 2. Define the render function for opening (nesting === 1) and closing (nesting === -1)
+// 3. The system will automatically register it and support nesting
+const containers = {
+  card: {
+    name: 'card',
+    render: (tokens, idx) => {
+      if (tokens[idx].nesting === 1) {
+        const title = tokens[idx].info ? tokens[idx].info.trim() : '';
+        return `<div class="docmd-container card">${title ? `<div class="card-title">${title}</div>` : ''}<div class="card-content">`;
+      }
+      return '</div></div>';
+    }
+  },
+  callout: {
+    name: 'callout',
+    render: (tokens, idx) => {
+      if (tokens[idx].nesting === 1) {
+        const [type, ...titleParts] = tokens[idx].info.split(' ');
+        const title = titleParts.join(' ');
+        return `<div class="docmd-container callout callout-${type}">${title ? `<div class="callout-title">${title}</div>` : ''}<div class="callout-content">`;
+      }
+      return '</div></div>';
+    }
+  },
+  button: {
+    name: 'button',
+    selfClosing: true, // Mark as self-closing
+    render: (tokens, idx) => {
+      if (tokens[idx].nesting === 1) {
+        const parts = tokens[idx].info.split(' ');
+        const text = parts[0];
+        const url = parts[1];
+        const color = parts[2];
+        const colorStyle = color && color.startsWith('color:') ? ` style="background-color: ${color.split(':')[1]}"` : '';
+        
+        // Check if URL starts with 'external:' for new tab behavior
+        let finalUrl = url;
+        let targetAttr = '';
+        if (url && url.startsWith('external:')) {
+          finalUrl = url.substring(9); // Remove 'external:' prefix
+          targetAttr = ' target="_blank" rel="noopener noreferrer"';
+        }
+        
+        return `<a href="${finalUrl}" class="docmd-button"${colorStyle}${targetAttr}>${text.replace(/_/g, ' ')}</a>`;
       }
+      return '';
+    }
+  },
+  steps: {
+    name: 'steps',
+    render: (tokens, idx) => {
+      if (tokens[idx].nesting === 1) {
+        // Add a unique class for steps containers to enable CSS-based numbering reset
+        // The steps-numbering class will style only direct ol > li children as numbered steps
+        return '<div class="docmd-container steps steps-reset steps-numbering">';
+      }
+      return '</div>';
     }
-    return '<pre class="hljs"><code>' + md.utils.escapeHtml(str) + '</code></pre>';
   }
-});
-
-// Add markdown-it-attrs for image styling and other element attributes
-// This allows for {.class} syntax after elements
-md.use(attrs, {
-  // Allow attributes on images and other elements
-  leftDelimiter: '{',
-  rightDelimiter: '}',
-  allowedAttributes: ['class', 'id', 'width', 'height', 'style']
-});
-
-// Custom image renderer to ensure attributes are properly applied
-const defaultImageRenderer = md.renderer.rules.image;
-md.renderer.rules.image = function(tokens, idx, options, env, self) {
-  // Get the rendered HTML from the default renderer
-  const renderedImage = defaultImageRenderer(tokens, idx, options, env, self);
+  // Future containers can be added here:
+  // timeline: {
+  //   name: 'timeline',
+  //   render: (tokens, idx) => {
+  //     if (tokens[idx].nesting === 1) {
+  //       return '<div class="docmd-container timeline">';
+  //     }
+  //     return '</div>';
+  //   }
+  // },
+  // changelog: {
+  //   name: 'changelog',
+  //   render: (tokens, idx) => {
+  //     if (tokens[idx].nesting === 1) {
+  //       return '<div class="docmd-container changelog">';
+  //     }
+  //     return '</div>';
+  //   }
+  // }
+};
+
+
+
+// Advanced container rule with proper nesting support
+function advancedContainerRule(state, startLine, endLine, silent) {
+  const start = state.bMarks[startLine] + state.tShift[startLine];
+  const max = state.eMarks[startLine];
+  const lineContent = state.src.slice(start, max).trim();
   
-  // Check if the next token is an attrs_block
-  const nextToken = tokens[idx + 1];
-  if (nextToken && nextToken.type === 'attrs_block') {
-    // Extract attributes from the attrs_block token
-    const attrs = nextToken.attrs || [];
+  // Check if this is a container opening
+  const containerMatch = lineContent.match(/^:::\s*(\w+)(?:\s+(.+))?$/);
+  if (!containerMatch) return false;
+  
+  const [, containerName, params] = containerMatch;
+  const container = containers[containerName];
+  
+  if (!container) return false;
+  
+  if (silent) return true;
+  
+  // Handle self-closing containers (like buttons)
+  if (container.selfClosing) {
+    const openToken = state.push(`container_${containerName}_open`, 'div', 1);
+    openToken.info = params || '';
+    const closeToken = state.push(`container_${containerName}_close`, 'div', -1);
+    state.line = startLine + 1;
+    return true;
+  }
+  
+  // Find the closing tag with proper nesting handling
+  let nextLine = startLine;
+  let found = false;
+  let depth = 1;
+  
+  while (nextLine < endLine) {
+    nextLine++;
+    const nextStart = state.bMarks[nextLine] + state.tShift[nextLine];
+    const nextMax = state.eMarks[nextLine];
+    const nextContent = state.src.slice(nextStart, nextMax).trim();
     
-    // Build the attributes string
-    const attrsStr = attrs.map(([name, value]) => {
-      if (name === 'class') {
-        return `class="${value}"`;
-      } else if (name.startsWith('data-')) {
-        return `${name}="${value}"`;
-      } else {
-        return `${name}="${value}"`;
+    // Check for opening tags (any container)
+    if (nextContent.startsWith(':::')) {
+      const containerMatch = nextContent.match(/^:::\s*(\w+)/);
+      if (containerMatch && containerMatch[1] !== containerName) {
+        // Only increment depth for non-self-closing containers
+        const innerContainer = containers[containerMatch[1]];
+        if (innerContainer && innerContainer.render && !innerContainer.selfClosing) {
+          depth++;
+        }
+        continue;
       }
-    }).join(' ');
+    }
     
-    // Insert attributes into the image tag
-    return renderedImage.replace('<img ', `<img ${attrsStr} `);
+    // Check for closing tags
+    if (nextContent === ':::') {
+      depth--;
+      if (depth === 0) {
+        found = true;
+        break;
+      }
+    }
   }
   
-  return renderedImage;
-};
+  if (!found) return false;
+  
+  // Create tokens
+  const openToken = state.push(`container_${containerName}_open`, 'div', 1);
+  openToken.info = params || '';
+  
+  // Process content recursively
+  const oldParentType = state.parentType;
+  const oldLineMax = state.lineMax;
+  
+  state.parentType = 'container';
+  state.lineMax = nextLine;
+  
+  // Process the content inside the container
+  state.md.block.tokenize(state, startLine + 1, nextLine);
+  
+  const closeToken = state.push(`container_${containerName}_close`, 'div', -1);
+  
+  state.parentType = oldParentType;
+  state.lineMax = oldLineMax;
+  state.line = nextLine + 1;
+  
+  return true;
+}
 
-// Add anchors to headings for TOC linking
-md.use((md) => {
-  // Original renderer
-  const defaultRender = md.renderer.rules.heading_open || function(tokens, idx, options, env, self) {
-    return self.renderToken(tokens, idx, options);
-  };
+// --- Simple Steps Container Rule ---
+function stepsContainerRule(state, startLine, endLine, silent) {
+  const start = state.bMarks[startLine] + state.tShift[startLine];
+  const max = state.eMarks[startLine];
+  const lineContent = state.src.slice(start, max).trim();
+  if (lineContent !== '::: steps') return false;
+  if (silent) return true;
 
-  md.renderer.rules.heading_open = function(tokens, idx, options, env, self) {
-    const token = tokens[idx];
-    // Get the heading level (h1, h2, etc.)
-    const level = token.tag.substring(1);
+  // Find the closing ':::' for the steps container
+  let nextLine = startLine;
+  let found = false;
+  let depth = 1;
+  
+  while (nextLine < endLine) {
+    nextLine++;
+    const nextStart = state.bMarks[nextLine] + state.tShift[nextLine];
+    const nextMax = state.eMarks[nextLine];
+    const nextContent = state.src.slice(nextStart, nextMax).trim();
     
-    // Find the heading text from the next inline token
-    const contentToken = tokens[idx + 1];
-    if (contentToken && contentToken.type === 'inline') {
-      const headingText = contentToken.content;
-      
-      // Generate an ID from the heading text
-      // Simple slugify: lowercase, replace spaces and special chars with dashes
-      const id = headingText
-        .toLowerCase()
-        .replace(/\s+/g, '-')
-        .replace(/[^\w-]/g, '')
-        .replace(/--+/g, '-')
-        .replace(/^-+|-+$/g, '');
-      
-      // Add the id attribute
-      if (id) {
-        token.attrSet('id', id);
+    // Skip tab markers as they don't affect container depth
+    if (nextContent.startsWith('== tab')) {
+      continue;
+    }
+    
+    // Check for opening tags (any container)
+    if (nextContent.startsWith(':::')) {
+      const containerMatch = nextContent.match(/^:::\s*(\w+)/);
+      if (containerMatch) {
+        const containerName = containerMatch[1];
+        // Only count non-self-closing containers for depth
+        const innerContainer = containers[containerName];
+        if (innerContainer && !innerContainer.selfClosing) {
+          depth++;
+        }
+        continue;
       }
     }
     
-    // Call the original renderer
-    return defaultRender(tokens, idx, options, env, self);
-  };
-});
-
-// Custom Containers
-md.use(container, 'callout', {
-  validate: function(params) {
-    // Allows optional title for callout: ::: callout type [Optional Title Text]
-    return params.trim().match(/^callout\s+(info|warning|tip|danger|success)(\s+.*)?$/);
-  },
-  render: function (tokens, idx) {
-    const token = tokens[idx];
-    const match = token.info.trim().match(/^callout\s+(info|warning|tip|danger|success)(\s+(.*))?$/);
-
-    if (token.nesting === 1) {
-      const type = match[1];
-      const title = match[3] ? md.renderInline(match[3]) : ''; // Render title as markdown
-      let titleHtml = '';
-      if (title) {
-        titleHtml = `<div class="callout-title">${title}</div>`;
+    // Check for closing tags
+    if (nextContent === ':::') {
+      depth--;
+      if (depth === 0) {
+        found = true;
+        break;
       }
-      return `<div class="docmd-container callout callout-${type}">\n${titleHtml}<div class="callout-content">\n`;
-    } else {
-      return '</div></div>\n';
     }
   }
-});
+  
+  if (!found) return false;
 
-md.use(container, 'card', {
-  validate: function(params) {
-    // Allows optional title for card: ::: card [Optional Title Text]
-    return params.trim().match(/^card(\s+.*)?$/);
-  },
-  render: function (tokens, idx) {
-    const token = tokens[idx];
-    const titleText = token.info.trim().substring('card'.length).trim();
+  // Create tokens for steps container
+  const openToken = state.push('container_steps_open', 'div', 1);
+  openToken.info = '';
+  
+  // Process content normally but disable automatic list processing
+  const oldParentType = state.parentType;
+  const oldLineMax = state.lineMax;
+  
+  state.parentType = 'container';
+  state.lineMax = nextLine;
+  
+  // Process the content inside the container
+  state.md.block.tokenize(state, startLine + 1, nextLine);
+  
+  const closeToken = state.push('container_steps_close', 'div', -1);
+  
+  state.parentType = oldParentType;
+  state.lineMax = oldLineMax;
+  state.line = nextLine + 1;
+  
+  return true;
+}
+
+// --- Enhanced tabs rule with nested content support ---
+function enhancedTabsRule(state, startLine, endLine, silent) {
+  const start = state.bMarks[startLine] + state.tShift[startLine];
+  const max = state.eMarks[startLine];
+  const lineContent = state.src.slice(start, max).trim();
 
-    if (token.nesting === 1) {
-      let titleHtml = '';
-      if (titleText) {
-        titleHtml = `<div class="card-title">${md.renderInline(titleText)}</div>\n`;
+  if (lineContent !== '::: tabs') return false;
+  if (silent) return true;
+
+  // Find the closing tag with proper nesting handling
+  let nextLine = startLine;
+  let found = false;
+  let depth = 1;
+  while (nextLine < endLine) {
+    nextLine++;
+    const nextStart = state.bMarks[nextLine] + state.tShift[nextLine];
+    const nextMax = state.eMarks[nextLine];
+    const nextContent = state.src.slice(nextStart, nextMax).trim();
+    
+    // Check for opening tags (any container)
+    if (nextContent.startsWith(':::')) {
+      const containerMatch = nextContent.match(/^:::\s*(\w+)/);
+      if (containerMatch && containerMatch[1] !== 'tabs') {
+        // Don't increment depth for steps - they have their own depth counting
+        if (containerMatch[1] === 'steps') {
+          continue;
+        }
+        // Only increment depth for non-self-closing containers
+        const innerContainer = containers[containerMatch[1]];
+        if (innerContainer && !innerContainer.selfClosing) {
+          depth++;
+        }
+        continue;
+      }
+    }
+    
+    // Check for closing tags
+    if (nextContent === ':::') {
+      depth--;
+      if (depth === 0) {
+        found = true;
+        break;
       }
-      return `<div class="docmd-container card">\n${titleHtml}<div class="card-content">\n`;
-    } else {
-      return '</div></div>\n';
     }
   }
-});
-
-// Steps container: Uses CSS counters for H4 or P > STRONG elements within it.
-// Markdown syntax:
-// ::: steps
-// > 1. **First Step Title:**
-// > Content for step 1
-//
-// > 2. **Second Step Title:**
-// > More content
-// :::
-md.use(container, 'steps', {
-  render: function (tokens, idx) {
-    if (tokens[idx].nesting === 1) {
-      // style="counter-reset: step-counter;" is added for CSS counters
-      return '<div class="docmd-container steps" style="counter-reset: step-counter;">\n';
-    } else {
-      return '</div>\n';
+  if (!found) return false;
+
+  // Get the raw content by manually extracting lines
+  let content = '';
+  for (let i = startLine + 1; i < nextLine; i++) {
+    const lineStart = state.bMarks[i] + state.tShift[i];
+    const lineEnd = state.eMarks[i];
+    content += state.src.slice(lineStart, lineEnd) + '\n';
+  }
+
+  // Parse tabs manually
+  const lines = content.split('\n');
+  const tabs = [];
+  let currentTab = null;
+  let currentContent = [];
+  
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    const tabMatch = line.match(/^==\s*tab\s+(?:"([^"]+)"|(\S+))$/);
+    
+    if (tabMatch) {
+      // Save previous tab if exists
+      if (currentTab) {
+        currentTab.content = currentContent.join('\n').trim();
+        tabs.push(currentTab);
+      }
+      // Start new tab
+      const title = tabMatch[1] || tabMatch[2];
+      currentTab = { title: title, content: '' };
+      currentContent = [];
+    } else if (currentTab) {
+      // Add line to current tab content (only if not empty and not a tab marker)
+      if (lines[i].trim() && !lines[i].trim().startsWith('==')) {
+        currentContent.push(lines[i]);
+      }
     }
   }
-});
-
-// Post-process step markers for blockquote-based steps
-function processStepsContent(html) {
-  // Clean up any malformed containers
-  html = html.replace(/<blockquote>\s*<p>::: /g, '<p>');
-  
-  // Find all steps containers and process their blockquotes as steps
-  return html.replace(
-    /<div class="docmd-container steps"[^>]*>([\s\S]*?)<\/div>/g,
-    function(match, stepsContent) {
-      // Process blockquotes within steps container
-      const processedContent = stepsContent
-        // Handle numbered steps - improved pattern to better capture the number and title
-        .replace(
-          /<blockquote>\s*<[^>]*>\s*(\d+|[*])(?:\.)?(?:\s*)(?:<strong>)?([^<]*)(?:<\/strong>)?(?::)?(?:\s*)([\s\S]*?)(?=<\/blockquote>)/g,
-          function(blockquote, stepNumber, stepTitle, stepContent) {
-            // Ensure there's always content in the step title
-            const title = stepTitle.trim() || `Step ${stepNumber}`;
-            
-            // Preserve paragraph breaks in the content
-            const formattedContent = stepContent
-              .replace(/<p>([\s\S]*?)<\/p>/g, '</div><p>$1</p><div class="step-content">') // Convert paragraphs
-              .replace(/<pre([\s\S]*?)<\/pre>/g, '</div><pre$1</pre><div class="step-content">'); // Preserve code blocks
-            
-            return `<div class="step"><h4>${stepNumber}. <strong>${title}</strong></h4><div class="step-content">${formattedContent}</div></div>`;
-          }
-        )
-        // Handle unnumbered steps - like "**Title:**"
-        .replace(
-          /<blockquote>\s*<p><strong>([^<:]*?):<\/strong>([\s\S]*?)(?=<\/blockquote>)/g,
-          function(blockquote, stepTitle, stepContent) {
-            // Preserve paragraph breaks in the content
-            const formattedContent = stepContent
-              .replace(/<p>([\s\S]*?)<\/p>/g, '</div><p>$1</p><div class="step-content">') // Convert paragraphs
-              .replace(/<pre([\s\S]*?)<\/pre>/g, '</div><pre$1</pre><div class="step-content">'); // Preserve code blocks
-            
-            return `<div class="step"><h4><strong>${stepTitle}</strong></h4><div class="step-content">${formattedContent}</div></div>`;
-          }
-        )
-        // Handle any remaining blockquotes as generic steps
-        .replace(
-          /<blockquote>([\s\S]*?)<\/blockquote>/g,
-          function(blockquote, content) {
-            return `<div class="step">${content}</div>`;
+  
+  // Save the last tab
+  if (currentTab) {
+    currentTab.content = currentContent.join('\n').trim();
+    tabs.push(currentTab);
+  }
+
+  // Create tabs structure
+  const openToken = state.push('tabs_open', 'div', 1);
+  openToken.attrs = [['class', 'docmd-tabs']];
+  
+  // Create navigation
+  const navToken = state.push('tabs_nav_open', 'div', 1);
+  navToken.attrs = [['class', 'docmd-tabs-nav']];
+  tabs.forEach((tab, index) => {
+    const navItemToken = state.push('tabs_nav_item', 'div', 0);
+    navItemToken.attrs = [['class', `docmd-tabs-nav-item ${index === 0 ? 'active' : ''}`]];
+    navItemToken.content = tab.title;
+  });
+  state.push('tabs_nav_close', 'div', -1);
+  
+  // Create content
+  const contentToken = state.push('tabs_content_open', 'div', 1);
+  contentToken.attrs = [['class', 'docmd-tabs-content']];
+  tabs.forEach((tab, index) => {
+    const paneToken = state.push('tab_pane_open', 'div', 1);
+    paneToken.attrs = [['class', `docmd-tab-pane ${index === 0 ? 'active' : ''}`]];
+    
+    // Process tab content with the main markdown-it instance
+    if (tab.content.trim()) {
+      const tabContent = tab.content.trim();
+      
+      // Create a separate markdown-it instance for tab content to avoid double processing
+      const tabMd = new MarkdownIt({
+        html: true,
+        linkify: true,
+        typographer: true,
+        breaks: true,
+        highlight: function (str, lang) {
+          if (lang && hljs.getLanguage(lang)) {
+            try {
+              return '<pre class="hljs"><code>' +
+                     hljs.highlight(str, { language: lang, ignoreIllegals: true }).value +
+                     '</code></pre>';
+            } catch (e) { console.error(`Error highlighting language ${lang}:`, e); }
           }
-        );
+          return '<pre class="hljs"><code>' + MarkdownIt.utils.escapeHtml(str) + '</code></pre>';
+        }
+      });
       
-      // Fix any empty step-content divs or doubled divs
-      let fixedContent = processedContent
-        .replace(/<div class="step-content"><\/div><div class="step-content">/g, '<div class="step-content">')
-        .replace(/<div class="step-content"><\/div>/g, '');
+      // Register the same plugins for the tab markdown instance
+      tabMd.use(attrs, { leftDelimiter: '{', rightDelimiter: '}' });
+      tabMd.use(markdown_it_footnote);
+      tabMd.use(markdown_it_task_lists);
+      tabMd.use(markdown_it_abbr);
+      tabMd.use(markdown_it_deflist);
       
-      return `<div class="docmd-container steps" style="counter-reset: step-counter;">${fixedContent}</div>`;
-    }
-  );
-}
-
-// Pre-process step markers in Markdown content
-// to ensure they'll be processed correctly by the markdown renderer
-function preprocessStepMarkers(content) {
-  // Find content between ::: steps and ::: markers
-  return content.replace(
-    /:::\s*steps\s*\n([\s\S]*?):::/g,
-    function(match, stepsContent) {
-      // Replace the step markers with a format that will survive markdown parsing
-      const processedSteps = stepsContent.replace(
-        /^::\s*((?:\d+|\*)?\.?\s*)(.*)$/gm,
-        function(stepMatch, stepNumber, stepContent) {
-          // Format it as a heading that we can target later
-          return `### STEP_MARKER ${stepNumber}${stepContent}`;
-        }
-      );
+      // Register container renderers for the tab markdown instance
+      Object.keys(containers).forEach(containerName => {
+        const container = containers[containerName];
+        tabMd.renderer.rules[`container_${containerName}_open`] = container.render;
+        tabMd.renderer.rules[`container_${containerName}_close`] = container.render;
+      });
+      
+      // Register the enhanced rules for the tab markdown instance
+      tabMd.block.ruler.before('fence', 'enhanced_tabs', enhancedTabsRule, {
+        alt: ['paragraph', 'reference', 'blockquote', 'list']
+      });
+      tabMd.block.ruler.before('paragraph', 'steps_container', stepsContainerRule, {
+        alt: ['paragraph', 'reference', 'blockquote', 'list']
+      });
+      tabMd.block.ruler.before('paragraph', 'advanced_container', advancedContainerRule, {
+        alt: ['paragraph', 'reference', 'blockquote', 'list']
+      });
+      
+      // Register custom renderers for the tab markdown instance
+      tabMd.renderer.rules.ordered_list_open = customOrderedListOpenRenderer;
+      tabMd.renderer.rules.list_item_open = customListItemOpenRenderer;
+      tabMd.renderer.rules.image = customImageRenderer;
       
-      return `::: steps\n${processedSteps}:::`;
+      // Register tabs renderers for the tab markdown instance
+      tabMd.renderer.rules.tabs_open = tabsOpenRenderer;
+      tabMd.renderer.rules.tabs_nav_open = tabsNavOpenRenderer;
+      tabMd.renderer.rules.tabs_nav_close = tabsNavCloseRenderer;
+      tabMd.renderer.rules.tabs_nav_item = tabsNavItemRenderer;
+      tabMd.renderer.rules.tabs_content_open = tabsContentOpenRenderer;
+      tabMd.renderer.rules.tabs_content_close = tabsContentCloseRenderer;
+      tabMd.renderer.rules.tab_pane_open = tabPaneOpenRenderer;
+      tabMd.renderer.rules.tab_pane_close = tabPaneCloseRenderer;
+      tabMd.renderer.rules.tabs_close = tabsCloseRenderer;
+      
+      // Register heading ID plugin for the tab markdown instance
+      tabMd.use(headingIdPlugin);
+      
+      // Register standalone closing rule for the tab markdown instance
+      tabMd.block.ruler.before('paragraph', 'standalone_closing', standaloneClosingRule, {
+        alt: ['paragraph', 'reference', 'blockquote', 'list']
+      });
+      
+      // Render the tab content
+      const renderedContent = tabMd.render(tabContent);
+      const htmlToken = state.push('html_block', '', 0);
+      htmlToken.content = renderedContent;
     }
-  );
+    
+    state.push('tab_pane_close', 'div', -1);
+  });
+  state.push('tabs_content_close', 'div', -1);
+  state.push('tabs_close', 'div', -1);
+  state.line = nextLine + 1;
+  return true;
 }
 
-// Post-process step markers back to the expected format
-function postprocessStepMarkers(html) {
-  return html.replace(
-    /<h3>STEP_MARKER\s*((?:\d+|\*)?\.?\s*)(.*?)<\/h3>/g,
-    function(match, stepNumber, stepContent) {
-      return `<h4>${stepNumber}${stepContent}</h4>`;
-    }
-  );
-}
+// Add a rule to handle standalone closing tags
+const standaloneClosingRule = (state, startLine, endLine, silent) => {
+  const start = state.bMarks[startLine] + state.tShift[startLine];
+  const max = state.eMarks[startLine];
+  const lineContent = state.src.slice(start, max).trim();
+  
+  if (lineContent === ':::') {
+    if (silent) return true;
+    // Skip this line by not creating any tokens
+    state.line = startLine + 1;
+    return true;
+  }
+  
+  return false;
+};
 
-// Escape container syntax in code blocks
-function escapeContainerSyntax(content) {
-  // Find all fenced code blocks and escape container markers within them
-  return content.replace(
-    /```(.*?)\n([\s\S]*?)```/g,
-    function(match, language, codeContent) {
-      // Don't modify code blocks that already contain escaped markers
-      if (codeContent.includes("\\:::") || codeContent.includes("\\::")) {
-        return match;
-      }
-      
-      // Escape ::: and :: markers within code blocks, but use a special marker
-      // that won't render a backslash in the final output
-      const escapedContent = codeContent
-        .replace(/:::/g, "___DOCMD_CONTAINER_ESCAPED___:::")
-        .replace(/^::/gm, "___DOCMD_CONTAINER_ESCAPED___::");
-        
-      return "```" + language + "\n" + escapedContent + "```";
+// Custom renderer for ordered lists in steps containers
+const customOrderedListOpenRenderer = function(tokens, idx, options, env, self) {
+  const token = tokens[idx];
+  // Check if we're inside a steps container by looking at the context
+  let isInSteps = false;
+  
+  // Look back through tokens to see if we're in a steps container
+  for (let i = idx - 1; i >= 0; i--) {
+    if (tokens[i].type === 'container_steps_open') {
+      isInSteps = true;
+      break;
     }
-  );
-}
-
-// Fix container syntax issues in Markdown content
-function normalizeContainerSyntax(content) {
-  // 1. Ensure container opening markers are at the beginning of lines, not inline
-  let fixed = content.replace(/([^\n])(:::)/g, '$1\n$2');
+    if (tokens[i].type === 'container_steps_close') {
+      break;
+    }
+  }
   
-  // 2. Ensure container closing markers are at the beginning of lines and have proper newlines
-  fixed = fixed.replace(/(:::)([^\n])/g, '$1\n$2');
+  if (isInSteps) {
+    const start = token.attrGet('start');
+    return start ? 
+      `<ol class="steps-list" start="${start}">` : 
+      '<ol class="steps-list">';
+  }
   
-  // 3. Fix extra spaces after container marker
-  fixed = fixed.replace(/:::\s+(\w+)/g, '::: $1');
+  // Default behavior for non-steps ordered lists
+  const start = token.attrGet('start');
+  return start ? `<ol start="${start}">` : '<ol>';
+};
+
+// Custom renderer for list items in steps containers
+const customListItemOpenRenderer = function(tokens, idx, options, env, self) {
+  const token = tokens[idx];
+  // Check if we're inside a steps container and this is a direct child
+  let isInStepsList = false;
   
-  // 4. Fix container markers that have newlines within them
-  fixed = fixed.replace(/:::\n(\w+)/g, '::: $1');
+  // Look back through tokens to see if we're in a steps list
+  for (let i = idx - 1; i >= 0; i--) {
+    if (tokens[i].type === 'ordered_list_open' && 
+        tokens[i].markup && 
+        tokens[i].level < token.level) {
+      // Check if this ordered list has steps-list class (meaning it's in steps container)
+      let j = i - 1;
+      while (j >= 0) {
+        if (tokens[j].type === 'container_steps_open') {
+          isInStepsList = true;
+          break;
+        }
+        if (tokens[j].type === 'container_steps_close') {
+          break;
+        }
+        j--;
+      }
+      break;
+    }
+  }
   
-  // 5. Fix missing spaces between ::: and container type
-  fixed = fixed.replace(/:::(\w+)/g, '::: $1');
+  if (isInStepsList) {
+    return '<li class="step-item">';
+  }
   
-  return fixed;
+  // Default behavior for non-step list items
+  return '<li>';
+};
+
+// Enhanced tabs renderers
+const tabsOpenRenderer = (tokens, idx) => {
+  const token = tokens[idx];
+  return `<div class="${token.attrs.map(attr => attr[1]).join(' ')}">`;
+};
+
+const tabsNavOpenRenderer = () => '<div class="docmd-tabs-nav">';
+const tabsNavCloseRenderer = () => '</div>';
+
+const tabsNavItemRenderer = (tokens, idx) => {
+  const token = tokens[idx];
+  return `<div class="${token.attrs[0][1]}">${token.content}</div>`;
+};
+
+const tabsContentOpenRenderer = () => '<div class="docmd-tabs-content">';
+const tabsContentCloseRenderer = () => '</div>';
+
+const tabPaneOpenRenderer = (tokens, idx) => {
+  const token = tokens[idx];
+  return `<div class="${token.attrs[0][1]}">`;
+};
+
+const tabPaneCloseRenderer = () => '</div>';
+
+const tabsCloseRenderer = () => '</div>';
+
+// Override the default image renderer to properly handle attributes like {.class}.
+const customImageRenderer = function(tokens, idx, options, env, self) {
+  const defaultImageRenderer = function(tokens, idx, options, env, self) { return self.renderToken(tokens, idx, options); };
+  const renderedImage = defaultImageRenderer(tokens, idx, options, env, self);
+  const nextToken = tokens[idx + 1];
+  if (nextToken && nextToken.type === 'attrs_block') {
+    const attrs = nextToken.attrs || [];
+    const attrsStr = attrs.map(([name, value]) => `${name}="${value}"`).join(' ');
+    return renderedImage.replace('<img ', `<img ${attrsStr} `);
+  }
+  return renderedImage;
+};
+
+// Add IDs to headings for anchor links, used by the Table of Contents.
+const headingIdPlugin = (md) => {
+  const defaultRender = function(tokens, idx, options, env, self) {
+    return self.renderToken(tokens, idx, options);
+  };
+  const headingOpenRenderer = function(tokens, idx, options, env, self) {
+    const token = tokens[idx];
+    const contentToken = tokens[idx + 1];
+    if (contentToken && contentToken.type === 'inline') {
+      const headingText = contentToken.content;
+      const id = headingText.toLowerCase().replace(/\s+/g, '-').replace(/[^\w-]/g, '').replace(/--+/g, '-').replace(/^-+|-+$/g, '');
+      if (id) { token.attrSet('id', id); }
+    }
+    return defaultRender(tokens, idx, options, env, self);
+  }
 }
 
-/**
- * Decodes HTML entities in a string
- * @param {string} html - The HTML string to decode
- * @returns {string} - Decoded string
- */
+
+// ===================================================================
+// --- SAFE CONTAINER WRAPPER (FOR SIMPLE CONTAINERS) ---
+// The safeContainer function has been replaced by the advanced nested container system
+// which provides better nesting support and more robust parsing.
+
+// ===================================================================
+// --- ADVANCED NESTED CONTAINER SYSTEM IMPLEMENTATION ---
+// ===================================================================
+
+// The advanced nested container system is now implemented above
+// All containers (card, callout, button, steps, tabs) are handled by the new system
+// which supports seamless nesting of any container within any other container.
+
+
+// --- UTILITY AND PROCESSING FUNCTIONS ---
+
 function decodeHtmlEntities(html) {
-  return html
-    .replace(/&amp;/g, '&')
-    .replace(/&lt;/g, '<')
-    .replace(/&gt;/g, '>')
-    .replace(/&quot;/g, '"')
-    .replace(/&#39;/g, "'")
-    .replace(/&nbsp;/g, ' ');
+  return html.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"').replace(/'/g, "'").replace(/ /g, ' ');
 }
 
-/**
- * Extracts headings from HTML content for table of contents generation
- * @param {string} htmlContent - The rendered HTML content
- * @returns {Array} - Array of heading objects with id, level, and text
- */
 function extractHeadingsFromHtml(htmlContent) {
   const headings = [];
-  
-  // Regular expression to find heading tags (h1-h6) with their content and id attributes
   const headingRegex = /<h([1-6])[^>]*?id="([^"]*)"[^>]*?>([\s\S]*?)<\/h\1>/g;
-  
   let match;
   while ((match = headingRegex.exec(htmlContent)) !== null) {
     const level = parseInt(match[1], 10);
     const id = match[2];
-    // Remove any HTML tags inside the heading text
-    const textWithTags = match[3].replace(/<\/?[^>]+(>|$)/g, '');
-    // Decode any HTML entities in the text
-    const text = decodeHtmlEntities(textWithTags);
-    
+    const text = decodeHtmlEntities(match[3].replace(/<\/?[^>]+(>|$)/g, ''));
     headings.push({ id, level, text });
   }
-  
   return headings;
 }
 
-async function processMarkdownFile(filePath, options = { isDev: false }) {
+async function processMarkdownFile(filePath, md, config) {
   const rawContent = await fs.readFile(filePath, 'utf8');
   let frontmatter, markdownContent;
 
   try {
-    const parsed = matter(rawContent);
-    frontmatter = parsed.data;
-    markdownContent = parsed.content;
+    ({ data: frontmatter, content: markdownContent } = matter(rawContent));
   } catch (e) {
-    if (e.name === 'YAMLException') {
-      // Provide more specific error for YAML parsing issues
-      const errorMessage = `Error parsing YAML frontmatter in ${formatPathForDisplay(filePath)}: ${e.reason || e.message}${e.mark ? ` at line ${e.mark.line + 1}, column ${e.mark.column + 1}` : ''}. Please check the syntax.`;
-      console.error(`❌ ${errorMessage}`);
-      throw new Error(errorMessage); // Propagate error to stop build/dev
-    }
-    // For other errors from gray-matter or unknown errors
-    console.error(`❌ Error processing frontmatter in ${formatPathForDisplay(filePath)}: ${e.message}`);
-    throw e;
+    console.error(`❌ Error parsing frontmatter in ${formatPathForDisplay(filePath)}:`);
+    console.error(`   ${e.message}`);
+    console.error('   This page will be skipped. Please fix the YAML syntax.');
+    return null;
   }
 
   if (!frontmatter.title) {
-    console.warn(`⚠️ Warning: Markdown file ${formatPathForDisplay(filePath)} is missing a 'title' in its frontmatter. Using filename as fallback.`);
-    // Fallback title, or you could make it an error
-    // frontmatter.title = path.basename(filePath, path.extname(filePath));
-  }
-
-  // Special handling for no-style pages with HTML content
-  if (frontmatter.noStyle === true) {
-    // Only log when not in dev mode to reduce console output during dev
-    if (!options.isDev) {
-      console.log(`📄 Processing no-style page: ${formatPathForDisplay(filePath)} - Using raw HTML content`);
+    if (config.autoTitleFromH1 !== false) {
+        const h1Match = markdownContent.match(/^#\s+(.*)/m);
+        if (h1Match && h1Match[1]) {
+            frontmatter.title = h1Match[1].trim();
+        }
+    }
+    if (!frontmatter.title) {
+        console.warn(`⚠️ Warning: Markdown file ${formatPathForDisplay(filePath)} has no title in frontmatter and no H1 fallback. The page header will be hidden.`);
     }
-    
-    // For no-style pages, we'll use the raw content directly
-    // No markdown processing, no HTML escaping
-    const htmlContent = markdownContent;
-    
-    // Extract headings for table of contents (if needed)
-    const headings = extractHeadingsFromHtml(htmlContent);
-
-    return {
-      frontmatter,
-      htmlContent,
-      headings,
-    };
   }
 
-  // Regular processing for standard pages
-  // Check if this is a documentation example showing how to use containers
-  const isContainerDocumentation = markdownContent.includes('containerName [optionalTitleOrType]') || 
-                                  markdownContent.includes('## Callouts') || 
-                                  markdownContent.includes('## Cards') || 
-                                  markdownContent.includes('## Steps');
-
-  // Special handling for container documentation - escape container syntax in code blocks
-  if (isContainerDocumentation) {
-    markdownContent = escapeContainerSyntax(markdownContent);
+  let htmlContent, headings;
+  if (frontmatter.noStyle === true) {
+    // For noStyle pages, NO markdown processing at all
+    // Pass the raw content directly as-is
+    htmlContent = markdownContent;
+    headings = [];
+  } else {
+    htmlContent = md.render(markdownContent);
+    headings = extractHeadingsFromHtml(htmlContent);
   }
-  
-  // Normalize container syntax
-  const normalizedContent = normalizeContainerSyntax(markdownContent);
-  
-  // Render to HTML
-  let htmlContent = md.render(normalizedContent);
-  
-  // Apply steps formatting
-  htmlContent = processStepsContent(htmlContent);
-
-  // Fix any specific issues
-  // 1. Fix the issue with "These custom containers" paragraph in custom-containers.md
-  htmlContent = htmlContent.replace(
-    /<p>You should see "Application started successfully!" in your console.\s*<\/p>\s*<p>::: These custom containers/,
-    '<p>You should see "Application started successfully!" in your console.</p></div><p>These custom containers'
-  );
-  
-  // 2. Fix any remaining ::: markers at the start of paragraphs
-  htmlContent = htmlContent.replace(/<p>:::\s+(.*?)<\/p>/g, '<p>$1</p>');
-  
-  // 3. Fix any broken Asterisk steps
-  htmlContent = htmlContent.replace(
-    /<div class="step"><h4>\*\. <strong><\/strong><\/h4>(.+?)<\/strong>/,
-    '<div class="step"><h4>*. <strong>$1</strong>'
-  );
-
-  // 4. Replace our special escape marker with nothing (to fix backslash issue in rendered HTML)
-  htmlContent = htmlContent.replace(/___DOCMD_CONTAINER_ESCAPED___/g, '');
-
-  // Extract headings for table of contents
-  const headings = extractHeadingsFromHtml(htmlContent);
 
   return {
-    frontmatter: {
-      title: "Untitled Page", // Default if not provided and no fallback
-      ...frontmatter
-    },
+    frontmatter,
     htmlContent,
-    headings, // Add headings to the returned object
+    headings,
   };
 }
 
-// Add findMarkdownFiles function
-/**
- * Recursively finds all Markdown files in a directory and its subdirectories
- * @param {string} dir - Directory to search in
- * @returns {Promise<string[]>} - Array of file paths
- */
 async function findMarkdownFiles(dir) {
   let files = [];
   const items = await fs.readdir(dir, { withFileTypes: true });
@@ -470,9 +766,9 @@ async function findMarkdownFiles(dir) {
   return files;
 }
 
-module.exports = { 
-  processMarkdownFile, 
-  mdInstance: md, 
+module.exports = {
+  processMarkdownFile,
+  createMarkdownItInstance,
   extractHeadingsFromHtml,
-  findMarkdownFiles // Export the findMarkdownFiles function
+  findMarkdownFiles
 };