@docmd/parser 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 docmd (docmd.io)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,10 @@
+# @docmd/parser
+
+The pure logic engine for **docmd**.
+
+This package handles:
+- Markdown parsing (via `markdown-it`)
+- Custom features (Callouts, Tabs, Steps, Changelogs)
+- HTML template rendering (EJS)
+
+It is environment-agnostic (Node.js & Browser).

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@docmd/parser",
+  "version": "0.4.0",
+  "description": "Pure Markdown parsing engine for docmd",
+  "main": "src/index.js",
+  "dependencies": {
+    "ejs": "^3.1.10",
+    "gray-matter": "^4.0.3",
+    "highlight.js": "^11.9.0",
+    "lucide-static": "^0.370.0",
+    "markdown-it": "^14.1.0",
+    "markdown-it-attrs": "^4.1.6",
+    "markdown-it-footnote": "^4.0.0",
+    "markdown-it-task-lists": "^2.1.1",
+    "markdown-it-abbr": "^2.0.0",
+    "markdown-it-deflist": "^3.0.0",
+    "markdown-it-container": "^4.0.0"
+  },
+  "license": "MIT"
+}

package/src/features/basics.js

@@ -0,0 +1,38 @@
+module.exports = {
+  name: 'basics',
+  setup(md) {
+    // 1. Custom Image Renderer
+    const defaultImageRenderer = md.renderer.rules.image || function(tokens, idx, options, env, self) {
+      return self.renderToken(tokens, idx, options);
+    };
+
+    md.renderer.rules.image = function(tokens, idx, options, env, self) {
+      const renderedImage = defaultImageRenderer(tokens, idx, options, env, self);
+      const nextToken = tokens[idx + 1];
+      
+      // Look ahead for attributes syntax { .class } immediately after image
+      if (nextToken && nextToken.type === 'attrs_block') {
+        // markdown-it-attrs usually handles this, but if we need specific logic for 
+        // aligning images that don't use standard attributes, we do it here.
+        // For standard docmd usage, markdown-it-attrs handles {.align-center}, etc.
+        // But we explicitly support 'attributes merging' if needed.
+        
+        // Actually, for docmd v0.3 compatibility, we rely on `markdown-it-attrs` 
+        // to handle classes like .align-right, .size-small.
+        // So we might strictly NOT need a custom renderer unless we are doing 
+        // something proprietary.
+        
+        // However, we DO need the TABLE wrapper.
+      }
+      return renderedImage;
+    };
+
+    // 2. Table Wrapper (Horizontal Scroll)
+    md.renderer.rules.table_open = (tokens, idx, options, env, self) => {
+      return '<div class="table-wrapper">' + self.renderToken(tokens, idx, options);
+    };
+    md.renderer.rules.table_close = (tokens, idx, options, env, self) => {
+      return self.renderToken(tokens, idx, options) + '</div>';
+    };
+  }
+};

package/src/features/changelog.js

@@ -0,0 +1,115 @@
+// Helper: Smart Dedent (reused, ideally move to utils, but inline is fine for isolation)
+function smartDedent(str) {
+  const lines = str.split('\n');
+  let minIndent = Infinity;
+  lines.forEach(line => {
+    if (line.trim().length === 0) return;
+    const match = line.match(/^ */);
+    if (match[0].length < minIndent) minIndent = match[0].length;
+  });
+  if (minIndent === Infinity) return str;
+  return lines.map(line => line.trim().length ? line.substring(minIndent) : '').join('\n');
+}
+
+function changelogRule(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 !== '::: changelog') return false;
+  if (silent) return true;
+
+  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();
+    
+    // Simple fence check
+    if (/^(\s{0,3})(~{3,}|`{3,})/.test(nextContent)) inFence = !inFence;
+
+    if (!inFence) {
+        if (nextContent.startsWith(':::')) {
+          if (nextContent.match(/^:::\s*changelog/)) depth++;
+          else if (nextContent === ':::') {
+            depth--;
+            if (depth === 0) { found = true; break; }
+          }
+        }
+    }
+  }
+  
+  if (!found) return false;
+
+  // Extract content block
+  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 "== Date" entries
+  const lines = content.split('\n');
+  const entries = [];
+  let currentEntry = null;
+  let currentContentLines = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i];
+    const trimmedLine = rawLine.trim();
+    const markerMatch = trimmedLine.match(/^==\s+(.+)$/);
+
+    if (markerMatch) {
+      if (currentEntry) {
+        currentEntry.content = smartDedent(currentContentLines.join('\n'));
+        entries.push(currentEntry);
+      }
+      currentEntry = { meta: markerMatch[1], content: '' };
+      currentContentLines = [];
+    } else if (currentEntry) {
+      currentContentLines.push(rawLine);
+    }
+  }
+  if (currentEntry) {
+    currentEntry.content = smartDedent(currentContentLines.join('\n'));
+    entries.push(currentEntry);
+  }
+
+  state.push('changelog_open', 'div', 1);
+
+  entries.forEach(entry => {
+    // We render HTML blocks directly for the timeline structure
+    const entryOpen = state.push('html_block', '', 0);
+    entryOpen.content = `<div class="changelog-entry">
+      <div class="changelog-meta"><span class="changelog-date">${entry.meta}</span></div>
+      <div class="changelog-body">`;
+
+    // Recurse render the markdown inside the entry
+    entryOpen.content += state.md.render(entry.content, state.env);
+    
+    const entryClose = state.push('html_block', '', 0);
+    entryClose.content = `</div></div>`;
+  });
+
+  state.push('changelog_close', 'div', -1);
+  state.line = nextLine + 1;
+  return true;
+}
+
+module.exports = {
+  name: 'changelog',
+  setup(md) {
+    // Register Rule
+    md.block.ruler.before('fence', 'changelog_timeline', changelogRule, { alt: ['paragraph', 'reference', 'blockquote', 'list'] });
+    
+    // Register Container Renderer
+    md.renderer.rules.changelog_open = () => '<div class="docmd-container changelog-timeline">';
+    md.renderer.rules.changelog_close = () => '</div>';
+  }
+};

package/src/features/common-containers.js

@@ -0,0 +1,97 @@
+const container = require('markdown-it-container');
+
+module.exports = {
+  name: 'common-containers',
+  setup(md) {
+    // 1. Callout
+    md.use(container, 'callout', {
+      render: (tokens, idx) => {
+        if (tokens[idx].nesting === 1) {
+          const info = tokens[idx].info.trim();
+          const parts = info.split(' ');
+          const type = parts[1] || 'info'; 
+          const title = parts.slice(2).join(' ');
+          return `<div class="docmd-container callout callout-${type}">${title ? `<div class="callout-title">${title}</div>` : ''}<div class="callout-content">\n`;
+        }
+        return '</div></div>\n';
+      }
+    });
+
+    // 2. Card
+    md.use(container, 'card', {
+      render: (tokens, idx) => {
+        if (tokens[idx].nesting === 1) {
+          const title = tokens[idx].info.replace('card', '').trim();
+          return `<div class="docmd-container card">${title ? `<div class="card-title">${title}</div>` : ''}<div class="card-content">\n`;
+        }
+        return '</div></div>\n';
+      }
+    });
+
+    // 3. Collapsible
+    md.use(container, 'collapsible', {
+      render: (tokens, idx) => {
+        if (tokens[idx].nesting === 1) {
+          const info = tokens[idx].info.replace('collapsible', '').trim();
+          // Check for "open" keyword
+          const isOpen = info.startsWith('open ') || info === 'open';
+          const title = isOpen ? info.replace('open', '').trim() : info;
+          const displayTitle = title || 'Click to expand';
+          
+          return `<details class="docmd-container collapsible" ${isOpen ? 'open' : ''}>
+            <summary class="collapsible-summary">
+                <span class="collapsible-title">${displayTitle}</span>
+                <span class="collapsible-arrow"><svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"></polyline></svg></span>
+            </summary>
+            <div class="collapsible-content">\n`;
+        }
+        return '</div></details>\n';
+      }
+    });
+
+    // 4. Button (Note: Buttons are often block-level if using :::, or inline if different syntax)
+    md.use(container, 'button', {
+      render: (tokens, idx) => {
+        if (tokens[idx].nesting === 1) {
+            const info = tokens[idx].info.trim().substring(6).trim(); // Remove "button"
+            
+            // Default vars
+            let text = 'Button';
+            let url = '#';
+            let style = '';
+            
+            // Helper to check if string looks like a URL
+            const isUrl = (s) => s.startsWith('http') || s.startsWith('/') || s.startsWith('./') || s.startsWith('#');
+            
+            const parts = info.split(/\s+/);
+            
+            // Logic: Scan parts to find the URL. Everything before is Text. Everything after is Color/Style.
+            const urlIndex = parts.findIndex(p => isUrl(p));
+            
+            if (urlIndex > -1) {
+                url = parts[urlIndex];
+                text = parts.slice(0, urlIndex).join(' ').replace(/_/g, ' '); // Allow underscores for spaces if needed
+                
+                // Check for color after URL
+                if (parts[urlIndex + 1] && parts[urlIndex + 1].startsWith('color:')) {
+                    const color = parts[urlIndex + 1].split(':')[1];
+                    style = ` style="background-color: ${color}; border-color: ${color}; color: #fff;"`;
+                }
+            } else {
+                // No URL found, assume first part is text
+                if (parts.length > 0) text = parts.join(' ');
+            }
+
+            // Handle External Link
+            let targetAttr = '';
+            if (url.startsWith('http')) {
+                targetAttr = ' target="_blank" rel="noopener noreferrer"';
+            }
+            
+            return `<a href="${url}" class="docmd-button"${style}${targetAttr}>${text}`;
+        }
+        return '</a>\n';
+      }
+    });
+  }
+};

package/src/features/index.js

@@ -0,0 +1,15 @@
+const common = require('./common-containers');
+const tabs = require('./tabs');
+const steps = require('./steps');
+const changelog = require('./changelog');
+const basics = require('./basics');
+
+const FEATURES = [basics, common, tabs, steps, changelog];
+
+function registerFeatures(md) {
+  FEATURES.forEach(feature => {
+    if (feature.setup) feature.setup(md);
+  });
+}
+
+module.exports = { registerFeatures };

package/src/features/steps.js

@@ -0,0 +1,79 @@
+function stepsRule(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;
+  
+    // ... (Same seeking logic as tabs, abbreviated for brevity) ...
+    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 (/^(\s{0,3})(~{3,}|`{3,})/.test(nextContent)) inFence = !inFence;
+      if (!inFence && nextContent === ':::') {
+        depth--;
+        if (depth === 0) { found = true; break; }
+      }
+    }
+    
+    if (!found) return false;
+  
+    const openToken = state.push('steps_open', 'div', 1);
+    openToken.info = '';
+    
+    const oldParentType = state.parentType;
+    const oldLineMax = state.lineMax;
+    state.parentType = 'container';
+    state.lineMax = nextLine;
+    
+    state.md.block.tokenize(state, startLine + 1, nextLine);
+    
+    const closeToken = state.push('steps_close', 'div', -1);
+    
+    state.parentType = oldParentType;
+    state.lineMax = oldLineMax;
+    state.line = nextLine + 1;
+    return true;
+}
+
+module.exports = {
+  name: 'steps',
+  setup(md) {
+    md.block.ruler.before('fence', 'steps_container', stepsRule, { alt: ['paragraph', 'reference', 'blockquote', 'list'] });
+
+    // Custom List Renderer for Steps
+    md.renderer.rules.steps_open = () => '<div class="docmd-container steps steps-reset">';
+    md.renderer.rules.steps_close = () => '</div>';
+
+    // Hook into list rendering to add classes when inside steps
+    md.renderer.rules.ordered_list_open = function(tokens, idx, options, env, self) {
+        let isInSteps = false;
+        // Check tokens backward to see if we are inside a steps container
+        for (let i = idx - 1; i >= 0; i--) {
+            if (tokens[i].type === 'steps_open') { isInSteps = true; break; }
+            if (tokens[i].type === 'steps_close') break;
+        }
+        if (isInSteps) {
+            const start = tokens[idx].attrGet('start');
+            return start ? `<ol class="steps-list" start="${start}">` : '<ol class="steps-list">';
+        }
+        return self.renderToken(tokens, idx, options);
+    };
+
+    md.renderer.rules.list_item_open = function(tokens, idx, options, env, self) {
+        let isInSteps = false;
+        for (let i = idx - 1; i >= 0; i--) {
+            if (tokens[i].type === 'steps_open') { isInSteps = true; break; }
+            if (tokens[i].type === 'steps_close') break;
+        }
+        if (isInSteps) return '<li class="step-item">';
+        return '<li>';
+    };
+  }
+};

package/src/features/tabs.js

@@ -0,0 +1,144 @@
+// Helper for "Smart Dedent"
+function smartDedent(str) {
+  const lines = str.split('\n');
+  let minIndent = Infinity;
+  lines.forEach(line => {
+    if (line.trim().length === 0) return;
+    const match = line.match(/^ */);
+    if (match[0].length < minIndent) minIndent = match[0].length;
+  });
+  if (minIndent === Infinity) return str;
+  return lines.map(line => {
+    if (line.trim().length === 0) return '';
+    const dedented = line.substring(minIndent);
+    // Fix Code Fences that were indented
+    if (/^\s{4,}(`{3,}|~{3,})/.test(dedented)) return dedented.trimStart();
+    return dedented;
+  }).join('\n');
+}
+
+// Helper to identify fences
+function isFenceLine(line) {
+  return /^(\s{0,3})(~{3,}|`{3,})/.test(line);
+}
+
+// The Parsing Rule
+function tabsRule(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 !== '::: tabs') return false;
+  if (silent) return true;
+
+  let nextLine = startLine;
+  let found = false;
+  let depth = 1;
+  let inFence = false;
+
+  // Find closing :::
+  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 (isFenceLine(nextContent)) inFence = !inFence;
+
+    if (!inFence) {
+        if (nextContent.startsWith(':::')) {
+          if (nextContent.match(/^:::\s*tabs/)) depth++;
+          else if (nextContent === ':::') {
+            depth--;
+            if (depth === 0) { found = true; break; }
+          }
+        }
+    }
+  }
+  if (!found) return false;
+
+  // Extract content
+  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 "== tab" lines
+  const lines = content.split('\n');
+  const tabs = [];
+  let currentTab = null;
+  let currentContentLines = [];
+  
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i]; 
+    const trimmedLine = rawLine.trim();
+    const tabMatch = trimmedLine.match(/^==\s*tab\s+(?:"([^"]+)"|(\S+))$/);
+    
+    if (tabMatch) {
+      if (currentTab) {
+        currentTab.content = smartDedent(currentContentLines.join('\n'));
+        tabs.push(currentTab);
+      }
+      const title = tabMatch[1] || tabMatch[2];
+      currentTab = { title: title, content: '' };
+      currentContentLines = [];
+    } else if (currentTab) {
+      currentContentLines.push(rawLine); 
+    }
+  }
+  if (currentTab) {
+    currentTab.content = smartDedent(currentContentLines.join('\n'));
+    tabs.push(currentTab);
+  }
+
+  // Generate Tokens
+  const openToken = state.push('tabs_open', 'div', 1);
+  openToken.attrs = [['class', 'docmd-tabs']];
+  
+  const navToken = state.push('tabs_nav_open', 'div', 1);
+  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);
+  
+  const contentToken = state.push('tabs_content_open', 'div', 1);
+  tabs.forEach((tab, index) => {
+    const paneToken = state.push('tab_pane_open', 'div', 1);
+    paneToken.attrs = [['class', `docmd-tab-pane ${index === 0 ? 'active' : ''}`]];
+    
+    if (tab.content) {
+        // Recurse parsing inside tabs
+        const renderedContent = state.md.render(tab.content, state.env);
+        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;
+}
+
+module.exports = {
+  name: 'tabs',
+  setup(md) {
+    // Register Rule
+    md.block.ruler.before('fence', 'enhanced_tabs', tabsRule, { alt: ['paragraph', 'reference', 'blockquote', 'list'] });
+
+    // Register Renderers
+    md.renderer.rules.tabs_nav_open = () => '<div class="docmd-tabs-nav">';
+    md.renderer.rules.tabs_nav_close = () => '</div>';
+    md.renderer.rules.tabs_nav_item = (tokens, idx) => `<div class="${tokens[idx].attrs[0][1]}">${tokens[idx].content}</div>`;
+    md.renderer.rules.tabs_content_open = () => '<div class="docmd-tabs-content">';
+    md.renderer.rules.tabs_content_close = () => '</div>';
+    md.renderer.rules.tab_pane_open = (tokens, idx) => `<div class="${tokens[idx].attrs[0][1]}">`;
+    md.renderer.rules.tab_pane_close = () => '</div>';
+    md.renderer.rules.tabs_close = () => '</div>';
+  }
+};

package/src/html-renderer.js

@@ -0,0 +1,51 @@
+const ejs = require('ejs');
+const { renderIcon } = require('./utils/icon-renderer');
+
+/**
+ * Renders an EJS template string with provided data.
+ * NOTE: The 'templateString' must be read by the CLI and passed here.
+ */
+function renderTemplate(templateString, data, options = {}) {
+  // Inject core helpers into every template
+  const fullData = {
+    ...data,
+    renderIcon,
+    // Helper to fix links relative to root
+    fixLink: (url) => fixHtmlLinks(url, data.relativePathToRoot, data.isOfflineMode, data.config?.base)
+  };
+
+  try {
+    return ejs.render(templateString, fullData, options);
+  } catch (e) {
+    throw new Error(`EJS Render Error: ${e.message}`);
+  }
+}
+
+function fixHtmlLinks(url, root = './', isOffline = false, base = '/') {
+  if (!url || url.startsWith('http') || url.startsWith('#') || url.startsWith('mailto:')) return url;
+
+  let final = url;
+  
+  // Strip base if present
+  if (base !== '/' && url.startsWith(base)) {
+    final = '/' + url.substring(base.length);
+  }
+
+  // Make relative
+  if (final.startsWith('/')) {
+    final = root + final.substring(1);
+  }
+
+  // Offline adjustments
+  if (isOffline) {
+    if (!final.includes('.') && !final.endsWith('/')) final += '/index.html';
+    else if (final.endsWith('/')) final += 'index.html';
+  } else {
+    // Clean URLs
+    if (final.endsWith('/index.html')) final = final.substring(0, final.length - 10);
+  }
+
+  return final;
+}
+
+module.exports = { renderTemplate };

package/src/index.js

@@ -0,0 +1,15 @@
+const { createMarkdownProcessor, processContent } = require('./markdown-processor');
+const { renderTemplate } = require('./html-renderer');
+const { renderIcon } = require('./utils/icon-renderer');
+const { validateConfig } = require('./utils/validator');
+
+module.exports = {
+  // Logic
+  createMarkdownProcessor,
+  processContent,
+  renderTemplate,
+  validateConfig,
+  
+  // Utils
+  renderIcon
+};

package/src/markdown-processor.js

@@ -0,0 +1,149 @@
+const MarkdownIt = require('markdown-it');
+const matter = require('gray-matter');
+const hljs = require('highlight.js');
+
+// Standard Plugins
+const attrs = require('markdown-it-attrs');
+const footnote = require('markdown-it-footnote');
+const taskLists = require('markdown-it-task-lists');
+const abbr = require('markdown-it-abbr');
+const deflist = require('markdown-it-deflist');
+
+// The Feature Registry
+const { registerFeatures } = require('./features');
+
+// Custom Heading ID Logic (Internal helper)
+const headingIdPlugin = (md) => {
+  const originalHeadingOpen = md.renderer.rules.heading_open || function(tokens, idx, options, env, self) {
+    return self.renderToken(tokens, idx, options);
+  };
+
+  md.renderer.rules.heading_open = function(tokens, idx, options, env, self) {
+    const token = tokens[idx];
+    const existingId = token.attrGet('id');
+
+    if (!existingId) {
+      const contentToken = tokens[idx + 1];
+      if (contentToken && contentToken.type === 'inline' && contentToken.content) {
+        const headingText = contentToken.content;
+        const id = headingText
+          .toLowerCase()
+          .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);
+  };
+};
+
+function createMarkdownProcessor(config = {}, pluginsCallback) {
+  const mdOptions = {
+    html: true,
+    linkify: true,
+    typographer: true,
+    breaks: true,
+  };
+
+  // Syntax Highlighting
+  const highlightFn = (str, lang) => {
+    if (lang === 'mermaid') {
+      return `<pre class="mermaid">${new MarkdownIt().utils.escapeHtml(str)}</pre>`;
+    }
+    if (lang && hljs.getLanguage(lang)) {
+      try {
+        const highlighted = hljs.highlight(str, { language: lang, ignoreIllegals: true }).value;
+        return `<pre class="hljs"><code>${highlighted}</code></pre>`;
+      } catch (e) { /* ignore */ }
+    }
+    return `<pre class="hljs"><code>${new MarkdownIt().utils.escapeHtml(str)}</code></pre>`;
+  };
+
+  mdOptions.highlight = config.theme?.codeHighlight !== false ? highlightFn : (str, lang) => {
+    if (lang === 'mermaid') return `<pre class="mermaid">${new MarkdownIt().utils.escapeHtml(str)}</pre>`;
+    return `<pre><code>${new MarkdownIt().utils.escapeHtml(str)}</code></pre>`;
+  };
+
+  const md = new MarkdownIt(mdOptions);
+
+  // 1. Core Plugins
+  md.use(attrs, { leftDelimiter: '{', rightDelimiter: '}' });
+  md.use(footnote);
+  md.use(taskLists);
+  md.use(abbr);
+  md.use(deflist);
+  md.use(headingIdPlugin);
+
+  // 2. Register Built-in Features (Callouts, Tabs, Steps, etc.)
+  registerFeatures(md);
+
+  // 3. External Plugins Hook
+  if (typeof pluginsCallback === 'function') {
+    pluginsCallback(md);
+  }
+
+  return md;
+}
+
+function stripHtml(html) {
+  if (!html) return '';
+  return html.replace(/<[^>]*>?/gm, '');
+}
+
+function extractHeadings(html) {
+  const headings = [];
+  const regex = /<h([1-6])[^>]*?id="([^"]*)"[^>]*?>([\s\S]*?)<\/h\1>/g;
+  let match;
+  while ((match = regex.exec(html)) !== null) {
+    headings.push({
+      level: parseInt(match[1], 10),
+      id: match[2],
+      text: match[3].replace(/<\/?[^>]+(>|$)/g, '').trim()
+    });
+  }
+  return headings;
+}
+
+function processContent(rawString, mdInstance, config) {
+  let frontmatter, markdownContent;
+
+  try {
+    const parsed = matter(rawString);
+    frontmatter = parsed.data;
+    markdownContent = parsed.content;
+  } catch (e) {
+    console.error('Error parsing frontmatter:', e.message);
+    return null;
+  }
+
+  if (!frontmatter.title && config.autoTitleFromH1 !== false) {
+    const h1Match = markdownContent.match(/^#\s+(.*)/m);
+    if (h1Match) frontmatter.title = h1Match[1].trim();
+  }
+
+  let htmlContent, headings;
+  if (frontmatter.noStyle === true) {
+    htmlContent = markdownContent;
+    headings = [];
+  } else {
+    htmlContent = mdInstance.render(markdownContent);
+    headings = extractHeadings(htmlContent);
+  }
+
+  let searchData = null;
+  if (!frontmatter.noindex) {
+    searchData = {
+      title: frontmatter.title || 'Untitled',
+      content: stripHtml(htmlContent).slice(0, 5000),
+      headings: headings.map(h => h.text)
+    };
+  }
+
+  return { frontmatter, htmlContent, headings, searchData };
+}
+
+module.exports = { createMarkdownProcessor, processContent };

package/src/utils/icon-renderer.js

@@ -0,0 +1,37 @@
+const lucideStatic = require('lucide-static');
+
+// Convert kebab-case to PascalCase (e.g., arrow-right -> ArrowRight)
+function kebabToPascal(str) {
+  return str.split('-').map(p => p.charAt(0).toUpperCase() + p.slice(1)).join('');
+}
+
+const exceptions = {
+  'arrow-up-right-square': 'ExternalLink',
+  'file-cog': 'Settings',
+  'cloud-upload': 'UploadCloud'
+};
+
+function renderIcon(name, options = {}) {
+  if (!name) return '';
+  
+  const key = exceptions[name] || kebabToPascal(name);
+  const svgData = lucideStatic[key];
+
+  if (!svgData) return ''; // Fail silently or warn via callback
+
+  // Inject attributes into the raw SVG string
+  const attrs = [
+    `class="lucide-icon icon-${name} ${options.class || ''}"`,
+    `width="${options.width || '1em'}"`,
+    `height="${options.height || '1em'}"`,
+    `stroke="${options.stroke || 'currentColor'}"`,
+    `stroke-width="${options.strokeWidth || 2}"`,
+    'fill="none"',
+    'stroke-linecap="round"',
+    'stroke-linejoin="round"'
+  ].join(' ');
+
+  return svgData.replace('<svg', `<svg ${attrs}`);
+}
+
+module.exports = { renderIcon };

package/src/utils/navigation-helper.js

@@ -0,0 +1,56 @@
+/**
+ * Normalizes paths to a "canonical" form for comparison.
+ */
+function getCanonicalPath(p) {
+  if (!p) return '';
+  if (p.startsWith('http')) return p;
+
+  // 1. Remove ./ and leading /
+  let path = p.replace(/^\.?\//, '');
+
+  // 2. Remove file extension
+  path = path.replace(/(\.html|\.md)$/, '');
+
+  // 3. Remove index suffix
+  if (path.endsWith('index')) {
+    path = path.slice(0, -5);
+  }
+
+  // 4. Remove trailing slash
+  if (path.endsWith('/')) {
+    path = path.slice(0, -1);
+  }
+
+  // 5. Ensure root is empty string or consistent slash
+  return path === '' ? '/' : '/' + path;
+}
+
+function findPageNeighbors(navItems, currentPagePath) {
+  const flatNavigation = [];
+  const currentCanonical = getCanonicalPath(currentPagePath);
+
+  function recurse(items) {
+    if (!items) return;
+    for (const item of items) {
+      if (item.path && !item.external) {
+        flatNavigation.push({
+          title: item.title,
+          path: item.path,
+          url: item.path, // We will fix this URL in build.js context if needed
+          canonical: getCanonicalPath(item.path)
+        });
+      }
+      if (item.children) recurse(item.children);
+    }
+  }
+  recurse(navItems);
+
+  const index = flatNavigation.findIndex(item => item.canonical === currentCanonical);
+
+  return {
+    prevPage: index > 0 ? flatNavigation[index - 1] : null,
+    nextPage: index < flatNavigation.length - 1 ? flatNavigation[index + 1] : null
+  };
+}
+
+module.exports = { findPageNeighbors };

package/src/utils/validator.js

@@ -0,0 +1,81 @@
+const chalk = require('chalk');
+
+// Known configuration keys for typo detection
+const KNOWN_KEYS = [
+  'siteTitle', 'siteUrl', 'srcDir', 'outputDir', 'logo', 
+  'sidebar', 'theme', 'customJs', 'autoTitleFromH1', 
+  'copyCode', 'plugins', 'navigation', 'footer', 'sponsor', 'favicon',
+  'search', 'minify', 'editLink', 'pageNavigation'
+];
+
+// Common typos mapping
+const TYPO_MAPPING = {
+  'site_title': 'siteTitle',
+  'sitetitle': 'siteTitle',
+  'baseUrl': 'siteUrl',
+  'source': 'srcDir',
+  'out': 'outputDir',
+  'customCSS': 'theme.customCss',
+  'customcss': 'theme.customCss',
+  'customJS': 'customJs',
+  'customjs': 'customJs',
+  'nav': 'navigation',
+  'menu': 'navigation'
+};
+
+function validateConfig(config) {
+  const errors = [];
+  const warnings = [];
+
+  // 1. Required Fields
+  if (!config.siteTitle) {
+    errors.push('Missing required property: "siteTitle"');
+  }
+
+  // 2. Type Checking
+  if (config.navigation && !Array.isArray(config.navigation)) {
+    errors.push('"navigation" must be an Array');
+  }
+
+  if (config.customJs && !Array.isArray(config.customJs)) {
+    errors.push('"customJs" must be an Array of strings');
+  }
+
+  if (config.theme) {
+    if (config.theme.customCss && !Array.isArray(config.theme.customCss)) {
+      errors.push('"theme.customCss" must be an Array of strings');
+    }
+  }
+
+  // 3. Typos and Unknown Keys (Top Level)
+  Object.keys(config).forEach(key => {
+    if (TYPO_MAPPING[key]) {
+      warnings.push(`Found unknown property "${key}". Did you mean "${TYPO_MAPPING[key]}"?`);
+    }
+  });
+
+  // 4. Theme specific typos
+  if (config.theme) {
+    if (config.theme.customCSS) {
+      warnings.push('Found "theme.customCSS". Did you mean "theme.customCss"?');
+    }
+  }
+
+  // Output results
+  if (warnings.length > 0) {
+    console.log(chalk.yellow('\n⚠️  Configuration Warnings:'));
+    warnings.forEach(w => console.log(chalk.yellow(`   - ${w}`)));
+  }
+
+  if (errors.length > 0) {
+    console.log(chalk.red('\n❌ Configuration Errors:'));
+    errors.forEach(e => console.log(chalk.red(`   - ${e}`)));
+    console.log('');
+    // We throw to stop the build process in the CLI
+    throw new Error('Invalid configuration file.');
+  }
+
+  return true;
+}
+
+module.exports = { validateConfig };