@mgks/docmd 0.3.4 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mgks/docmd",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Generate beautiful, lightweight static documentation sites directly from your Markdown files. Zero clutter, just content.",
   "main": "src/index.js",
   "exports": {
@@ -15,6 +15,7 @@
   "scripts": {
     "start": "node ./bin/docmd.js dev",
     "build": "node ./bin/docmd.js build",
+    "live": "node scripts/build-live.js && npx serve dist",
     "postinstall": "node ./bin/postinstall.js",
     "lint": "eslint .",
     "format": "prettier --write .",
@@ -22,32 +23,32 @@
   },
   "dependencies": {
     "chalk": "^4.1.2",
-    "chokidar": "^4.0.3",
+    "chokidar": "^5.0.0",
     "clean-css": "^5.3.3",
-    "commander": "^14.0.0",
-    "ejs": "^3.1.9",
-    "esbuild": "^0.27.0",
-    "express": "^5.1.0",
-    "fs-extra": "^11.2.0",
+    "commander": "^14.0.2",
+    "ejs": "^3.1.10",
+    "esbuild": "^0.27.2",
+    "express": "^5.2.1",
+    "fs-extra": "^11.3.3",
     "gray-matter": "^4.0.3",
     "highlight.js": "^11.11.1",
-    "lucide-static": "^0.535.0",
+    "lucide-static": "^0.562.0",
+    "markdown-it": "^14.1.0",
     "markdown-it-abbr": "^2.0.0",
     "markdown-it-attrs": "^4.3.1",
     "markdown-it-container": "^4.0.0",
     "markdown-it-deflist": "^3.0.0",
     "markdown-it-footnote": "^4.0.0",
     "markdown-it-task-lists": "^2.1.1",
-    "mermaid": "^11.12.1",
+    "mermaid": "^11.12.2",
     "minisearch": "^7.2.0",
     "striptags": "^3.2.0",
-    "ws": "^8.17.0"
+    "ws": "^8.18.3"
   },
   "devDependencies": {
-    "eslint": "^9.32.0",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-node": "^11.1.0",
-    "prettier": "^3.2.5"
+    "buffer": "^6.0.3",
+    "eslint": "^9.39.2",
+    "prettier": "^3.7.4"
   },
   "directories": {
     "doc": "docs"
@@ -77,4 +78,4 @@
   "homepage": "https://github.com/mgks/docmd#readme",
   "funding": "https://github.com/sponsors/mgks",
   "license": "MIT"
-}
+}

package/scripts/build-live.js

@@ -0,0 +1,157 @@
+const fs = require('fs-extra');
+const path = require('path');
+const esbuild = require('esbuild');
+
+async function build() {
+    console.log('📦 Building @docmd/live core...');
+
+    const SRC_DIR = path.join(__dirname, '../src');
+    const LIVE_SRC_DIR = path.join(SRC_DIR, 'live');
+    const DIST_DIR = path.join(__dirname, '../dist');
+
+    // Ensure dist exists and is empty
+    fs.emptyDirSync(DIST_DIR);
+
+    // 1. Read Templates
+    const templatesDir = path.join(SRC_DIR, 'templates');
+    const files = fs.readdirSync(templatesDir);
+    const templates = {};
+
+    for (const file of files) {
+        if (file.endsWith('.ejs')) {
+            templates[file] = fs.readFileSync(path.join(templatesDir, file), 'utf8');
+        }
+    }
+
+    // 2. Generate templates.js
+    const templatesJsPath = path.join(LIVE_SRC_DIR, 'templates.js');
+    const templatesContent = `
+const templates = ${JSON.stringify(templates, null, 2)};
+if (typeof globalThis !== 'undefined') globalThis.__DOCMD_TEMPLATES__ = templates;
+module.exports = templates;
+`;
+    fs.writeFileSync(templatesJsPath, templatesContent);
+
+    // 3. Generate Shim for Buffer
+    const shimPath = path.join(LIVE_SRC_DIR, 'shims.js');
+    fs.writeFileSync(shimPath, `import { Buffer } from 'buffer'; globalThis.Buffer = Buffer;`);
+
+    // 4. Bundle JS
+    try {
+        await esbuild.build({
+            entryPoints: [path.join(LIVE_SRC_DIR, 'core.js')],
+            bundle: true,
+            outfile: path.join(DIST_DIR, 'docmd-live.js'),
+            platform: 'browser',
+            format: 'iife',
+            globalName: 'docmd',
+            minify: true,
+            define: { 'process.env.NODE_ENV': '"production"' },
+            inject: [shimPath],
+            plugins: [
+                {
+                    name: 'node-deps-shim',
+                    setup(build) {
+                        build.onResolve({ filter: /^path$/ }, args => ({ path: args.path, namespace: 'path-shim' }));
+                        build.onLoad({ filter: /.*/, namespace: 'path-shim' }, () => ({
+                            contents: `
+                                module.exports = {
+                                    join: (...args) => args.filter(Boolean).join('/'),
+                                    resolve: (...args) => '/' + args.filter(Boolean).join('/'),
+                                    basename: (p) => p ? p.split(/[\\\\/]/).pop() : '',
+                                    dirname: (p) => p ? p.split(/[\\\\/]/).slice(0, -1).join('/') || '.' : '.',
+                                    extname: (p) => {
+                                        if (!p) return '';
+                                        const parts = p.split('.');
+                                        return parts.length > 1 ? '.' + parts.pop() : '';
+                                    },
+                                    isAbsolute: (p) => p.startsWith('/'),
+                                    normalize: (p) => p,
+                                    sep: '/'
+                                };
+                            `,
+                            loader: 'js'
+                        }));
+
+                        build.onResolve({ filter: /^(fs|fs-extra)$/ }, args => ({ path: args.path, namespace: 'fs-shim' }));
+                        build.onLoad({ filter: /.*/, namespace: 'fs-shim' }, () => ({
+                            contents: `
+                                module.exports = {
+                                    existsSync: (p) => {
+                                        if (!globalThis.__DOCMD_TEMPLATES__) return false;
+                                        let name = p.split(/[\\\\/]/).pop(); 
+                                        if (globalThis.__DOCMD_TEMPLATES__[name]) return true;
+                                        if (!name.endsWith('.ejs') && globalThis.__DOCMD_TEMPLATES__[name + '.ejs']) return true;
+                                        return false;
+                                    },
+                                    readFileSync: (p) => {
+                                        if (!globalThis.__DOCMD_TEMPLATES__) return '';
+                                        let name = p.split(/[\\\\/]/).pop();
+                                        if (globalThis.__DOCMD_TEMPLATES__[name]) return globalThis.__DOCMD_TEMPLATES__[name];
+                                        if (!name.endsWith('.ejs')) name += '.ejs';
+                                        return globalThis.__DOCMD_TEMPLATES__[name] || '';
+                                    },
+                                    statSync: () => ({ isFile: () => true, isDirectory: () => false }),
+                                    constants: { F_OK: 0, R_OK: 4 }
+                                };
+                            `, 
+                            loader: 'js'
+                        }));
+                    }
+                }
+            ]
+        });
+        console.log('✅ Bundled JS to dist/docmd-live.js');
+
+        // 5. Copy Assets
+        console.log('📂 Copying assets...');
+        await fs.copy(path.join(SRC_DIR, 'assets'), path.join(DIST_DIR, 'assets'));
+        
+        // 5.5 Bundle Third-Party Libraries (The FIX)
+        // We need to manually copy these from node_modules because they aren't in src/assets
+        const copyLibrary = async (packageName, fileToBundle, destFileName) => {
+            try {
+                // Try to resolve the package path
+                let srcPath;
+                try {
+                    srcPath = require.resolve(`${packageName}/${fileToBundle}`);
+                } catch (e) {
+                    // Fallback search if require.resolve fails
+                    const mainPath = require.resolve(packageName);
+                    let currentDir = path.dirname(mainPath);
+                    for (let i = 0; i < 5; i++) {
+                        if (fs.existsSync(path.join(currentDir, 'package.json'))) break;
+                        currentDir = path.dirname(currentDir);
+                    }
+                    srcPath = path.join(currentDir, fileToBundle);
+                }
+
+                if (srcPath && fs.existsSync(srcPath)) {
+                    const destPath = path.join(DIST_DIR, 'assets/js', destFileName);
+                    await fs.ensureDir(path.dirname(destPath));
+                    await fs.copy(srcPath, destPath);
+                    console.log(`   └─ Copied ${packageName} -> assets/js/${destFileName}`);
+                } else {
+                    console.warn(`⚠️ Could not locate ${fileToBundle} in ${packageName}`);
+                }
+            } catch (e) {
+                console.warn(`⚠️ Failed to bundle ${packageName}: ${e.message}`);
+            }
+        };
+
+        await copyLibrary('minisearch', 'dist/umd/index.js', 'minisearch.js');
+        await copyLibrary('mermaid', 'dist/mermaid.min.js', 'mermaid.min.js');
+        console.log('✅ Assets & Libraries copied.');
+
+        // 6. Copy Demo HTML
+        await fs.copy(path.join(LIVE_SRC_DIR, 'index.html'), path.join(DIST_DIR, 'index.html'));
+        await fs.copy(path.join(LIVE_SRC_DIR, 'live.css'), path.join(DIST_DIR, 'live.css'));
+        console.log('✅ Demo HTML copied.');
+
+    } catch (e) {
+        console.error('❌ Build failed:', e);
+        process.exit(1);
+    }
+}
+
+build();

package/scripts/test-live.js

@@ -0,0 +1,54 @@
+const fs = require('fs');
+const path = require('path');
+const vm = require('vm');
+
+const bundlePath = path.join(__dirname, '../dist/docmd-live.js');
+
+if (!fs.existsSync(bundlePath)) {
+    console.error('❌ Bundle not found. Run "npm run live" or "node scripts/build-live.js" first.');
+    process.exit(1);
+}
+
+const bundleCode = fs.readFileSync(bundlePath, 'utf8');
+
+const sandbox = { 
+    console: console,
+    setTimeout: setTimeout,
+    clearTimeout: clearTimeout,
+    window: {},
+    self: {},
+    globalThis: {}
+};
+sandbox.window = sandbox;
+sandbox.self = sandbox;
+sandbox.globalThis = sandbox;
+
+vm.createContext(sandbox);
+
+console.log('🧪 Testing Live Bundle...');
+
+try {
+    vm.runInContext(bundleCode, sandbox);
+    
+    if (!sandbox.docmd) {
+        throw new Error('docmd global not found in bundle');
+    }
+
+    const markdown = '# Hello Live\nThis is a test.';
+    const config = { siteTitle: 'Live Test' };
+    
+    console.log('Compiling markdown...');
+    const result = sandbox.docmd.compile(markdown, config);
+    
+    if (result.includes('<h1>Hello Live</h1>') && result.includes('Live Test')) {
+        console.log('✅ Bundle works! Output contains expected HTML.');
+    } else {
+        console.error('❌ Bundle produced unexpected output.');
+        console.log('Output snippet:', result.substring(0, 200));
+        process.exit(1);
+    }
+
+} catch (e) {
+    console.error('❌ Test failed:', e);
+    process.exit(1);
+}

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

@@ -9,124 +9,82 @@ function initializeCollapsibleNav() {
   const nav = document.querySelector('.sidebar-nav');
   if (!nav) return;
 
-  let navStates = {};
-  try {
-    // Use sessionStorage to remember state only for the current session
-    navStates = JSON.parse(sessionStorage.getItem('docmd-nav-states')) || {};
-  } catch (e) { /* silent fail */ }
+  // We NO LONGER set initial state here. 
+  // The HTML arrives with style="display: block" and aria-expanded="true" 
+  // pre-rendered by the build process. This eliminates the FOUC/Jitter.
 
   nav.querySelectorAll('li.collapsible').forEach(item => {
-    const navId = item.dataset.navId;
     const anchor = item.querySelector('a');
     const submenu = item.querySelector('.submenu');
 
-    if (!navId || !anchor || !submenu) return;
-
-    const isParentActive = item.classList.contains('active-parent');
-    // Default to expanded if it's a parent of the active page, otherwise check stored state.
-    let isExpanded = isParentActive || (navStates[navId] === true);
-
-    const toggleSubmenu = (expand) => {
-      item.setAttribute('aria-expanded', expand);
-      submenu.style.display = expand ? 'block' : 'none';
-      navStates[navId] = expand;
-      sessionStorage.setItem('docmd-nav-states', JSON.stringify(navStates));
-    };
-
-    // Set initial state on page load
-    toggleSubmenu(isExpanded);
+    if (!anchor || !submenu) return;
 
+    // Only handle CLICK events to toggle state
     anchor.addEventListener('click', (e) => {
-      const currentExpanded = item.getAttribute('aria-expanded') === 'true';
       const href = anchor.getAttribute('href');
-      const isPlaceholder = !href || href === '#' || href === '';
-
-      if (!currentExpanded) {
-        toggleSubmenu(true);
-      } else if (isPlaceholder || e.target.closest('.collapse-icon')) {
-        toggleSubmenu(false);
-      }
+      // If it's a placeholder link (#) OR the user clicked the arrow icon
+      const isToggleAction = !href || href === '#' || e.target.closest('.collapse-icon');
 
-      if (isPlaceholder || e.target.closest('.collapse-icon')) {
+      if (isToggleAction) {
         e.preventDefault();
+        
+        // Toggle Logic
+        const isExpanded = item.getAttribute('aria-expanded') === 'true';
+        const newState = !isExpanded;
+        
+        item.setAttribute('aria-expanded', newState);
+        submenu.style.display = newState ? 'block' : 'none';
       }
     });
-
-    /*    anchor.addEventListener('click', (e) => {
-          // If the click target is the icon, ALWAYS prevent navigation and toggle.
-          if (e.target.closest('.collapse-icon')) {
-            e.preventDefault();
-            toggleSubmenu(item.getAttribute('aria-expanded') !== 'true');
-          } 
-          // If the link is just a placeholder, also prevent navigation and toggle.
-          else if (anchor.getAttribute('href') === '#') {
-            e.preventDefault();
-            toggleSubmenu(item.getAttribute('aria-expanded') !== 'true');
-          }
-          // Otherwise, let the click proceed to navigate to the link.
-        });*/
   });
 }
 
 // --- Mobile Menu Logic ---
 function initializeMobileMenus() {
-  // 1. Sidebar Toggle
   const sidebarBtn = document.querySelector('.sidebar-menu-button');
   const sidebar = document.querySelector('.sidebar');
   
   if (sidebarBtn && sidebar) {
     sidebarBtn.addEventListener('click', (e) => {
-      e.stopPropagation(); // Prevent bubbling
+      e.stopPropagation();
       sidebar.classList.toggle('mobile-expanded');
     });
   }
 
-  // 2. TOC Toggle
   const tocBtn = document.querySelector('.toc-menu-button');
   const tocContainer = document.querySelector('.toc-container');
-  // Also allow clicking the title text to toggle
   const tocTitle = document.querySelector('.toc-title');
 
   const toggleToc = (e) => {
-    // Only engage on mobile view (check if button is visible)
     if (window.getComputedStyle(tocBtn).display === 'none') return;
-    
     e.stopPropagation();
     tocContainer.classList.toggle('mobile-expanded');
   };
 
   if (tocBtn && tocContainer) {
     tocBtn.addEventListener('click', toggleToc);
-    if (tocTitle) {
-      tocTitle.addEventListener('click', toggleToc);
-    }
+    if (tocTitle) tocTitle.addEventListener('click', toggleToc);
   }
 }
 
-// --- Sidebar Scroll Preservation ---
+// --- Sidebar Scroll Preservation (Instant Center) ---
 function initializeSidebarScroll() {
   const sidebar = document.querySelector('.sidebar');
   if (!sidebar) return;
 
-  setTimeout(() => {
-    const activeElement = sidebar.querySelector('a.active') || sidebar.querySelector('.active-parent > a');
+  // Wait for the layout to be stable
+  requestAnimationFrame(() => {
+    // Find the active link
+    const activeElement = sidebar.querySelector('a.active');
 
     if (activeElement) {
-      const sidebarRect = sidebar.getBoundingClientRect();
-      const elementRect = activeElement.getBoundingClientRect();
-
-      // Check if the element's top or bottom is outside the sidebar's visible area
-      const isNotInView = elementRect.top < sidebarRect.top || elementRect.bottom > sidebarRect.bottom;
-
-      if (isNotInView) {
-        activeElement.scrollIntoView({
-          behavior: 'auto',
-          block: 'center',
-          inline: 'nearest'
-        });
-      }
+      activeElement.scrollIntoView({
+        behavior: 'auto', // INSTANT jump (prevents scrolling animation jitter)
+        block: 'center',  // Center it vertically in the sidebar
+        inline: 'nearest'
+      });
     }
-  }, 10);
+  });
 }
 
 // --- Theme Toggle Logic ---
@@ -138,7 +96,6 @@ function setupThemeToggleListener() {
     document.body.setAttribute('data-theme', theme);
     localStorage.setItem('docmd-theme', theme);
 
-    // Switch highlight.js theme
     const highlightThemeLink = document.getElementById('highlight-theme');
     if (highlightThemeLink) {
       const newHref = highlightThemeLink.getAttribute('data-base-href') + `docmd-highlight-${theme}.css`;
@@ -146,7 +103,6 @@ function setupThemeToggleListener() {
     }
   }
 
-  // Add click listener to the toggle button
   if (themeToggleButton) {
     themeToggleButton.addEventListener('click', () => {
       const currentTheme = document.documentElement.getAttribute('data-theme');
@@ -161,22 +117,15 @@ function initializeSidebarToggle() {
   const toggleButton = document.getElementById('sidebar-toggle-button');
   const body = document.body;
 
-  if (!body.classList.contains('sidebar-collapsible') || !toggleButton) {
-    return;
-  }
+  if (!body.classList.contains('sidebar-collapsible') || !toggleButton) return;
 
   const defaultConfigCollapsed = body.dataset.defaultCollapsed === 'true';
   let isCollapsed = localStorage.getItem('docmd-sidebar-collapsed');
 
-  if (isCollapsed === null) {
-    isCollapsed = defaultConfigCollapsed;
-  } else {
-    isCollapsed = isCollapsed === 'true';
-  }
+  if (isCollapsed === null) isCollapsed = defaultConfigCollapsed;
+  else isCollapsed = isCollapsed === 'true';
 
-  if (isCollapsed) {
-    body.classList.add('sidebar-collapsed');
-  }
+  if (isCollapsed) body.classList.add('sidebar-collapsed');
 
   toggleButton.addEventListener('click', () => {
     body.classList.toggle('sidebar-collapsed');
@@ -197,9 +146,7 @@ function initializeTabs() {
         tabPanes.forEach(pane => pane.classList.remove('active'));
 
         navItem.classList.add('active');
-        if (tabPanes[index]) {
-          tabPanes[index].classList.add('active');
-        }
+        if (tabPanes[index]) tabPanes[index].classList.add('active');
       });
     });
   });
@@ -207,9 +154,7 @@ function initializeTabs() {
 
 // --- Copy Code Button Logic ---
 function initializeCopyCodeButtons() {
-  if (document.body.dataset.copyCodeEnabled !== 'true') {
-    return;
-  }
+  if (document.body.dataset.copyCodeEnabled !== 'true') return;
 
   const copyIconSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg>`;
   const checkIconSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-check"><polyline points="20 6 9 17 4 12"></polyline></svg>`;
@@ -218,18 +163,12 @@ function initializeCopyCodeButtons() {
     const codeElement = preElement.querySelector('code');
     if (!codeElement) return;
 
-    // Create a wrapper div around the pre element
     const wrapper = document.createElement('div');
     wrapper.style.position = 'relative';
     wrapper.style.display = 'block';
 
-    // Insert the wrapper before the pre element
     preElement.parentNode.insertBefore(wrapper, preElement);
-
-    // Move the pre element into the wrapper
     wrapper.appendChild(preElement);
-
-    // Remove the relative positioning from pre since wrapper handles it
     preElement.style.position = 'static';
 
     const copyButton = document.createElement('button');
@@ -260,21 +199,11 @@ function syncBodyTheme() {
   if (currentTheme && document.body) {
     document.body.setAttribute('data-theme', currentTheme);
   }
-
-  // Also ensure highlight CSS matches the current theme
-  const highlightThemeLink = document.getElementById('highlight-theme');
-  if (highlightThemeLink && currentTheme) {
-    const baseHref = highlightThemeLink.getAttribute('data-base-href');
-    if (baseHref) {
-      const newHref = baseHref + `docmd-highlight-${currentTheme}.css`;
-      highlightThemeLink.setAttribute('href', newHref);
-    }
-  }
 }
 
 // --- Main Execution ---
 document.addEventListener('DOMContentLoaded', () => {
-  syncBodyTheme(); // Sync body theme with html theme
+  syncBodyTheme();
   setupThemeToggleListener();
   initializeSidebarToggle();
   initializeTabs();

package/src/commands/build.js

@@ -66,6 +66,7 @@ async function buildSite(configPath, options = { isDev: false, preserve: false,
   const md = createMarkdownItInstance(config);
   const shouldMinify = !options.isDev && config.minify !== false;
   const searchIndexData = [];
+  const isOfflineMode = options.offline === true;
 
   if (!await fs.pathExists(SRC_DIR)) {
     throw new Error(`Source directory not found: ${formatPathForDisplay(SRC_DIR, CWD)}`);
@@ -287,10 +288,11 @@ async function buildSite(configPath, options = { isDev: false, preserve: false,
       const currentPagePathForNav = normalizedPath;
 
       const navigationHtml = await generateNavigationHtml(
-        config.navigation,
-        currentPagePathForNav,
-        relativePathToRoot,
-        config
+          config.navigation,
+          normalizedPath,
+          relativePathToRoot,
+          config,
+          isOfflineMode
       );
 
       // Find previous and next pages for navigation
@@ -320,9 +322,10 @@ async function buildSite(configPath, options = { isDev: false, preserve: false,
         nextPage: nextPage,
         currentPagePath: normalizedPath,
         headings: headings || [],
+        isOfflineMode,
       };
 
-      const pageHtml = await generateHtmlPage(pageDataForTemplate);
+      const pageHtml = await generateHtmlPage(pageDataForTemplate, isOfflineMode);
 
       await fs.ensureDir(path.dirname(finalOutputHtmlPath));
       await fs.writeFile(finalOutputHtmlPath, pageHtml);
@@ -369,7 +372,9 @@ async function buildSite(configPath, options = { isDev: false, preserve: false,
 
   // Generate search index if enabled
   if (config.search !== false) {
-    console.log('🔍 Generating search index...');
+    if (!options.isDev) {
+      console.log('🔍 Generating search index...');
+    }
 
     // Create MiniSearch instance
     const miniSearch = new MiniSearch({