Skip to content

docmd@0.4.8 🚀 (Stability, UX & SPA Update)

Choose a tag to compare

View all tags
@mgks mgks released this 26 Feb 20:25
· 171 commits to main since this release
0.4.8
0c1d5ea

docmd logo

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.

image

✨ 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

Assets 2
Loading