The docmd 0.8.0 release is a monumental architectural upgrade. We have moved from a single-threaded sequential engine to a native multi-threaded worker pool that processes pages in parallel. This release also introduces first-class Multi-Project support, allowing you to manage complex documentation ecosystems under a single domain with near-instant build times.

✨ Highlights

⚡ Parallel Build Engine

docmd now builds your documentation in parallel using a highly optimised WorkerPool. By offloading Markdown AST parsing and processor hooks into background threads, docmd fully utilises all available CPU cores. For large sites (1000+ pages), this results in up to 10x faster builds.

🏢 Multi-Project Support

You can now build multiple independent documentation projects into a single site. This is perfect for monorepos or large organisations that need to unify multiple documentation sources under one domain (e.g., docmd.io and docmd.io/search).

• Unified Output: Each project has its own config but shares a single output directory.
• Independent Context: Each sub-project maintains its own versioning, i18n, and plugin configurations.

🔌 Plugin Worker API

We have exposed the internal WorkerPool to the entire plugin ecosystem. Plugins can now offload computationally heavy tasks (like image processing, remote indexing, or data parsing) to background threads using the new ctx.runWorkerTask() API.

📜 Persistent Git Indexing

The Git plugin has been redesigned for speed. It now features a Persistent Disk Cache and parallel I/O processing.

• Massive Speedup: Indexing 800+ pages now takes ~3.5s instead of ~18s on subsequent builds.
• Smart Pruning: The cache automatically manages entries for deleted or renamed files.

🏠 SEO-Friendly README Routes

docmd now automatically treats README.md as a directory index, ensuring that links like [Guide](./guide/README.md) resolve correctly to /guide/.

• Intelligent Fallback: index.md is always prioritized, with README.md serving as a fallback if no index is present.
• Clean URLs: Automatically strips README and index from URLs for a professional look.

⚙️ Modern Configuration

You can now write your configuration in TypeScript or JSON.

• TypeScript Support: Use docmd.config.ts with full autocompletion and type safety via defineConfig.
• JSON Support: Lightweight docmd.config.json for environments where JavaScript execution is restricted.

🧜 Better Mermaid Diagrams

The Mermaid plugin now features an improved UI for large diagrams.

• Refined Controls: Zoom and pan controls have been moved to the bottom-left to prevent overlapping with content.
• Fullscreen Experience: Fullscreen mode now includes full access to all navigation and zoom controls.

📝 Complete Changelog

🚀 Engine & Architecture

• Worker-Parser Pipeline: The core markdown processor is now re-hydrated dynamically inside background threads. Files are read concurrently and farmed out to the workers in batches.
• AST Caching Engine: An MD5-based caching layer intercepts unmodified files. If a file’s raw content hash hasn’t changed since the previous pass, the AST parsing is skipped entirely.
• Persistent Dev Workers: During docmd dev, the worker pool remains persistent across file saves. This eliminates the 200-500ms thread-startup latency commonly associated with Node.js workers, resulting in near-instant incremental rebuilds.
• Worker CPU Throttling: The thread pool calculates the exact number of threads based on system architecture, reserving one CPU core to prevent I/O starvation and OS lockups.
• WorkerPool MaxListeners Guard: The EventEmitter listener cap is dynamically scaled (poolSize * 4 + 50) to prevent spurious Node.js warnings on high-throughput builds with 900+ pages.

🔌 Plugin System

• onBeforeBuild Lifecycle Hook: A new dedicated “Data Indexing” phase allows plugins to fetch heavy data (like Git logs or remote APIs) and display a progress bar before HTML generation begins. This guarantees the core render loop remains purely synchronous and lightning-fast.
• runWorkerTask API: Exposed directly on the plugin contexts (onBeforeBuild, onBeforeRender, onPostBuild, actions, events) for generic script execution in the background.
• Git Plugin Persistent Cache: The Git plugin now runs in the new onBeforeBuild hook and utilises a robust persistent disk cache (.docmd/cache/git-history.json). This completely eliminates redundant git log shell subprocesses on subsequent builds, dropping the build time of large repositories (800+ pages) from ~18 seconds down to just ~3.5 seconds.
• Git Plugin Parallel I/O: Git metadata syncing now processes pages in parallel batches (concurrency of 10). Since git log is async I/O, this yields ~5-10x faster cold-start indexing on large sites compared to sequential processing.
• Git Cache Auto-Pruning: The disk cache automatically removes stale entries for deleted or renamed files during each save, preventing unbounded cache growth over time.
• Search Index Worker Offload: When a WorkerPool is available, the CPU-intensive MiniSearch tokenization and indexing is offloaded to a worker thread via runWorkerTask, keeping the main thread free for other post-build tasks.
• Decoupled API Imports: Plugins can now import fsUtils, WorkerPool, and getGitRoot directly from @docmd/utils.

🖥️ Terminal Interface

• TUI Progress Bars: Exposing the @docmd/tui engine directly to plugin contexts. The Git and Search plugins now render highly stable, in-place progress bars during their indexing phases to clearly separate data-fetching latency from raw build speed.

⚙️ Infrastructure & Tooling

• Centralised Git Context: Internal Git branch detection and repository root parsing (getGitRoot) have been extracted into the safe utilities boundary.
• Modern Config Candidates: Added docmd.config.ts and docmd.config.json to the default configuration search path.
• JSON-serialisable Configs: Continued transition towards zero-config architecture by ensuring the resolved config object is fully JSON-serialisable.

⚠️ Breaking Changes

• Utility Imports: Custom plugins relying on core relative imports must migrate to @docmd/utils.
• Serialisable Hooks: markdownSetup hooks must be serialisable for cross-thread instantiation.

Migration Guide

Upgrade by running npm install docmd@latest. Most sites will see immediate performance gains without any configuration changes.

See Installation for a full walkthrough.