docmd v0.8.1 introduces a pluggable engine architecture, major improvements to git indexing performance, and important fixes for SPA navigation.

✨ Highlights

Pluggable Engine Architecture (Preview)

docmd now supports a pluggable engine system. The new @docmd/engine-rust package provides a foundation for accelerated I/O operations, designed to work seamlessly with existing plugins.

{
  "engine": "rust"
}

The engine is optional — the default JavaScript engine handles all workloads. The Rust engine provides measurable gains for large repositories (1000+ files) where git indexing and batch file operations dominate build time.

Architecture highlights:

• Pluggable design: Engines are packages under @docmd/engine-*, following the same pattern as plugins
• Bundled pre-built binaries: All supported platform binaries are now delivered via a single centralised @docmd/engine-rust-binaries package
• Lazy loading: Native binaries are only loaded when the engine is explicitly selected
• Plugin-compatible: Plugins can leverage the engine API for accelerated I/O
• Automatic fallback: If the native binary isn’t available, the JS engine takes over transparently

Available engine packages:

Git Indexing: Persistent Disk Cache

The git plugin now persists indexing results to disk across builds. Previously, git metadata was re-indexed from scratch on every build — even when no files had changed. The new cache system:

• Routes cache storage cleanly to your operating system’s isolated temporary directory (os.tmpdir()), preventing top-level directory clutter.
• Secures cache retrieval persistently across directory renames or moves by generating a robust hash anchored to your repository’s Git tracking URL or unique OS inode identifiers.
• Supports configurable storage paths via the new tmp configuration parameter.
• Works with both engine paths (Rust and JS) and the execFile fallback.
• Provides ~45% faster warm builds on the official documentation site (886 pages).

Configurable tmp Directory

By default, docmd now routes internal state and build caches to your system’s isolated temporary folder to keep your project root clean. For environments that require persistent caching in specific locations (e.g., CI/CD pipelines with cache-key requirements), you can now configure the full storage path using the new tmp key:

{
  "src": ".",
  "out": "site",
  "tmp": ".docmd-cache"
}

This allows you to anchor the .docmd/ state folder to any directory, ensuring it can be easily cached and restored across build sessions.

JSON Configuration Standard

Starting with v0.8.0, docmd.config.json is the recommended configuration format. All v0.8 documentation has been updated to use JSON examples. The .js and .ts formats remain fully supported as fallbacks for dynamic configuration logic.

🐛 Bug Fixes

External Links in SPA Navigation

Fixed an issue where external links defined in navigation.json with external: true were incorrectly resolved as relative paths after navigating to another internal page via the SPA router. The links now correctly preserve their absolute URLs during client-side navigation.

Navigation External Link Shorthand

The external: prefix, previously available only in Markdown content, now works in navigation.json as a convenient shorthand:

[
  { "title": "GitHub", "path": "external:https://github.com/docmd-io/docmd" }
]

This is equivalent to:

[
  { "title": "GitHub", "path": "https://github.com/docmd-io/docmd", "external": true }
]

Git Cache Directory Stability & Relocation

Fixed a bug where the git plugin’s disk cache was written to shifting directories during workspace builds. The cache has been cleanly relocated out of the project root directory directly into os.tmpdir() using a persistent repository identifier, fully supporting the custom tmp override path parameter.

Engine Configuration Respected

The git plugin now respects the engine configuration key. Previously, it always attempted to load the Rust engine first regardless of configuration. Setting "engine": "js" now correctly forces the JavaScript engine.

📝 Complete Changelog

🚀 Engine & Architecture

• Pluggable Engine System: New Engine interface in @docmd/api for build acceleration
• JS Engine Package: Default engine extracted to @docmd/engine-js
• Rust Engine Ecosystem: Native Rust acceleration with centralised binary distribution via @docmd/engine-rust-binaries
• Engine Loader API: loadEngine() and registerEngine() for custom engine registration
• Engine Config Key: New engine key in docmd.config.json to select build engine
• Engine Prominence: Elevated top-level logging prominence for custom build engines inside TUI layouts

⚡ Performance

• Git Disk Cache: Engine-path results now persisted to disk for warm builds
• Persistent Identification: Dual-mode cache identification using Git remote URL hashing and OS inode fallback
• Configurable Storage: Added support for overriding cache destination via the tmp config parameter
• Config Resolvers: Added seamless detection support for standard JSON config files in workspace sub-project loops
• Disk Cache Pre-warming: Build pipeline reads disk cache before engine/subprocess calls

🐛 Bug Fixes

• SPA Router: External links in sidebar navigation now correctly preserved during client-side navigation
• Navigation Config: external: prefix now supported as shorthand in navigation.json
• Link Resolution: Fixed URL resolution edge case for protocol-relative URLs
• Git Plugin: Now respects the engine configuration key instead of always defaulting to Rust
• workspace Cache: Relocated state storage to deterministic temporary OS structures to prevent loss between loop boundaries