Highlights

docmd v0.9.6 brings a major suite of capabilities and refinements across the documentation engine:

• Focus Mode (Zen Mode): Distraction-free reading with dedicated top-right Print and Light/Dark Mode controls.
• Multi-Position Banners: 7 distinct banner positions (top, header, sidebar-top, sidebar-bottom, toc-top, toc-bottom, footer) with project-to-version inheritance, persistent card defaults, and session persistence.
• Heading Anchor Permalinks: Instant click-to-copy full anchor URLs with visual animated checkmark confirmation.
• Image Lightbox Re-bind & UI Polish: Event delegation and SPA page re-binding, frosted glass captions, and integrated close controls.
• Title & SEO Architecture: Granular layout.titleSeparator, layout.titleAppend control, and automatic structured JSON-LD schemas (Organization, WebSite, BreadcrumbList, and custom frontmatter ldJson).
• Open Knowledge Format (OKF): Concept descriptions in okf.yaml and automatic tag merging from both tags and keywords.
• Post-Build Asset Declarations Hook: Exposing an immutable, deeply frozen snapshot of resolved plugin/template assets to post-build hooks.
• AI Assistant Multi-Turn Streaming: Live token replacement protocol (meta.replace: true) and synthesis fallback across multi-turn reasoning.
• Security Dependency Hardening: Remediation of upstream vulnerabilities across sharp, adm-zip, and protobufjs, plus automated pipeline security auditing.
• Batch Pre-Flight Runtime Dependency Auto-Install: Unified zero-config batch installation of templates, plugins, and semantic search peer dependencies without manual package.json declarations or npm tree pruning.
• Parser & Live Editor Enhancements: open flag support for ::: details alias matching ::: collapsible, expanded container attributes, and smooth return navigation in the in-browser Live Editor.

Focus Mode & Print Controls (@docmd/ui & @docmd/template-summer)

• Distraction-Free Zen Reading: With a single click on the options menu or keyboard shortcut (Alt+F / Option+F), all navigation sidebars, headers, table of contents, breadcrumbs, footers, and floating tools recede into the background. Content centres with optimal typographic line length for immersive technical reading.
• Dedicated Top-Right Controls: In Focus Mode, only the three essential reading tools remain in the floating top-right toolbar:
  1. Print Page (printer icon, triggering window.print() with a tailored, clean print stylesheet).
  2. Light / Dark Mode Toggle (allowing instant theme switching while in focus).
  3. Exit Focus Mode (minimize-2 icon or pressing Esc / Alt+F).
• Document Copy Widgets Print Button: When print is enabled (layout.print: true or layout.optionsMenu.components.print: true or layout.copyWidgets.print: true), a dedicated Print button renders directly alongside the Copy Markdown and Copy Context buttons in the document header.
• Comprehensive Print Stylesheet: Built-in @media print rules ensure printed documentation or PDF exports strip away all navigation and web chrome, producing crisp, publish-ready paper documents.
• Cross-Template Support: Fully supported out of the box in both the default @docmd/ui template and the @docmd/template-summer layout.
• Configurable Options Menu: optionsMenu.components.focusMode and optionsMenu.components.print can be configured directly in docmd.config.json under layout.optionsMenu.components.

Multi-Position Banners & Inheritance (layout.banners)

• 7 Dedicated Display Positions: Configure site announcements and contextual callouts across top, header, sidebar-top, sidebar-bottom, toc-top, toc-bottom, and footer.
• Card Banner Persistence Defaults: Sidebar and Table of Contents card banners (sidebar-top, sidebar-bottom, toc-top, toc-bottom) now default to persistent (dismissible: false), ensuring promotional and sponsor cards stay visible across pages. Banners can explicitly opt in to dismissal using dismissible: true or dismissable: true.
• Dismissible Spelling Aliases: Support for dismissable and closable configuration keys alongside standard dismissible.
• Hierarchical Inheritance & Overrides: Versioned documentation sites can inherit workspace or project banners while allowing specific documentation versions (e.g. v09) to override or introduce distinct notices without losing sidebar notices.
• Rich Content & Persistence: Each banner supports markdown text, customizable Lucide icons, action hyperlinks, visual variants (info, tip, warning, announcement), and sessionStorage-persisted dismissal state.

UI & Navigation Enhancements

• Click-to-Copy Section Anchor URLs: Clicking any section header anchor permalink icon (#) now copies the full page URL with hash directly to the user’s clipboard. The anchor icon temporarily transitions to a green checkmark confirmation icon with automatic fallback handling.
• Image Lightbox Re-binding & Modernized UI: The built-in lightbox now uses unified event delegation and automatically re-binds across client-side SPA route transitions (docmd:page-mounted). The modal UI has been updated with a sleek frosted glass (backdrop-filter) caption bar and a circular close button.
• Reading Time Calculation: Improved accuracy for reading time estimates across complex Markdown documents, accounting for code blocks and media elements.
• Hardened Client-Side Router: Client-side hover prefetching and SPA navigation now strip accidental wrapping quotes from href attributes, properly detect target="_blank" and rel="noopener", and preserve root path navigation.
• Unescaped Navigation Attributes: Fixed EJS attribute escaping in sidebar navigation templates (<%- instead of <%=), ensuring custom data attributes, aria labels, and link properties render cleanly.
• Plugin Live Reload Sync: Resolved an issue in packages/api/src/hooks.ts where reloading a plugin configuration in live development mode did not assign the reloaded module to rawModule, ensuring runtime module reloads take effect immediately.

Title, Navigation & SEO Architecture (@docmd/plugin-seo & @docmd/core)

• Configurable Title Separators: Authors can now customize the separator string between page title and site title via layout.titleSeparator (e.g. " - ", " | ", " / "), with per-page frontmatter override support.
• Title Append Control: titleAppend: false in page frontmatter or layout.titleAppend: false suppresses appending the site title, allowing precise, standalone <title> strings on marketing and landing pages.
• Structured JSON-LD Schemas:
  • Automatically emits Google-compliant Organization schema on root homepages.
  • Generates WebSite schema with linked search query specifications.
  • Emits hierarchical BreadcrumbList schemas across nested documentation structures.
  • Supports custom raw JSON-LD injection via the frontmatter ldJson property.
• Social Graph Consistency: Enforces identical titles across HTML <title>, Open Graph og:title, and Twitter twitter:title tags.

Open Knowledge Format Enhancements (@docmd/plugin-okf)

• Concept Descriptions: okf.yaml concepts now automatically populate description fields from page frontmatter or document introductory abstracts.
• Flexible Tag Merging: The OKF bundle generator now seamlessly unifies tags and keywords frontmatter properties, whether specified as arrays or comma-separated strings.

Post-Build Asset Declarations Hook (@docmd/api & @docmd/core)

• Immutable Asset Snapshots: The post-build plugin hook pipeline now receives an immutable declaration snapshot of all resolved plugin and template assets (report.resolvedAssets), allowing post-processors and deployers to inspect output assets safely without risking manifest mutations.

AI Assistant Multi-Turn Streaming & Stream Replacement (@docmd/plugin-ai & docmd-assistant)

• Extended Multi-Turn Reasoning: Expanded the internal conversational budget up to 6 turns, ensuring tool-assisted searches (such as documentation structural checks and page readings) complete before final synthesis.
• Real-Time Stream Replacement: Implemented a streaming replacement protocol (meta.replace: true) allowing live SSE tokens to stream immediately during thought iterations without leaking raw tool markers.
• Architectural Synthesis Fallback: Added a multi-tier fallback context synthesizer when queries reference concepts not directly mapped in primary navigation.
• Configurable Message Actions: Message action controls (Copy Response, Retry, and Edit Prompt) in @docmd/plugin-ai can be enabled via config.plugins.ai.messageActions: true (defaulting to false).

File Exclusions & Git Ignore Filtering

• Project-Level Exclusions: Added config.exclude glob support to allow documentation authors to exclude draft pages, internal notes, and temporary assets from generation.
• Automatic .gitignore Honouring: Integrated a tree-walking .gitignore parser that automatically excludes ignored markdown files and directories from HTML compilation and semantic search vectorisation.

Markdown Parser & Container Enhancements (@docmd/parser)

• Details Container Open Flag: Added support for the open flag on ::: details aliases matching the behavior of ::: collapsible open.
• Container Property Mapping: Added support for title, text, and label properties across badges, tags, buttons, tooltips, and changelog containers.
• Icon Set Update: Upgraded bundled lucide-static to ^1.47.0.

Live Editor Playground (@docmd/live)

• Cross-Site Seamless Flow: Added direct return navigation to https://docmd.io via the back button and logo.
• KaTeX Preset Preservation: Prevented String.prototype.replace from escaping double-dollar signs ($$) in KaTeX math presets.

Security Auditing & Dependency CVE Remediation

• Critical CVE Patches:
  • sharp (^0.35.4): Remediates critical security advisories relating to bundled libheif vulnerabilities (GHSA-rgj7-g3m4-5g8c).
  • adm-zip (>=0.6.0): Resolves directory traversal and arbitrary file write vulnerabilities (GHSA-955c-w567-g4pw).
  • protobufjs (^7.6.5): Fixes prototype pollution vulnerabilities (CVE-2023-36665).
  • onnxruntime-node (^1.27.0): Upgraded to provide modern native prebuilds for Node 20/22+ on Apple Silicon (darwin-arm64) and modern Linux distributions.
• Automated Pipeline Security Audit: tools/prep.js now executes an automated security audit (pnpm audit --audit-level=high) prior to building, preventing any code from being packaged or released with high or critical vulnerabilities.
• docmd-search Dependency Locks: Explicit package overrides and peer dependency definitions ensure consumers never install outdated or vulnerable binary dependencies.

Summer Template & Mobile Refinements (@docmd/template-summer & @docmd/plugin-ai)

• Summer Palette Variable Bridge: Core and plugin CSS variables (--docmd-*, --bg-color, --sidebar-bg, --text-color, etc.) are now mapped directly onto the Summer theme tokens, ensuring plugin UI (AI Assistant, Git metadata, OpenAPI) and shared components render with accurate colors and styling under the Summer template.
• Mobile Topbar Search: Added an adaptive search toggle button for viewports under 900px, enabling mobile readers to access the full-width search input smoothly. Integrated with Cmd/Ctrl+K and / hotkeys, with Escape to close.
• Responsive Git Popover: Restructured the commit popover under 900px to anchor cleanly to the footer and adapt to the viewport width, eliminating horizontal page overflow on small screens.
• AI Bar Mobile Flex: Added min-width: 0 to the AI Assistant prompt bar input, allowing it to flex responsively without overflowing narrow mobile viewports.

Batch Pre-Flight Runtime Dependency Installation (@docmd/api & @docmd/core)

• Zero-Manual Installation for Templates, Plugins & Semantic Search: Documentation projects can now specify official templates (e.g. theme.template: 'summer'), plugins (e.g. plugins: ['math', 'mermaid']), search engines (plugins.search.semantic: true), or rendering engines (engine: 'rust') directly in configuration without manually declaring or installing them in package.json.
• Pre-Flight Discovery & Single Batch Installation: Before starting compilation across both multi-project workspaces (buildWorkspace) and single-project sites (buildSite), docmd conducts a pre-flight scan of all configured requirements. If any runtime dependencies or peer packages (docmd-search, @huggingface/transformers, onnxruntime-node, sharp) are missing from node_modules, docmd dynamically resolves their versions and installs them all together in a single atomic batch command with --no-save.
• Elimination of npm Tree Reconciliation Pruning: Previously, installing missing packages sequentially during different build phases caused modern npm (v7+) to treat earlier auto-installed packages as extraneous and prune them from node_modules (e.g. deleting @docmd/template-summer when docmd-search installed later). Installing all dependencies in one unified batch guarantees all runtime assets and layouts remain intact on disk.
• Dynamic Registry-Aware Versioning: Runtime installations dynamically query the npm registry to fetch the latest published versions, preventing ETARGET failures during pre-release development while ensuring published production releases automatically install matching versions.
• Strict Scope & Registry Validation: Unknown or unofficial package names that do not match @docmd/* or are absent from the official docmd catalog are strictly rejected with clean warning reporting, ensuring the auto-installer remains completely secure.

Community Contributors & Acknowledgements

We are grateful to the community members whose pull requests and bug fixes helped shape this release:

• @MSOB7YY: Summer template mobile search toggle, responsive git popover, CSS token bridging, and AI input overflow fix (#238), plus broken link and route normalization fixes (#229).
• @w666: Image lightbox re-binding on SPA navigation and modern UI styling (#234), and heading anchor permalink click-to-copy (#236).
• @justinTM: Accurate reading time computation fix (#231).