This release introduces the Menubar component, significantly hardens the Zero-Config engine, and transforms the developer experience with a robust dev server and a built-in _playground.

✨ Highlights

Menubar

The focus of this release is the new Menubar, providing a top-level navigation layer for your documentation.

• Versatile Positioning: Can be placed at the very top of the viewport (fixed) or inside the header slot (sticky).
• Rich Components: Supports branding (logo + title), link items, and nested dropdowns for complex navigation needs.
• Responsive Design: Automatically collapses on mobile devices to maintain a clean reading experience.

Built-in _playground

We've added a dedicated _playground package within the repository. Developers can now test core engine changes, UI components, and parser rules in real-time without leaving the codebase.

Smarter Options Menu + New Positioning

The Options Menu is now more flexible than ever.

• Menubar Integration: A new menubar position allows the options menu to sit perfectly on the right side of your navigation bar.
• Intelligent Fallbacks: If you configure the options menu to a position that is currently disabled (like header or menubar), docmd now automatically falls back to sidebar-top to ensure your users never lose access to essential utilities.

📝 Complete Changelog

✨ Dev-UX & Dev Server Hardening

• Auto Port Selection: docmd dev now automatically finds and binds to the next available port if 3000 is in use, eliminating interactive prompts and speeding up launch times.
• Log Refinement: We've eliminated repeating build logs and improved visual highlights, providing clearer details about the build process and PWA asset generation.
• Robust Rebuilds: Fixed issues where pnpm dev would fail during active development. The internal watcher is now smarter about tracking core utility changes.
• Nested Design: Improved the visual and structural handling of nested containers (e.g., Tabs inside Callouts).

📦 Zero-Config Evolution

• Selective Activation: Zero-Config is now more surgical about where it activates, implementing "silent kills" to avoid triggering in invalid or non-project directories.
• Stability: Multiple edge cases in directory analysis have been resolved, making the zero-config start much more reliable across different OS environments.

🐛 Bug Fixes

• Indentation Fixes: Reset indentation in common-containers to prevent code block parsing by @svallory in #75
• Container Heading Logic: Fixed a design flaw where headings inside containers (Tabs, Cards, etc.) were receiving permalinks and appearing in the Table of Contents. They are now correctly excluded to keep your TOC focused on main page sections.
• Sidebar-Top Fallback: Fixed an issue where the Options Menu would remain invisible if its primary target container was disabled.

📥 Upgrade

npm install -g @docmd/core

New Contributors

• @svallory made their first contribution in #75

Full Changelog: 0.5.1...0.5.2

This release focuses on refining the developer experience, enhancing our AI-First approach, and introducing powerful new plugins for the ecosystem.

✨ Highlights

Progressive Web App (PWA) Plugin

You can now instantly turn your documentation site into an installable application with a zero-config, intelligent Service Worker and offline availability! The @docmd/plugin-pwa is shipped natively.

• Zero Config: Add pwa: {} to your config plugins. It automatically generates manifest.webmanifest, service-worker.js, and injects all mobile meta tags.
• Smart Caching: Uses a network-first with cache fallback strategy — fresh content is always preferred but the offline shell activates seamlessly when there's no network.
• Automatic Cache Busting: Every docmd build generates a uniquely fingerprinted Service Worker (docmd-cache-<timestamp>). Old caches are purged automatically on activation — no user action needed.
• 5-Minute Background Updates: A silent polling interval checks the server for a new Service Worker every 5 minutes, so redeployed content reaches users without requiring a manual refresh.
• Ghost Worker Cleanup: If you remove the PWA plugin from your config, docmd automatically detects the missing manifest on the client and unregisters any lingering Service Workers without user action.
• Customizable: Override theme colors, background colors, and PWA icons via pwa.logo or a manual pwa.icons array.

Read Complete Documentation on PWA Plugin.

AI First Full Context Generation

docmd 0.5.1 is officially the easiest static site generator for LLMs to consume natively.

• llms-full.txt Generation: Beyond the structural llms.txt, the LLM Plugin now concatenates the raw, unmodified markdown content of your entire documentation repository into a single unified llms-full.txt file. Give it directly to ChatGPT or Claude to immediately inject your entire codebase context in one shot.

Deep Section Linking in Search

• The Search Plugin has been overhauled to provide hyper-granular results. Instead of just taking users to matching pages, search results are now broken down by Header sections (<h3>, <h4> etc) and seamlessly deeply link users straight to the exact paragraph the keyword originates from.

Block AI Bots with SEO Plugin

• SEO AI Bot Blacklist: Added native seo.aiBots configuration support which automatically blankets your meta headers with <meta name="GPTBot" content="noindex"> tags across 12 prominent model scrapers for projects that need privacy.
• Meta Description: If you omit a frontmatter description from a Markdown file, the SEO plugin automatically constructs a rich excerpt fallback from the first 150 characters of the content securely.

// Blocking Bots Globally
plugins: {
    seo: {
      aiBots: false // This will block all common AI bots
    }
}

// Page Specific Overrides
---
title: My Private Guide
seo:
  aiBots: false # Only block bots on this specific page
---

Bots in current block list - GPTBot, ChatGPT-User, Google-Extended, CCBot, anthropic-ai, Omgilibot, Omgili, FacebookBot, Diffbot, Bytespider, ImagesiftBot, and cohere-ai.

📝 Complete Changelog

✨ Zero-Config Hardening

• Smarter Path Resolving: Zero-Config mode now automatically detects docs, src/docs, and content base folders natively.
• Metadata Fallbacks: Zero-Config will automatically try to ingest the root package.json to assign the proper name and description to the documentation site natively.
• Failsafe Executions: Dev Loops are completely eradicated. If you run docmd dev in a folder that has zero Markdown files anywhere to be found, it now cleanly aborts with a useful error message instead of spamming watcher loops indefinitely.

🐛 Bug Fixes

• SPA Query Selector: Fixed a crash in docmd-main.js which caused navigation loops when users manually clicked Anchor tags with IDs starting with numeric values.

📥 Upgrade

npm install -g @docmd/core

Full Changelog: 0.5.0...0.5.1

v0.5.0 marks a massive evolution for docmd. We are introducing Enterprise-Grade Versioning, a magical Zero-Config Mode, and a modernized configuration schema, all while maintaining our promise of zero bloat. This release transforms docmd from a simple documentation generator into a robust platform capable of handling complex, multi-versioned projects with ease.

✨ Highlights

Documentation Versioning Support

You asked, we delivered. You can now maintain multiple versions of your documentation (e.g., v1.0, v2.0) simultaneously. docmd handles the routing, asset separation, and UI automatically.

• Sticky Switching: Changing versions keeps you on the same page (e.g., switching v1 -> v2 while on /installation takes you to /v2/installation).
• Smart Navigation: The sidebar automatically filters out links that don't exist in older versions.
• Per-Version Navigation: You can completely override the menu for specific versions.

versions: {
  current: 'v2', // Builds to root (/) for optimal SEO
  all:[
    { 
      id: 'v2', 
      dir: 'docs', 
      label: 'v2.x (Latest)' 
    },
    { 
      id: 'v1', 
      dir: 'docs-v1', 
      label: 'v1.x',

      // version specific navigation: not required (optional)
      // docmd is smart enough to auto-generate custom nav for your specific version based on available docs
      navigation: [
          { title: 'Legacy Guide', path: '/legacy-intro' }
      ]
    }
  ]
}

Zero-Config Mode (--zero-config)

Want to document a project instantly? You no longer need a config file.

Run docmd dev -z for dev server and docmd build -z for production in any folder.
Our new Auto-Router will:

• Scan your directory structure recursively.
• Extract H1 titles from every Markdown file.
• Build a deeply nested, collapsible sidebar.
• Launch the dev server instantly.
• Note: Zero-Config is still in beta and does not support versioning yet.

V3 Configuration Schema (Simpler Labels)

We have streamlined the configuration labels to align with modern standards (like Vite/VitePress). It is cleaner, shorter, and more intuitive.

Legacy v0.4 labels are still 100% supported, so no breaking changes!

Native 404s & SEO Redirects

docmd now behaves like a mature Static Site Generator (SSG) regarding SEO traffic.

• Custom 404: We generate a native 404.html that inherits your theme, sidebar, and layout.
• Redirects: Define old paths in your config, and we generate static HTML redirects to preserve your SEO ranking.

module.exports = defineConfig({
  redirects: { '/old-guide': '/new-guide' },
  notFound: { 
    title: 'Page Not Found', 
    content: 'Oops! This page has moved.' 
  }
});

Whitelabeling (Hide Branding)

For professional use cases, you can now easily toggle off the "Built with docmd" footer signature.

footer: {
  style: 'minimal',
  branding: false    // you can hide docmd signature now
}

📝 Complete Changelog

✨ Features & Enhancements:

• Core: Implemented Multi-Version Build Engine. It loops through configured versions and builds them into isolated sub-directories (/v1/, /v2/).
• Core: Added Auto-Router for Zero-Config mode. It performs AST-free scanning of headers to build navigation trees dynamically.
• Core: Introduced defineConfig helper for IDE autocomplete support.
• Config: Added V3 Schema (title, src, out, url) with internal normalization for backward compatibility.
• UI: Added Version Dropdown component with "Sticky Path" logic (preserves relative path when switching versions).
• UI: Major sidebar CSS overhaul. The navigation list now scrolls independently of the header/footer (Flexbox layout), eliminating double scrollbars.
• UI: Sidebar dropdowns now intelligently open upwards when placed at the bottom of the sidebar.
• Dev Server: Now serves the custom 404.html instead of a raw text error when a route is missing.

🐛 Bug Fixes:

• Search: Fixed search index 404s in versioned subfolders by implementing DOCMD_SITE_ROOT logic.
• Core: Fixed ReferenceError: options is not defined in config loader when using specific flags.
• UI: Fixed SPA Router duplicating relative paths (e.g., /v1/v1/page) by hard-reloading on version context switches.
• Live Editor: Fixed crash caused by missing isOfflineMode flag in the browser-side rendering engine.
• Build: Fixed EJS Render Error for 404 pages by passing correct template context.
• Failsafe: Upgraded test suite to brute-test Versioning, Zero-Config, and Redirect generation before every release.

📥 Upgrade

npm install -g @docmd/core

Full Changelog: 0.4.11...0.5.0

While v0.4.8 introduced the architecture for our Single Page Application (SPA) experience, v0.4.11 makes our 0ms latency claim a reality. By implementing predictive UI patterns, docmd is now officially faster than the time it takes for a user to click.

⚡ Lightning SPA: Predictive Prefetching

We have implemented Intent-based Prefetching. docmd now monitors user behavior; the moment a mouse hovers over a link, the engine begins downloading the page in the background.

• Perceived 0ms Latency: By the time the user actually clicks, the content is already in the memory cache, making the transition truly instantaneous.
• Data Efficient: The selective delay ensures we don't waste bandwidth on accidental mouse swipes, only fetching when intent is clear.

🐛 Bug Fixes

• Search Plugin: The search engine now calculates its index path using absolute URLs derived from the project root. This ensures that the search bar and results function flawlessly regardless of how deep you navigate into nested folders via the SPA. Fixed #63.
• Mermaid In-Memory Rendering: docmd now generates SVG diagrams in a background memory buffer. This allows Mermaid to calculate dimensions accurately even if the diagram is currently hidden inside a Tab or a Collapsible container. The diagram "snaps" into view the moment the container is opened.
• Performance: Optimized the SPA router to prevent unnecessary DOM destruction, preserving the scroll position and state of the sidebar more effectively.
• Sync: Bumped all internal workspace packages to maintain monorepo lockstep.

📥 Upgrade

npm install -g @docmd/core

Full Changelog: 0.4.10...0.4.11

Following our massive architectural overhaul in v0.4.8, we've spent this release hunting down edge cases, perfecting the Single Page Application (SPA) experience, and making our Markdown parser completely bulletproof.

🛠️ Bug Fixes & Improvements

SPA Router & Navigation:

• Fix: Eliminated the "layout dragging" jitter that occurred when navigating to or from pages with heavy elements (like Mermaid diagrams). The router now briefly locks the layout height during DOM swaps for a perfectly stable, native-feeling transition.
• Fix: Resolved 404 Not Found errors for Favicons and Theme CSS that occurred when the SPA navigated between different folder depths (e.g., from / to /content/syntax/).
• Fix: Relative internal Markdown links (e.g., [link](./file.md)) now resolve correctly. The parser now intelligently calculates depth traversal to account for docmd's "Clean URLs" folder structure. Fix #62.
• Fix: Hash anchors in internal links (e.g., [link](./file.md#section)) are now preserved correctly during the HTML build step.

Mermaid & Plugins:

• Fix: Fixed a critical Mermaid.js crash (Could not find a suitable point for the given distance) that occurred when diagrams were placed inside hidden containers like Tabs or Collapsibles. docmd now uses an advanced in-memory SVG rendering queue that safely waits for the container to become visible before drawing.

Parser & UI:

• Fix: Indented ::: button components inside nested containers (like Cards or Callouts) are no longer mistakenly parsed as <pre><code> blocks by standard Markdown rules.
• Fix: The "Edit this page" link in the footer now accurately points to the original .md source file path rather than the generated .html output path.

📥 Upgrade

npm install -g @docmd/core

Full Changelog: 0.4.9...0.4.10

v0.4.9 is a critical security and performance hotfix.

This release removes a vulnerable third-party dependency from the Live Editor and replaces it with a faster, native implementation.

🛡️ Security & Fixes

• Security: Removed the serve dependency from the @docmd/live package, resolving multiple high-severity security warnings (CVE-related ReDoS vulnerabilities in serve-handler and ajv).
• Performance: Replaced the third-party server with a lightweight, native Node.js HTTP server. The docmd live command is now faster to boot and significantly smaller to install.
• Maintenance: Bumped all workspace packages to ensure version consistency across the monorepo.

Recommended Action: All users should update to v0.4.9 to clear security audit warnings in their CI/CD pipelines.

📥 Upgrade

npm install -g @docmd/core

Full Changelog: 0.4.8...0.4.9

v0.4.8 is our biggest stability and UX update yet. We’ve completely overhauled the internal architecture to make docmd faster, smarter, and incredibly beautiful out-of-the-box. Frosted-glass headers, deep container nesting, and buttery-smooth page transitions, all while keeping the core footprint tiny.

✨ Highlights

1. The New V2 Layout Configuration

We've introduced a cleaner, more organized configuration structure. All UI elements (header, sidebar, options menu, footer) are now neatly grouped under a layout object.

NOTE: Your existing v0.4.7 config is 100% backward compatible! Our new internal schema adapter translates it on the fly.

Example of the new structure:

module.exports = {
  siteTitle: 'My Docs',
  
  layout: {
    spa: true, // Seamless page transitions
    header: { enabled: true },
    sidebar: { collapsible: true, defaultCollapsed: false },
    
    // Centralized options menu!
    optionsMenu: {
      position: 'header', // 'header', 'sidebar-top', 'sidebar-bottom'
      components: {
        search: true,
        themeSwitch: true,
        sponsor: 'https://github.com/sponsors/your-name'
      }
    },
    
    // The New "Complete" Footer
    footer: {
      style: 'complete', // 'minimal' or 'complete'
      description: 'The minimalist documentation generator.',
      copyright: '© 2026 My Project',
      columns: [
        {
          title: 'Resources',
          links:[
            { text: 'Getting Started', url: '/getting-started' },
            { text: 'API', url: '/api' }
          ]
        }
      ]
    }
  }
}

I will update the complete new config template in the documentation

2. Introducing SPA Router & Event Delegation

We completely rewrote the client-side JavaScript. Instead of attaching hundreds of event listeners, docmd now uses a single, highly-optimized Event Delegation model.

• Seamless Navigation: Clicking sidebar links instantly swaps content without reloading the page, without breaking <head> relative paths, and without throwing Favicon 404s.
• Failsafe Offline Mode: If you open the docs locally via file:///, the SPA intelligently disables itself to prevent browser CORS blocks.

3. The Migration Tool (docmd migrate)

Moved to the new V2 config structure? We built a tool to do it for you.
Run docmd migrate in your project root. It will:

• Backup your existing docmd.config.js.
• Intelligently map your old settings (search, theme, sponsor) to the new nested layout structure.
• Generate a clean, modern config file automatically.

4. Deep Container Nesting

Previously, nesting a ::: button inside a ::: card inside ::: tabs could confuse the Markdown parser into closing the wrong container. We wrote a custom depth-tracking parser. You can now infinitely nest components without breaking the layout.

5. Premium UI Overhaul

• Cross-Browser Perfection: Buttons, SVGs, and header elements are now strictly bound to rem and CSS variables. They look pixel-perfectly identical on Safari, Chrome, and Firefox.
• Heading Anchors: Hovering over any h2, h3, or h4 now reveals a beautiful, clickable permalink chain icon.
• Frosted Glass: The sticky top header now features a modern backdrop-filter: blur effect.
• Smart Scrollbars: Scrollbars are now theme-aware. In Chrome, they auto-hide until hovered. In Safari, they respect native OS dark/light color schemes natively.
• Themes Update: The default theme is now stable and nearing its final design stage. Other themes have received initial improvements but are not yet fully stable. They will continue to be refined over the next few releases.

📝 Complete Changelog

Features & Enhancements:

• Core: Added docmd migrate command.
• Failsafe: failsafe.js now includes a Virtual Machine (VM) runtime test to catch crashes before they happen.
• Config: Introduced nested layout schema with backward compatibility adapter.
• Config: Added layout.spa: true/false to easily toggle the SPA router.
• UI: Added multi-column complete footer option.
• UI: Added docmd-heading anchor links for H2, H3, and H4.
• UI: Unified optionsMenu for Search, Theme, and Sponsor buttons allowing easy repositioning.
• UX: Replaced jittery scrollIntoView in the Table of Contents with a smooth, targeted container scrollTo.
• UX: Dummy navigation links (paths like # or missing) now render as unclickable <span class="nav-category-label"> to prevent false active states.

Bug Fixes:

• Core: Fixed relative path duplication bug (content/content/syntax) during SPA navigation.
• Core: Dev server now correctly throws a 301 redirect to append trailing slashes on directories, mimicking production servers.
• Core: docmd init now generates the modern V2 configuration by default.
• Parser: Fixed greedy closing tags (:::) when nesting Cards, Callouts, and Collapsibles.
• Plugins: plugin-search completely decoupled from the layout template. The search modal is now self-injected by the plugin, reducing bundle size for users who disable it.
• Plugins: plugin-mermaid now does lazy rendering to prevent layout crashes when diagrams are placed inside hidden containers.
• Plugins: plugin-mermaid now seamlessly handles dark mode toggles without forcing a full page reload.
• Plugins: Fixed Monorepo plugin resolution fallback (Cannot find module @docmd/plugin-search).
• Security: Updated minimatch via overrides to patch a transitive vulnerability. Updated esbuild and lucide-static to latest.

📥 Upgrade

npm install -g @docmd/core

Full Changelog: 0.4.7...0.4.8

This release focuses on quality-of-life improvements for content authors and polishing the Live Editor experience.

✨ New Features

• GFM Emoji Support: You can now use GitHub-flavored emoji shortcodes in your markdown!
  • I :heart: documentation :rocket: → I ❤️ documentation 🚀
• Smart Link Rewriting: You can now link directly to .md files in your content. docmd will automatically convert paths like [Guide](guide.md) into clean HTML links (/guide/) during the build. This ensures links work in your code editor (VS Code) and your website.

🛠 Improvements & Fixes

• Parser Stability: Resolved a critical crash (plugin.apply is not a function) caused by ESM/CommonJS conflicts in the parser dependencies.
• Button Syntax: The default template now uses the modern, self-closing button syntax (::: button "Text" URL).
• Live Layout: Fixed iframe resizing issues in the Live Editor to ensure the preview pane fills the available space correctly.

📥 Upgrade

npm install -g @docmd/core

Full Changelog: 0.4.6...0.4.7

This release marks a major step forward for docmd as a developer-first tool, introducing native AI support and fixing long-standing parsing edge cases.

✨ New Features

• AI Context Plugin (llms.txt): Added @docmd/plugin-llms. It automatically generates an /llms.txt file (mapping to llmstxt.org) to help AI agents like ChatGPT, Claude, and Cursor understand your project context instantly. Resolved #37
• Live Editor Presets: Added a "Chips" toolbar to the Live Editor. Quickly load templates for Mermaid, Tabs, Steps, and Containers to see how docmd components look in real-time.

🐛 Critical Parser Fixes

• Tabs Indentation: Fixed #40. Code blocks nested inside Tabs now perfectly preserve their internal indentation. No more flattened code!
• Mermaid Live: Fixed a silent rendering failure in the Live Editor by inlining the Mermaid loader directly into the preview iframe.
• Container Nesting: Improved depth-tracking to allow infinite nesting of components (e.g., a Card inside a Step inside a Tab) without early closure.

🖥️ UX & Internal Improvements

• Overlay Scrollbars: Redesigned sidebar scrollbars to use an "overlay" style. This prevents layout shifts and content "jumping" when expanding large sub-menus.
• Asset Ordering: Refactored the build engine to ensure Plugin CSS/JS is injected after Core CSS, making custom overrides easier and more predictable.
• Persistent Highlight Themes: Fixed an issue where code blocks would flash or revert to Light mode on page reload while in Dark mode.

📥 Upgrade

npm install -g @docmd/core

Full Changelog: 0.4.5...0.4.6

This release brings stability improvements to the core parser and improves on WCAG standards.

✨ New Features

• Button Syntax: Upgraded the ::: button container syntax. It is now a self-closing block, supporting quoted text and mailto links.

  ::: button "Contact Support" mailto:support@example.com

• Base Path: We now support a base configuration option in docmd.config.js. Set base: '/project-name/'. When you write ![img](/assets/img.png), docmd automatically rewrites it to /project-name/assets/img.png during the build. (Feature #43)
• Keyboard Shortcuts: Still very early addition but we're adapting to more keyboard friendly UX with WCAG AA standards. Now users can skip sidebar/navigation completely and jump directly to the main-content with keyboard using hidden navigations.

🐛 Bug Fixes

• CSS Minification: Fixed an issue where plugin assets (like Mermaid styles) were not being minified during the build.
• Nested Containers: Resolved parsing logic where closing a nested container (e.g., a Card inside a Step) would break the parent container.
• Port Detection: Improved the docmd dev port check to avoid false positives and "EADDRINUSE" errors on restarts.
• Fixed many minor design inconsistencies and broken elements.

📥 Upgrade

npm install -g @docmd/core

Full Changelog: 0.4.4...0.4.5