docmd features a modular plugin architecture. Required plugins ship with the core and need no installation. Optional plugins can be installed with a single CLI command.

Installing Plugins

Use the docmd CLI to install and remove plugins:

# Install a plugin
npx @docmd/core add <plugin-name>

# Remove a plugin
npx @docmd/core remove <plugin-name>

The installer detects your package manager (npm, pnpm, yarn, or bun). It resolves short names to full package names and injects the config into your docmd.config.json.

Use --verbose (or -V) for full installer output:

npx @docmd/core add <plugin-name> -V

Required Plugins

These plugins are bundled with @docmd/core. No installation is needed. Enable them in your docmd.config.json:

docmd.config.json
  "plugins": {
    "search": {},
    "seo": { "aiBots": false },
    "sitemap": {},
    "analytics": {},
    "llms": {},
    "okf": {},
    "mermaid": {},
    "openapi": {},
    "git": {}
  }
Git Plugin

The Git plugin detects if your project is a Git repository. If not, it disables itself automatically. No configuration is required for last-updated timestamps.

OKF Bundle (new in 0.8.8)

@docmd/plugin-okf generates an Open Knowledge Format bundle (site/okf/) — a typed manifest plus per-page concept files that AI agents consume directly. The plugin is enabled by default; set "plugins": { "okf": false } to opt out. See the OKF Bundle Plugin docs for the full contract.

Optional Plugins

Optional plugins require installation before enabling.

Plugin Install Command Description
PWA npx @docmd/core add pwa Progressive Web App support with offline caching
Threads npx @docmd/core add threads Inline discussion comments stored in Markdown
Math npx @docmd/core add math Native KaTeX and LaTeX mathematics rendering

Auto-Installation

When you add an official plugin to your docmd.config.json without installing it, docmd automatically downloads and installs it on the next build. This works for all plugins in the official registry.

docmd.config.json
{
  "plugins": {
    "pwa": {}
  }
}

The auto-installer:

  • Targets official @docmd/plugin-* packages only.
  • Pins the version to match your @docmd/core installation.
  • Detects and uses your project’s package manager.
  • Reports progress in the terminal as it runs.
Resilient auto-install (new in 0.8.9)

The auto-installer uses dynamic import() for the final load step, so it
works for ESM packages that declare only an import condition in their
exports field. The set of names it can install is still restricted to
the official plugin registry allowlist — a registry re-check runs inside
the retry path as defense-in-depth, so a future change to the installer
cannot silently turn it into a generic npm-loader.

Third-Party & Custom Plugins

For security, the installer enforces an official registry allowlist. Third-party plugins must be installed natively using your package manager:

npm install my-custom-plugin
# or pnpm add, yarn add, bun add

After installation, add the plugin to your docmd.config.json using its exact package name:

docmd.config.json
{
  "plugins": {
    "my-custom-plugin": {
      "someOption": true
    }
  }
}

If the plugin meets docmd’s requirements, it activates automatically during the build. Otherwise, the engine reports an error.

Plugin Scopes and noStyle Overrides

Plugins inject CSS and behaviour globally. However, you can configure them to bypass specific pages or entirely disable their execution on unstyled landing pages (noStyle: true).

Global Config Extent

Instruct any plugin to automatically skip noStyle pages via your docmd.config.json:

docmd.config.json
{
  "plugins": {
    "math": {
      "noStyle": false
    }
  }
}

Page Local Scope (Frontmatter)

You can definitively enable or disable any plugin per-document via markdown frontmatter.

---
noStyle: true
plugins:
  math: true
  threads: false
---

# Only Math renders here, Threads are completely blocked

Plugin Lifecycle

Plugins hook into different stages of the build and development process:

Hook Description
markdownSetup(md, opts) Extend the Markdown parser with custom rules.
generateMetaTags(config, page, root) Inject <meta> and <link> tags into the <head>.
generateScripts(config, opts) Inject scripts into <head> or </body>.
getAssets(opts) Define external files or CDN scripts to inject.
onPostBuild(ctx) Run logic after all HTML files finish generating.
translations(localeId) Return translated UI strings for a locale.
actions Server-side handlers callable via WebSocket RPC.
events Fire-and-forget handlers for browser-pushed events.

Plugin Safety

The plugin system guarantees build safety:

  • Validation: Invalid plugin descriptors are rejected at load time.
  • Isolation: Every hook invocation is wrapped in a try/catch. A broken plugin cannot crash the build.
  • Capability enforcement: Plugins can only register for hooks they have declared.

See Building Plugins for the full API reference.

Traceable Architecture

Every meta-tag and script the engine emits is generated from explicit config and plugin output. There are no hidden side effects.

Previous Customisation & Variables Next Search