@mgks/docmd 0.3.8 → 0.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mgks/docmd",
-  "version": "0.3.8",
+  "version": "0.3.11",
   "description": "Generate beautiful, lightweight static documentation sites directly from your Markdown files. Zero clutter, just content.",
   "main": "src/index.js",
   "exports": {
@@ -37,7 +37,7 @@
     "esbuild": "^0.27.2",
     "gray-matter": "^4.0.3",
     "highlight.js": "^11.11.1",
-    "lucide-static": "^0.562.0",
+    "lucide-static": "^0.563.0",
     "markdown-it": "^14.1.0",
     "markdown-it-abbr": "^2.0.0",
     "markdown-it-attrs": "^4.3.1",

package/src/assets/css/docmd-main.css

@@ -51,6 +51,11 @@
     --lightbox-text: #fff
 }
 
+html {
+    scroll-behavior: smooth;
+    scroll-padding-top: 80px;
+}
+
 body {
     font-family: var(--font-family-sans);
     background-color: var(--bg-color);
@@ -212,7 +217,6 @@ body.sidebar-collapsed .main-content-wrapper {
     flex-grow: 1;
     display: flex;
     flex-direction: column;
-    overflow: hidden
 }
 
 .header-left,
@@ -848,13 +852,6 @@ details[open]>.collapsible-summary .collapsible-arrow svg {
     margin-bottom: .5rem
 }
 
-.toc-title {
-    margin-top: 0;
-    font-size: 1rem;
-    font-weight: 700;
-    color: var(--text-muted)
-}
-
 .toc-list {
     list-style: none;
     padding-left: 0;
@@ -866,31 +863,84 @@ details[open]>.collapsible-summary .collapsible-arrow svg {
     line-height: 1.4
 }
 
+/* Base Link State */
 .toc-link {
-    text-decoration: none;
-    color: var(--link-color);
-    display: inline-block;
-    padding: .1rem 0;
-    font-size: .9rem;
-    font-weight: 500
+    display: block;
+    padding: 0.3rem 1rem;
+    font-size: 0.85rem;
+    color: var(--text-secondary);
+    /* Pre-allocate border space to prevent jumping */
+    border-left: 2px solid transparent;
+    margin-left: -1px; /* Overlap the sidebar's border-left */
+    transition: all 0.2s ease;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
 }
 
-.toc-level-3 {
-    margin-left: .75rem;
-    font-size: .85rem
+.toc-link:hover {
+    color: var(--text-primary);
+    background-color: var(--bg-surface);
 }
 
-.toc-level-4 {
-    margin-left: 1.5rem;
-    font-size: .8rem
+/* Active State - Only changes color, no layout shift */
+.toc-link.active {
+    color: var(--primary);
+    border-left-color: var(--primary);
+    background-color: var(--primary-light);
 }
 
+/* Nesting Levels */
+.toc-level-3 { padding-left: 2rem; }
+.toc-level-4 { padding-left: 3rem; }
+
+/* Handle Dark Mode specifics for the trail */
+:root[data-theme="dark"] .toc-link.active {
+    background-color: rgba(59, 130, 246, 0.1);
+}
+
+/* TOC Sidebar Container */
 .toc-sidebar {
-    width: 180px;
+    position: -webkit-sticky;
     position: sticky;
-    top: 2rem;
+    top: 5rem;
+    max-height: calc(100vh - 15rem);
     overflow-y: auto;
-    align-self: flex-start
+    align-self: flex-start;
+    /* Create the vertical guide rail */
+    border-left: 1px solid var(--border-color);
+    padding-left: 0; 
+    margin-left: 1rem;
+}
+
+.toc-container {
+    padding: 0;
+}
+
+.toc-title {
+    padding-left: 1rem;
+    margin-bottom: 1rem;
+    font-size: 0.75rem;
+    color: var(--text-tertiary);
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+}
+
+@media (max-width: 1024px) {
+    .content-layout {
+        flex-direction: column-reverse;
+    }
+
+    .toc-sidebar {
+        position: static; 
+        width: 100%;
+        max-height: none;
+        margin-bottom: 2rem;
+        border-left: none;
+        border-bottom: 1px solid var(--border-color);
+        padding-left: 0;
+        padding-bottom: 1rem;
+    }
 }
 
 .docmd-tabs,

package/src/assets/js/docmd-main.js

@@ -209,6 +209,43 @@ function syncBodyTheme() {
   }
 }
 
+// --- Scroll Spy Logic ---
+function initializeScrollSpy() {
+  const tocLinks = document.querySelectorAll('.toc-link');
+  const headings = document.querySelectorAll('.main-content h2, .main-content h3');
+  
+  if (tocLinks.length === 0 || headings.length === 0) return;
+
+  const observerOptions = {
+    root: null,
+    // Trigger when heading crosses the top 10% of screen
+    rootMargin: '-10% 0px -80% 0px', 
+    threshold: 0
+  };
+
+  const observer = new IntersectionObserver((entries) => {
+    entries.forEach(entry => {
+      if (entry.isIntersecting) {
+        // 1. Clear current active state
+        tocLinks.forEach(link => link.classList.remove('active'));
+        
+        // 2. Find link corresponding to this heading
+        const id = entry.target.getAttribute('id');
+        const activeLink = document.querySelector(`.toc-link[href="#${id}"]`);
+        
+        if (activeLink) {
+            activeLink.classList.add('active');
+            
+            // Optional: Auto-scroll the TOC sidebar itself if needed
+            // activeLink.scrollIntoView({ block: 'nearest' });
+        }
+      }
+    });
+  }, observerOptions);
+
+  headings.forEach(heading => observer.observe(heading));
+}
+
 // --- Main Execution ---
 document.addEventListener('DOMContentLoaded', () => {
   syncBodyTheme();
@@ -219,4 +256,5 @@ document.addEventListener('DOMContentLoaded', () => {
   initializeCollapsibleNav();
   initializeMobileMenus();
   initializeSidebarScroll();
+  initializeScrollSpy();
 });

package/src/core/config-loader.js

@@ -38,6 +38,7 @@ async function loadConfig(configPath) {
     validateConfig(config);
 
     // Basic validation and defaults
+    config.base = config.base || '/';
     config.srcDir = config.srcDir || 'docs';
     config.outputDir = config.outputDir || 'site';
     config.theme = config.theme || {};

package/src/core/html-generator.js

@@ -7,12 +7,10 @@ const { createMarkdownItInstance } = require('./file-processor');
 const { generateSeoMetaTags } = require('../plugins/seo');
 const { generateAnalyticsScripts } = require('../plugins/analytics');
 const { renderIcon } = require('./icon-renderer');
-const { formatHtml } = require('./html-formatter');
 
 let mdInstance = null;
 let themeInitScript = '';
 
-// Load the theme initialization script into memory once to avoid repeated disk I/O
 (async () => {
     try {
         const themeInitPath = path.join(__dirname, '..', 'templates', 'partials', 'theme-init.js');
@@ -23,51 +21,59 @@ let themeInitScript = '';
     } catch (e) { /* ignore */ }
 })();
 
-// Removes excessive whitespace and blank lines from the generated HTML
+// Basic whitespace cleanup (keep this simple version)
 function cleanupHtml(html) {
     if (!html) return '';
-    return html
-        .replace(/^[ \t]+$/gm, '')
-        .replace(/\n{3,}/g, '\n\n')
-        .trim();
+    // return html.replace(/^\s*[\r\n]/gm, '').trim(); // Remove leading/trailing blank lines from each line
+    return html.trim(); // Only trim the start/end of the whole document
 }
 
-// Rewrites links based on build mode (Offline/File protocol vs Web Server)
-function fixHtmlLinks(htmlContent, relativePathToRoot, isOfflineMode) {
+function fixHtmlLinks(htmlContent, relativePathToRoot, isOfflineMode, configBase = '/') {
     if (!htmlContent) return '';
     const root = relativePathToRoot || './';
+    const baseUrl = configBase.endsWith('/') ? configBase : configBase + '/';
 
-    return htmlContent.replace(/href="((?:\/|\.\/|\.\.\/)[^"]*)"/g, (match, href) => {
-        let finalPath = href;
-        
-        // Convert absolute project paths to relative
-        if (href.startsWith('/')) {
-            finalPath = root + href.substring(1);
+    return htmlContent.replace(/(href|src)=["']([^"']+)["']/g, (match, attr, url) => {
+        if (url.startsWith('#') || url.startsWith('http') || url.startsWith('mailto:') || url === '') {
+            return match;
         }
-        
-        // Handle offline mode (force index.html for directories)
+
+        let finalPath = url;
+
+        // 1. Handle Base URL removal
+        if (baseUrl !== '/' && url.startsWith(baseUrl)) {
+            finalPath = '/' + url.substring(baseUrl.length);
+        }
+
+        // 2. Handle Absolute Paths
+        if (finalPath.startsWith('/')) {
+            // Simple logic: if root relative, prepend relative path
+            finalPath = root + finalPath.substring(1);
+        }
+
+        // 3. Offline Mode Logic
         if (isOfflineMode) {
-            const cleanPath = finalPath.split('#')[0].split('?')[0];
-            if (!path.extname(cleanPath)) {
-                if (finalPath.includes('#')) {
-                    const parts = finalPath.split('#');
-                    const prefix = parts[0].endsWith('/') ? parts[0] : parts[0] + '/';
-                    finalPath = prefix + 'index.html#' + parts[1];
-                } else {
-                    finalPath += (finalPath.endsWith('/') ? '' : '/') + 'index.html';
+            const [pathOnly] = finalPath.split(/[?#]/);
+            const ext = path.extname(pathOnly);
+            const isAsset = ['.css', '.js', '.png', '.jpg', '.jpeg', '.gif', '.svg', '.ico'].includes(ext.toLowerCase());
+            
+            if (!isAsset && !ext) {
+                if (finalPath.endsWith('/')) {
+                    finalPath += 'index.html';
+                } else if (!finalPath.includes('#')) {
+                    finalPath += '/index.html';
                 }
             }
         } else {
-            // Web mode (strip index.html for clean URLs)
             if (finalPath.endsWith('/index.html')) {
                 finalPath = finalPath.substring(0, finalPath.length - 10);
             }
         }
-        return `href="${finalPath}"`;
+        
+        return `${attr}="${finalPath}"`;
     });
 }
 
-// aggregates HTML snippets from various plugins (SEO, Analytics, etc.)
 async function processPluginHooks(config, pageData, relativePathToRoot) {
     let metaTagsHtml = '';
     let faviconLinkHtml = '';
@@ -77,17 +83,16 @@ async function processPluginHooks(config, pageData, relativePathToRoot) {
     let pluginBodyScriptsHtml = '';
 
     const safeRoot = relativePathToRoot || './';
-    const indent = '    '; // 4 spaces for cleaner output
 
     if (config.favicon) {
         const cleanFaviconPath = config.favicon.startsWith('/') ? config.favicon.substring(1) : config.favicon;
         const finalFaviconHref = `${safeRoot}${cleanFaviconPath}`;
-        faviconLinkHtml = `${indent}<link rel="icon" href="${finalFaviconHref}" type="image/x-icon" sizes="any">\n${indent}<link rel="shortcut icon" href="${finalFaviconHref}" type="image/x-icon">`;
+        faviconLinkHtml = `<link rel="icon" href="${finalFaviconHref}" type="image/x-icon" sizes="any">\n<link rel="shortcut icon" href="${finalFaviconHref}" type="image/x-icon">`;
     }
 
     if (config.theme && config.theme.name && config.theme.name !== 'default') {
         const themeCssPath = `assets/css/docmd-theme-${config.theme.name}.css`;
-        themeCssLinkHtml = `${indent}<link rel="stylesheet" href="${safeRoot}${themeCssPath}">`;
+        themeCssLinkHtml = `<link rel="stylesheet" href="${safeRoot}${themeCssPath}">`;
     }
 
     if (config.plugins?.seo) {
@@ -103,7 +108,6 @@ async function processPluginHooks(config, pageData, relativePathToRoot) {
     return { metaTagsHtml, faviconLinkHtml, themeCssLinkHtml, pluginStylesHtml, pluginHeadScriptsHtml, pluginBodyScriptsHtml };
 }
 
-// Main function to assemble the page data and render the EJS template
 async function generateHtmlPage(templateData, isOfflineMode = false) {
     let { content, frontmatter, outputPath, headings, config } = templateData;
     const { currentPagePath, prevPage, nextPage, relativePathToRoot, navigationHtml, siteTitle } = templateData;
@@ -111,19 +115,16 @@ async function generateHtmlPage(templateData, isOfflineMode = false) {
 
     if (!relativePathToRoot) templateData.relativePathToRoot = './';
 
-    // Process content links and generate plugin assets
-    content = fixHtmlLinks(content, templateData.relativePathToRoot, isOfflineMode);
+    content = fixHtmlLinks(content, templateData.relativePathToRoot, isOfflineMode, config.base);
     const pluginOutputs = await processPluginHooks(config, { frontmatter, outputPath }, templateData.relativePathToRoot);
 
-    // Process footer markdown if present
     let footerHtml = '';
     if (config.footer) {
         if (!mdInstance) mdInstance = createMarkdownItInstance(config);
         footerHtml = mdInstance.renderInline(config.footer);
-        footerHtml = fixHtmlLinks(footerHtml, templateData.relativePathToRoot, isOfflineMode);
+        footerHtml = fixHtmlLinks(footerHtml, templateData.relativePathToRoot, isOfflineMode, config.base);
     }
 
-    // Determine which template to use
     let templateName = frontmatter.noStyle === true ? 'no-style.ejs' : 'layout.ejs';
     const layoutTemplatePath = path.join(__dirname, '..', 'templates', templateName);
     if (!await fs.exists(layoutTemplatePath)) throw new Error(`Template not found: ${layoutTemplatePath}`);
@@ -131,7 +132,6 @@ async function generateHtmlPage(templateData, isOfflineMode = false) {
 
     const isActivePage = currentPagePath && content && content.trim().length > 0;
 
-    // Build the "Edit this page" link
     let editUrl = null;
     let editLinkText = 'Edit this page';
     if (config.editLink && config.editLink.enabled && config.editLink.baseUrl) {
@@ -141,10 +141,9 @@ async function generateHtmlPage(templateData, isOfflineMode = false) {
          editLinkText = config.editLink.text || editLinkText;
     }
 
-    // Prepare complete data object for EJS
     const ejsData = {
         ...templateData,
-        description: frontmatter.description || '', // Fix for reference error
+        description: frontmatter.description || '',
         footerHtml, editUrl, editLinkText, isActivePage,
         defaultMode: config.theme?.defaultMode || 'light',
         logo: config.logo, sidebarConfig: config.sidebar || {}, theme: config.theme,
@@ -155,13 +154,12 @@ async function generateHtmlPage(templateData, isOfflineMode = false) {
         isOfflineMode 
     };
 
-    // Render and format
     const rawHtml = renderHtmlPage(layoutTemplate, ejsData, layoutTemplatePath);
     const pkgVersion = require('../../package.json').version;
     const brandingComment = `<!-- Generated by docmd (v${pkgVersion}) - https://docmd.io -->\n`;
     
-    // Apply smart formatting to the final HTML string
-    return brandingComment + formatHtml(rawHtml);
+    // REMOVED: formatHtml(rawHtml)
+    return brandingComment + cleanupHtml(rawHtml);
 }
 
 function renderHtmlPage(templateContent, ejsData, filename = 'template.ejs', options = {}) {
@@ -173,14 +171,12 @@ function renderHtmlPage(templateContent, ejsData, filename = 'template.ejs', opt
     }
 }
 
-// Generate the sidebar navigation HTML separately
 async function generateNavigationHtml(navItems, currentPagePath, relativePathToRoot, config, isOfflineMode = false) {
     const navTemplatePath = path.join(__dirname, '..', 'templates', 'navigation.ejs');
     if (!await fs.exists(navTemplatePath)) throw new Error(`Navigation template not found: ${navTemplatePath}`);
     const navTemplate = await fs.readFile(navTemplatePath, 'utf8');
     const safeRoot = relativePathToRoot || './';
 
-    // We render raw here; the main page formatter will clean this up later
     return ejs.render(navTemplate, { 
         navItems, currentPagePath, relativePathToRoot: safeRoot, config, isOfflineMode, renderIcon 
     }, { filename: navTemplatePath });

package/src/core/markdown/rules.js

@@ -1,14 +1,49 @@
 // Source file from the docmd project — https://github.com/docmd-io/docmd
 
-const MarkdownIt = require('markdown-it'); // Required for inner rendering fallback logic
+const MarkdownIt = require('markdown-it');
 const { containers } = require('./containers');
 
-// --- Helper: Create isolated parser for tabs (prevents recursion stack issues) ---
-// Note: We pass a callback to get the main config logic from setup.js later if needed,
-// but for now we reconstruct a basic one for tab/changelog internals to ensure plugins run.
-// Ideally, we prefer reusing state.md.render() where possible.
+// --- Helper: Smart Dedent ---
+// This handles the "Tab Indentation" and "Code Block" nesting issues
+function smartDedent(str) {
+    const lines = str.split('\n');
+    
+    // 1. Calculate global minimum indent (ignoring empty lines)
+    let minIndent = Infinity;
+    lines.forEach(line => {
+        if (line.trim().length === 0) return;
+        const match = line.match(/^ */);
+        const indent = match ? match[0].length : 0;
+        if (indent < minIndent) minIndent = indent;
+    });
+
+    if (minIndent === Infinity) return str;
+
+    // 2. Strip the common indent
+    const dedented = lines.map(line => {
+        if (line.trim().length === 0) return '';
+        return line.substring(minIndent);
+    });
+
+    // 3. Fix Code Fences
+    // If a line looks like a code fence (```) but is still indented 4+ spaces,
+    // it will be parsed as an "Indented Code Block" containing text, not a Fence.
+    // We force-pull these specific lines to the left to ensure they render as Fences.
+    return dedented.map(line => {
+        // Regex: 4 or more spaces, followed by 3 or more backticks/tildes
+        if (/^\s{4,}(`{3,}|~{3,})/.test(line)) {
+            return line.trimStart(); 
+        }
+        return line;
+    }).join('\n');
+}
+
+// Helper to check if a line starts a fence
+function isFenceLine(line) {
+    return /^(\s{0,3})(~{3,}|`{3,})/.test(line);
+}
 
-// --- 1. Advanced Container Rule (Nesting Logic) ---
+// --- 1. Advanced Container Rule ---
 function advancedContainerRule(state, startLine, endLine, silent) {
   const start = state.bMarks[startLine] + state.tShift[startLine];
   const max = state.eMarks[startLine];
@@ -33,6 +68,7 @@ function advancedContainerRule(state, startLine, endLine, silent) {
   let nextLine = startLine;
   let found = false;
   let depth = 1;
+  let inFence = false;
   
   while (nextLine < endLine) {
     nextLine++;
@@ -40,23 +76,28 @@ function advancedContainerRule(state, startLine, endLine, silent) {
     const nextMax = state.eMarks[nextLine];
     const nextContent = state.src.slice(nextStart, nextMax).trim();
     
-    if (nextContent.startsWith(':::')) {
-      const containerMatch = nextContent.match(/^:::\s*(\w+)/);
-      if (containerMatch && containerMatch[1] !== containerName) {
-        const innerContainer = containers[containerMatch[1]];
-        if (innerContainer && innerContainer.render && !innerContainer.selfClosing) {
-          depth++;
+    // Check for fences to prevent parsing ::: inside code blocks (#42)
+    if (isFenceLine(nextContent)) inFence = !inFence;
+
+    if (!inFence) {
+        if (nextContent.startsWith(':::')) {
+          const containerMatch = nextContent.match(/^:::\s*(\w+)/);
+          if (containerMatch && containerMatch[1] !== containerName) {
+            const innerContainer = containers[containerMatch[1]];
+            if (innerContainer && innerContainer.render && !innerContainer.selfClosing) {
+              depth++;
+            }
+            continue;
+          }
+        }
+        
+        if (nextContent === ':::') {
+          depth--;
+          if (depth === 0) {
+            found = true;
+            break;
+          }
         }
-        continue;
-      }
-    }
-    
-    if (nextContent === ':::') {
-      depth--;
-      if (depth === 0) {
-        found = true;
-        break;
-      }
     }
   }
   
@@ -81,7 +122,7 @@ function advancedContainerRule(state, startLine, endLine, silent) {
   return true;
 }
 
-// --- 2. Changelog Timeline Rule (FIXED FOR NESTING) ---
+// --- 2. Changelog Timeline Rule ---
 function changelogTimelineRule(state, startLine, endLine, silent) {
   const start = state.bMarks[startLine] + state.tShift[startLine];
   const max = state.eMarks[startLine];
@@ -93,6 +134,7 @@ function changelogTimelineRule(state, startLine, endLine, silent) {
   let nextLine = startLine;
   let found = false;
   let depth = 1;
+  let inFence = false;
   
   while (nextLine < endLine) {
     nextLine++;
@@ -100,21 +142,21 @@ function changelogTimelineRule(state, startLine, endLine, silent) {
     const nextMax = state.eMarks[nextLine];
     const nextContent = state.src.slice(nextStart, nextMax).trim();
     
-    if (nextContent.startsWith(':::')) {
-      const match = nextContent.match(/^:::\s*(\w+)/);
-      if (match) {
-        const containerName = match[1];
-        // Don't count self-closing like buttons for depth
-        const containerDef = containers[containerName];
-        if (!containerDef || !containerDef.selfClosing) {
-           depth++;
+    if (isFenceLine(nextContent)) inFence = !inFence;
+
+    if (!inFence) {
+        if (nextContent.startsWith(':::')) {
+          const match = nextContent.match(/^:::\s*(\w+)/);
+          if (match) {
+            const containerName = match[1];
+            const containerDef = containers[containerName];
+            if (!containerDef || !containerDef.selfClosing) depth++;
+          }
+        }
+        if (nextContent === ':::') {
+          depth--;
+          if (depth === 0) { found = true; break; }
         }
-      }
-    }
-    
-    if (nextContent === ':::') {
-      depth--;
-      if (depth === 0) { found = true; break; }
     }
   }
   
@@ -130,25 +172,26 @@ function changelogTimelineRule(state, startLine, endLine, silent) {
   const lines = content.split('\n');
   const entries = [];
   let currentEntry = null;
-  let currentContent = [];
+  let currentContentLines = [];
 
   for (let i = 0; i < lines.length; i++) {
-    const line = lines[i].trim();
-    const markerMatch = line.match(/^==\s+(.+)$/);
+    const rawLine = lines[i];
+    const trimmedLine = rawLine.trim();
+    const markerMatch = trimmedLine.match(/^==\s+(.+)$/);
 
     if (markerMatch) {
       if (currentEntry) {
-        currentEntry.content = currentContent.join('\n');
+        currentEntry.content = smartDedent(currentContentLines.join('\n'));
         entries.push(currentEntry);
       }
       currentEntry = { meta: markerMatch[1], content: '' };
-      currentContent = [];
+      currentContentLines = [];
     } else if (currentEntry) {
-      currentContent.push(lines[i]); 
+      currentContentLines.push(rawLine);
     }
   }
   if (currentEntry) {
-    currentEntry.content = currentContent.join('\n');
+    currentEntry.content = smartDedent(currentContentLines.join('\n'));
     entries.push(currentEntry);
   }
 
@@ -160,7 +203,6 @@ function changelogTimelineRule(state, startLine, endLine, silent) {
       <div class="changelog-meta"><span class="changelog-date">${entry.meta}</span></div>
       <div class="changelog-body">`;
 
-    // This ensures callouts/cards inside changelogs are parsed
     entryOpen.content += state.md.render(entry.content, state.env);
     
     const entryClose = state.push('html_block', '', 0);
@@ -183,6 +225,7 @@ function stepsContainerRule(state, startLine, endLine, silent) {
     let nextLine = startLine;
     let found = false;
     let depth = 1;
+    let inFence = false;
     
     while (nextLine < endLine) {
       nextLine++;
@@ -190,23 +233,23 @@ function stepsContainerRule(state, startLine, endLine, silent) {
       const nextMax = state.eMarks[nextLine];
       const nextContent = state.src.slice(nextStart, nextMax).trim();
       
-      if (nextContent.startsWith('== tab')) { continue; }
-      
-      if (nextContent.startsWith(':::')) {
-        const containerMatch = nextContent.match(/^:::\s*(\w+)/);
-        if (containerMatch) {
-          const containerName = containerMatch[1];
-          const innerContainer = containers[containerName];
-          if (innerContainer && !innerContainer.selfClosing) {
-            depth++;
+      if (isFenceLine(nextContent)) inFence = !inFence;
+
+      if (!inFence) {
+          if (nextContent.startsWith('== tab')) continue;
+          if (nextContent.startsWith(':::')) {
+            const containerMatch = nextContent.match(/^:::\s*(\w+)/);
+            if (containerMatch) {
+              const containerName = containerMatch[1];
+              const innerContainer = containers[containerName];
+              if (innerContainer && !innerContainer.selfClosing) depth++;
+              continue;
+            }
+          }
+          if (nextContent === ':::') {
+            depth--;
+            if (depth === 0) { found = true; break; }
           }
-          continue;
-        }
-      }
-      
-      if (nextContent === ':::') {
-        depth--;
-        if (depth === 0) { found = true; break; }
       }
     }
     
@@ -227,7 +270,7 @@ function stepsContainerRule(state, startLine, endLine, silent) {
     return true;
 }
 
-// --- 4. Enhanced Tabs Rule ---
+// --- 4. Enhanced Tabs Rule (Fixed) ---
 function enhancedTabsRule(state, startLine, endLine, silent) {
   const start = state.bMarks[startLine] + state.tShift[startLine];
   const max = state.eMarks[startLine];
@@ -239,61 +282,69 @@ function enhancedTabsRule(state, startLine, endLine, silent) {
   let nextLine = startLine;
   let found = false;
   let depth = 1;
+  let inFence = false;
+
   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();
     
-    if (nextContent.startsWith(':::')) {
-      const containerMatch = nextContent.match(/^:::\s*(\w+)/);
-      if (containerMatch && containerMatch[1] !== 'tabs') {
-        if (containerMatch[1] === 'steps') continue;
-        const innerContainer = containers[containerMatch[1]];
-        if (innerContainer && !innerContainer.selfClosing) depth++;
-        continue;
-      }
-    }
-    
-    if (nextContent === ':::') {
-      depth--;
-      if (depth === 0) { found = true; break; }
+    if (isFenceLine(nextContent)) inFence = !inFence;
+
+    if (!inFence) {
+        if (nextContent.startsWith(':::')) {
+          const containerMatch = nextContent.match(/^:::\s*(\w+)/);
+          if (containerMatch && containerMatch[1] !== 'tabs') {
+            if (containerMatch[1] === 'steps') continue;
+            const innerContainer = containers[containerMatch[1]];
+            if (innerContainer && !innerContainer.selfClosing) depth++;
+            continue;
+          }
+        }
+        if (nextContent === ':::') {
+          depth--;
+          if (depth === 0) { found = true; break; }
+        }
     }
   }
   if (!found) return false;
 
   let content = '';
+  // Capture content preserving newlines
   for (let i = startLine + 1; i < nextLine; i++) {
     const lineStart = state.bMarks[i] + state.tShift[i];
     const lineEnd = state.eMarks[i];
+    // .slice() keeps the indentation of the line as it is in source
     content += state.src.slice(lineStart, lineEnd) + '\n';
   }
 
   const lines = content.split('\n');
   const tabs = [];
   let currentTab = null;
-  let currentContent = [];
+  let currentContentLines = [];
   
   for (let i = 0; i < lines.length; i++) {
-    const line = lines[i].trim();
-    const tabMatch = line.match(/^==\s*tab\s+(?:"([^"]+)"|(\S+))$/);
+    const rawLine = lines[i]; 
+    const trimmedLine = rawLine.trim();
+    
+    const tabMatch = trimmedLine.match(/^==\s*tab\s+(?:"([^"]+)"|(\S+))$/);
     
     if (tabMatch) {
       if (currentTab) {
-        currentTab.content = currentContent.join('\n').trim();
+        // Apply Smart Dedent before saving
+        currentTab.content = smartDedent(currentContentLines.join('\n'));
         tabs.push(currentTab);
       }
       const title = tabMatch[1] || tabMatch[2];
       currentTab = { title: title, content: '' };
-      currentContent = [];
+      currentContentLines = [];
     } else if (currentTab) {
-      if (lines[i].trim() && !lines[i].trim().startsWith('==')) {
-        currentContent.push(lines[i]);
-      }
+      currentContentLines.push(rawLine); 
     }
   }
   if (currentTab) {
-    currentTab.content = currentContent.join('\n').trim();
+    currentTab.content = smartDedent(currentContentLines.join('\n'));
     tabs.push(currentTab);
   }
 
@@ -315,10 +366,8 @@ function enhancedTabsRule(state, startLine, endLine, silent) {
     const paneToken = state.push('tab_pane_open', 'div', 1);
     paneToken.attrs = [['class', `docmd-tab-pane ${index === 0 ? 'active' : ''}`]];
     
-    if (tab.content.trim()) {
-        // Use recursion here if possible, or create basic instance to prevent circular dep issues in this modular file
-        // Since we are inside rules.js, we rely on state.md being available or fallback to simple render
-        const renderedContent = state.md.render(tab.content.trim(), state.env);
+    if (tab.content) {
+        const renderedContent = state.md.render(tab.content, state.env);
         const htmlToken = state.push('html_block', '', 0);
         htmlToken.content = renderedContent;
     }
@@ -331,7 +380,6 @@ function enhancedTabsRule(state, startLine, endLine, silent) {
   return true;
 }
 
-// --- 5. Standalone Closing Rule ---
 const standaloneClosingRule = (state, startLine, endLine, silent) => {
   const start = state.bMarks[startLine] + state.tShift[startLine];
   const max = state.eMarks[startLine];

package/src/core/markdown/setup.js

@@ -20,33 +20,25 @@ const headingIdPlugin = (md) => {
 
   md.renderer.rules.heading_open = function(tokens, idx, options, env, self) {
     const token = tokens[idx];
-    
-    // Check if an ID was already set by markdown-it-attrs (e.g. {#my-id})
     const existingId = token.attrGet('id');
 
-    // If NO ID exists, generate one automatically from the text content
     if (!existingId) {
       const contentToken = tokens[idx + 1];
       if (contentToken && contentToken.type === 'inline' && contentToken.content) {
         const headingText = contentToken.content;
-        
-        // Note: markdown-it-attrs strips the curly braces content from .content 
-        // BEFORE this rule runs, so headingText should be clean.
-        
         const id = headingText
           .toLowerCase()
-          .replace(/\s+/g, '-')       // Replace spaces with -
-          .replace(/[^\w\u4e00-\u9fa5-]+/g, '') // Remove all non-word chars (keeping hyphens). Added unicode support implies keeping more chars if needed.
-          .replace(/--+/g, '-')       // Replace multiple - with single -
-          .replace(/^-+/, '')         // Trim - from start of text
-          .replace(/-+$/, '');        // Trim - from end of text
+          .replace(/\s+/g, '-')
+          .replace(/[^\w\u4e00-\u9fa5-]+/g, '')
+          .replace(/--+/g, '-')
+          .replace(/^-+/, '')
+          .replace(/-+$/, '');
 
         if (id) {
           token.attrSet('id', id);
         }
       }
     }
-    
     return originalHeadingOpen(tokens, idx, options, env, self);
   };
 };
@@ -59,13 +51,15 @@ function createMarkdownItInstance(config) {
     breaks: true,
   };
   
+  // Removed newlines from template literals to prevent extra padding in <pre> blocks
   const highlightFn = (str, lang) => {
     if (lang === 'mermaid') {
       return `<pre class="mermaid">${new MarkdownIt().utils.escapeHtml(str)}</pre>`;
     }
     if (lang && hljs.getLanguage(lang)) {
       try {
-        return `<pre class="hljs"><code>${hljs.highlight(str, { language: lang, ignoreIllegals: true }).value}</code></pre>`;
+        const highlighted = hljs.highlight(str, { language: lang, ignoreIllegals: true }).value;
+        return `<pre class="hljs"><code>${highlighted}</code></pre>`;
       } catch (e) { console.error(e); }
     }
     return `<pre class="hljs"><code>${new MarkdownIt().utils.escapeHtml(str)}</code></pre>`;
@@ -78,7 +72,6 @@ function createMarkdownItInstance(config) {
 
   const md = new MarkdownIt(mdOptions);
 
-  // Plugins
   md.use(attrs, { leftDelimiter: '{', rightDelimiter: '}' });
   md.use(markdown_it_footnote);
   md.use(markdown_it_task_lists);
@@ -86,28 +79,24 @@ function createMarkdownItInstance(config) {
   md.use(markdown_it_deflist);
   md.use(headingIdPlugin);
 
-  // Register 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 Rules (Order Matters)
   md.block.ruler.before('fence', 'steps_container', rules.stepsContainerRule, { alt: ['paragraph', 'reference', 'blockquote', 'list'] });
   md.block.ruler.before('fence', 'enhanced_tabs', rules.enhancedTabsRule, { alt: ['paragraph', 'reference', 'blockquote', 'list'] });
   md.block.ruler.before('fence', 'changelog_timeline', rules.changelogTimelineRule, { alt: ['paragraph', 'reference', 'blockquote', 'list'] });
   md.block.ruler.before('paragraph', 'advanced_container', rules.advancedContainerRule, { alt: ['paragraph', 'reference', 'blockquote', 'list'] });
   md.block.ruler.before('paragraph', 'standalone_closing', rules.standaloneClosingRule, { alt: ['paragraph', 'reference', 'blockquote', 'list'] });
 
-  // Register Renderers
   md.renderer.rules.ordered_list_open = renderers.customOrderedListOpenRenderer;
   md.renderer.rules.list_item_open = renderers.customListItemOpenRenderer;
   md.renderer.rules.image = renderers.customImageRenderer;
   md.renderer.rules.table_open = renderers.tableOpenRenderer;
   md.renderer.rules.table_close = renderers.tableCloseRenderer;
 
-  // Tabs Renderers
   md.renderer.rules.tabs_open = renderers.tabsOpenRenderer;
   md.renderer.rules.tabs_nav_open = renderers.tabsNavOpenRenderer;
   md.renderer.rules.tabs_nav_close = renderers.tabsNavCloseRenderer;

package/src/core/navigation-helper.js

@@ -1,62 +1,74 @@
 // Source file from the docmd project — https://github.com/docmd-io/docmd
 
 /**
- * Flattens the navigation tree and finds the previous and next pages relative to the current page.
- * @param {Array} navItems - The navigation array from config.
- * @param {string} currentPagePath - The normalized path of the current page.
- * @returns {{prevPage: object|null, nextPage: object|null}}
+ * Normalizes paths to a "canonical" form for comparison.
+ * Handles: "./path", "/path", "path/index.html", "path.md"
  */
+function getCanonicalPath(p) {
+  if (!p) return '';
+  if (p.startsWith('http')) return p; // Don't touch external URLs
+
+  // 1. Remove leading dot-slash or slash
+  let path = p.replace(/^(\.\/|\/)+/, '');
+
+  // 2. Remove query strings or hashes
+  path = path.split('?')[0].split('#')[0];
+
+  // 3. Remove file extensions (.html, .md)
+  path = path.replace(/(\.html|\.md)$/, '');
+
+  // 4. Handle index files (folder/index -> folder)
+  if (path.endsWith('/index')) {
+    path = path.slice(0, -6);
+  } else if (path === 'index') {
+    path = '';
+  }
+
+  // 5. Remove trailing slash
+  if (path.endsWith('/')) {
+    path = path.slice(0, -1);
+  }
+
+  return path;
+}
+
 function findPageNeighbors(navItems, currentPagePath) {
   const flatNavigation = [];
+  const currentCanonical = getCanonicalPath(currentPagePath);
 
-  // Recursive function to flatten the navigation tree
-  function extractNavigationItems(items) {
+  function recurse(items) {
     if (!items || !Array.isArray(items)) return;
-    
-    for (const item of items) {
-      if (item.external || !item.path || item.path === '#') {
-        // If it's a category with no path but has children, recurse into them
-        if (item.children && Array.isArray(item.children)) {
-          extractNavigationItems(item.children);
-        }
-        continue; // Skip external links and parent items without a direct path
-      }
 
-      let normalizedItemPath = item.path;
-
-      // Ensure it starts with a slash
-      if (!normalizedItemPath.startsWith('/')) {
-        normalizedItemPath = '/' + normalizedItemPath;
-      }
-
-      // Ensure it ends with a slash (unless it's the root path)
-      if (normalizedItemPath.length > 1 && !normalizedItemPath.endsWith('/')) {
-        normalizedItemPath += '/';
+    for (const item of items) {
+      // Logic: Only consider items that have a path and are NOT external
+      // Also ignore items that are just '#' (placeholder parents)
+      if (item.path && !item.external && !item.path.startsWith('http') && item.path !== '#') {
+        flatNavigation.push({
+          title: item.title,
+          path: item.path, // Keep original path for the HREF
+          canonical: getCanonicalPath(item.path) // Use canonical for comparison
+        });
       }
 
-      flatNavigation.push({
-        title: item.title,
-        path: normalizedItemPath,
-      });
-
-      if (item.children && Array.isArray(item.children)) {
-        extractNavigationItems(item.children);
+      if (item.children) {
+        recurse(item.children);
       }
     }
   }
 
-  extractNavigationItems(navItems);
+  recurse(navItems);
 
-  const currentPageIndex = flatNavigation.findIndex(item => item.path === currentPagePath);
+  // Find index using canonical paths
+  const index = flatNavigation.findIndex(item => item.canonical === currentCanonical);
 
-  if (currentPageIndex === -1) {
+  if (index === -1) {
     return { prevPage: null, nextPage: null };
   }
 
-  const prevPage = currentPageIndex > 0 ? flatNavigation[currentPageIndex - 1] : null;
-  const nextPage = currentPageIndex < flatNavigation.length - 1 ? flatNavigation[currentPageIndex + 1] : null;
-
-  return { prevPage, nextPage };
+  return {
+    prevPage: index > 0 ? flatNavigation[index - 1] : null,
+    nextPage: index < flatNavigation.length - 1 ? flatNavigation[index + 1] : null
+  };
 }
 
 module.exports = { findPageNeighbors };

package/src/templates/navigation.ejs

@@ -1,5 +1,6 @@
 <%# Source file from the docmd project — https://github.com/docmd-io/docmd %>
 
+<%# src/templates/navigation.ejs %>
 <nav class="sidebar-nav" aria-label="Main navigation">
   <ul>
     <%
@@ -33,19 +34,28 @@
           let itemPath = item.path || '#';
           const isAbsoluteUrl = itemPath.startsWith('http://') || itemPath.startsWith('https://');
           const normalizedItemPath = (isExplicitExternal || isAbsoluteUrl) ? itemPath : normalizePath(itemPath);
+          
           const isActive = !isExplicitExternal && !isAbsoluteUrl && currentPagePath === normalizedItemPath;
           const isParentOfActive = !isActive && hasActiveChild(item, currentPagePath);
-          const isCollapsible = item.children && item.collapsible;
+          
+          // Logic: An item is only "collapsible" if children exist AND collapsible flag is true
+          const isCollapsible = item.children && item.collapsible === true;
+          
+          // Logic: It should be open if it's the active parent or it's simply not a collapsible menu
           const shouldBeOpen = isParentOfActive || (isActive && item.children && item.children.length > 0);
+
           const liClasses = [];
           if (isActive) liClasses.push('active');
           if (isParentOfActive) liClasses.push('active-parent');
           if (isCollapsible) liClasses.push('collapsible');
+          
           let liAttributes = `class="${liClasses.join(' ')}"`;
           if (isCollapsible) {
               liAttributes += ` data-nav-id="${item.path}"`;
               if (shouldBeOpen) liAttributes += ` aria-expanded="true"`;
+              else liAttributes += ` aria-expanded="false"`;
           }
+
           let finalHref = item.path;
           if (!isExplicitExternal && !isAbsoluteUrl) {
              if (!itemPath || itemPath === '#') {
@@ -77,7 +87,7 @@
         <% if (isExplicitExternal) { %> <%- renderIcon('external-link', { class: 'nav-external-icon' }) %> <% } %>
       </a>
       <% if (item.children) { %>
-        <ul class="submenu" style="<%= (isCollapsible && shouldBeOpen) ? 'display: block;' : 'display: none;' %>">
+        <ul class="submenu" style="display: <%= (!isCollapsible || shouldBeOpen) ? 'block' : 'none' %>;">
           <% renderNav(item.children); %>
         </ul>
       <% } %>

package/src/templates/partials/theme-init.js

@@ -1,26 +1,32 @@
-// Source file from the docmd project — https://github.com/docmd-io/docmd
-
-/*
- * Initialize the theme from localStorage
- */
+/* Source file from the docmd project — https://github.com/docmd-io/docmd */
 
 (function() {
   try {
-    // Determine Theme
     var localValue = localStorage.getItem('docmd-theme');
     var configValue = window.DOCMD_DEFAULT_MODE || 'light'; 
     var theme = localValue ? localValue : configValue;
     
-    // Set HTML Attribute (for main CSS variables)
+    // Resolve system preference immediately
+    if (theme === 'system') {
+      theme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+    }
+
+    // Apply to HTML and Body to ensure all CSS selectors catch it
     document.documentElement.setAttribute('data-theme', theme);
+    
+    // We use a small interval to ensure body exists (since this script is in head)
+    var checkBody = setInterval(function() {
+      if (document.body) {
+        document.body.setAttribute('data-theme', theme);
+        clearInterval(checkBody);
+      }
+    }, 10);
 
-    // Handle Highlight.js Theme (if present)
+    // Handle Highlight.js Theme
     var highlightLink = document.getElementById('highlight-theme');
     if (highlightLink) {
       var baseHref = highlightLink.getAttribute('data-base-href');
-      // Check if the current href matches the desired theme
-      // If not, swap it immediately before the browser renders code blocks
-      if (baseHref && !highlightLink.href.includes('docmd-highlight-' + theme)) {
+      if (baseHref) {
         highlightLink.href = baseHref + 'docmd-highlight-' + theme + '.css';
       }
     }

package/src/core/html-formatter.js

@@ -1,97 +0,0 @@
-// Source file from the docmd project — https://github.com/docmd-io/docmd
-
-// Tags that don't have a closing tag (void elements)
-const VOID_TAGS = new Set([
-    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 
-    'link', 'meta', 'param', 'source', 'track', 'wbr', '!doctype'
-]);
-
-// Tags where whitespace should be preserved exactly
-const PRESERVE_TAGS = new Set(['pre', 'script', 'style', 'textarea']);
-
-function formatHtml(html) {
-    if (!html) return '';
-
-    const lines = html.split(/\r?\n/);
-    let formatted = [];
-    let indentLevel = 0;
-    const indentSize = 4; // 4 spaces per level
-    
-    // State tracking
-    let inPreserveBlock = false;
-    let preserveTagName = '';
-
-    for (let i = 0; i < lines.length; i++) {
-        let line = lines[i].trim(); // Start with a clean slate for this line
-
-        if (!line) continue; // Skip empty lines
-
-        // --- 1. Handle Preserve Blocks (pre/script/style) ---
-        if (inPreserveBlock) {
-            // Check if this line ends the block
-            if (line.toLowerCase().includes(`</${preserveTagName}>`)) {
-                inPreserveBlock = false;
-            } else {
-                // If inside preserve block, add raw line (no trim) from original
-                formatted.push(lines[i]); 
-                continue;
-            }
-        }
-
-        // Check if this line STARTS a preserve block
-        for (const tag of PRESERVE_TAGS) {
-            if (line.toLowerCase().startsWith(`<${tag}`)) {
-                inPreserveBlock = true;
-                preserveTagName = tag;
-                // If it's a one-liner (e.g. <script>...</script>), handle it immediately
-                if (line.toLowerCase().includes(`</${tag}>`)) {
-                    inPreserveBlock = false;
-                }
-                break;
-            }
-        }
-
-        // --- 2. Calculate Indentation ---
-        
-        // Detect closing tags at the start of the line (e.g. </div> or -->)
-        const isClosing = /^<\//.test(line) || /^-->/.test(line);
-        
-        if (isClosing && indentLevel > 0) {
-            indentLevel--;
-        }
-
-        // Apply indentation
-        const spaces = ' '.repeat(indentLevel * indentSize);
-        formatted.push(spaces + line);
-
-        // --- 3. Adjust Indent for Next Line ---
-        
-        // Detect opening tags
-        // Logic: Starts with <, not </, not <!, not void tag, and not self-closing />
-        const isOpening = /^<[\w]+/.test(line) 
-            && !/^<\//.test(line) 
-            && !/\/>$/.test(line); // Ends with />
-
-        if (isOpening) {
-            // Extract tag name to check if it's void
-            const tagNameMatch = line.match(/^<([\w-]+)/);
-            if (tagNameMatch) {
-                const tagName = tagNameMatch[1].toLowerCase();
-                if (!VOID_TAGS.has(tagName)) {
-                    // Check if it's a one-liner: <div>Content</div>
-                    // Logic: count opening vs closing tags in this line
-                    // Simple heuristic: if line contains </tagName>, it's closed
-                    const hasClosingPair = new RegExp(`</${tagName}>`, 'i').test(line);
-                    
-                    if (!hasClosingPair) {
-                        indentLevel++;
-                    }
-                }
-            }
-        }
-    }
-
-    return formatted.join('\n');
-}
-
-module.exports = { formatHtml };