v0.9.9 - Variables & Personalisation Engine, Versioned Search Paths, Template Resolvers & SPA Routing

Highlights

docmd v0.9.9 introduces a comprehensive Variables & Personalisation Engine spanning static build-time template interpolation and dynamic client-side reactivity, resolves search index loading across versioned directory mounts, hardens template layout slot resolution and monorepo peer dependency isolation, improves Single-Page Application (SPA) logo navigation routing, and incorporates automated context synthesis optimisations for the AI assistant plugin.

• Unified Variables & Personalisation Engine (@docmd/core, @docmd/parser, @docmd/ui): Enables clean {{ variable }} interpolation across documentation files, site banners, and footer copyright strings. Provides zero-configuration built-in variables (docmd.version, docmd.buildYear, docmd.gitCommit, docmd.gitBranch, page.slug, page.title), configuration variable trees with fallback defaults ({{ var || 'default' }}), and syntax escaping via \{{ ... }}.
• Universal Headless Client Runtime (@docmd/ui): Ships docmd-runtime.js across all layout templates (default, summer). Exposes window.docmd with reactive DOM rehydration (<span data-docmd-var="...">), live code snippet updates for personalized API keys, and cross-frame postMessage synchronisation for embedded developer portals.
• Versioned Search Path Resolution (@docmd/plugin-search): Fixed search index loading on sites mounted under versioned base paths like /vX.Y.Z/ (PR #266 by @Goldloli, closing #262). Prefers the authoritative build-time window.DOCMD_SITE_ROOT to prevent version segment stripping on mono-version deployments.
• SPA Logo Routing & Navigation Fixes (@docmd/ui): Hardened logo link handling so custom external URLs (e.g. corporate homepages) and root-relative workspace links navigate seamlessly without unwanted client-side SPA routing intercepts.
• Template Layout Slot Resolution & Dependency Hardening (@docmd/api, @docmd/ui): Eliminated false-positive layout slot warnings for themes like summer. Gated monorepo source detection within pre-flight runtime dependency checks and isolated peer dependency installs to prevent package pruning in npm v7+ workspaces.
• AI Assistant Context & Tool Optimisations (@docmd/plugin-ai): Streamlined documentation tool calling with Snippet-First Synthesis, ensuring AI responses deliver precise documentation passages and code examples with minimal roundtrips.
• Dependency Maintenance & Upgrades: Updated npm dependency group across workspace packages (PR #265) and bumped docker/login-action (PR #264).

Unified Variables & Dynamic Personalisation Engine (@docmd/core, @docmd/parser, @docmd/ui)

v0.9.9 introduces a first-class Variables Engine that addresses documentation maintenance at both compile-time and run-time:

• Build-Time Static Interpolation: Replaces {{ variable }} tokens directly during static site generation with zero client-side JavaScript overhead. Supports fallback values using the || operator (e.g. {{ env.PORT || "8080" }}) and literal syntax escaping with \{{ ... }}.
• Built-in System & Repository Variables:
  • docmd.version (DOCMD_VERSION): The active compiler release version.
  • docmd.buildYear (BUILD_YEAR): 4-digit calendar year of the build.
  • docmd.buildDate / docmd.buildTime: ISO 8601 build timestamps.
  • docmd.gitCommit / docmd.gitBranch: Git SHA and branch metadata extracted dynamically via repository discovery.
  • site.title / site.base: Global workspace configuration properties.
  • page.title / page.slug / page.path: Document context properties.
• Pre-Render Configuration Interpolation: Evaluates variables inside docmd.config.json before template compilation. Authors can define dynamic top banners ("content": "**docmd v{{ docmd.version }} is live!**") and automated footer copyright strings ("copyright": "© {{ docmd.buildYear }} Acme Corp").
• Environment Variable Promotion: System environment variables are accessible via {{ env.VARIABLE }}. Any variable prefixed with DOCMD_VAR_ is automatically promoted to top-level for clean template authoring.
• Headless Client Runtime (docmd-runtime.js): Bundled across all themes. Dynamic variables declared under variables.dynamic or prefixed with user. are rendered as <span data-docmd-var="..."> markers. The runtime provides window.docmd.var.set(), get(), list(), and sync(), enabling instant personalization of API keys in code snippets without full-page reloads.

Search Index Resolution for Versioned & Sub-site Mounts (@docmd/plugin-search)

Contributed by @Goldloli in PR #266 (closing issue #262):

• On sites whose configured base path itself ends in a version segment (e.g. /docs/v1.2.3/), the previous relative path deduction stripped the trailing version segment, causing the search plugin to request _docmd-search/ from the parent directory.
• The client now prioritises the build-time absolute window.DOCMD_SITE_ROOT injected by layout.ejs. Relative deduction is retained as a robust fallback for legacy templates and standalone search pages.

SPA Logo Routing & Navigation Fixes (@docmd/ui)

• Resolved an issue where clicking the site logo with an external destination (e.g. https://docmd.io) was intercepted by the SPA client router, resulting in an in-page navigation error.
• Verified that external links, anchor targets, and cross-origin links properly bypass SPA interceptors while internal workspace transitions remain instant and smooth.

Template Resolution & Monorepo Runtime Dependency Hardening (@docmd/api, @docmd/ui)

• Resolved the [ WARN ] Template "summer" declared slot "layout" but file not found warning observed in multi-project local development.
• Gated monorepo source package resolution in runtime-deps.ts to execute only when isMonorepoContext is valid, preventing pre-flight batch installation from skipping necessary template packages.
• Added hierarchical node module resolution fallbacks in @docmd/ui and @docmd/plugin-search to prevent npm v7+ from pruning sibling dependencies during sub-project development.

Community Contributors & Pull Requests

Special thanks to community members who contributed to the v0.9.9 release:

• @Goldloli for PR #266 (search index path resolution for versioned base paths, closing issue #262).
• @dependabot for automated security and dependency maintenance (PR #264, PR #265).

What to Expect in 0.9.10

• Enhanced code snippet copy actions with visual feedback states across mobile browsers.
• Expanded container normalisation for deeply nested tab groups and collapsible callouts.
• Further optimisations for multilingual vector search index generation.