Plugins are the primary extension mechanism for docmd. They allow you to inject HTML, modify Markdown parsing, inject build-time data, and automate post-build tasks. This guide outlines the plugin API.

Plugin Descriptor

Every plugin must export a plugin descriptor declaring its identity and capabilities. This enables the engine to validate and isolate boundaries at load time.

  "plugin": {
    "name": "my-analytics",
    "version": "1.0.0",
    "capabilities": ["head", "body", "post-build"]
  },

  "generateScripts": (config, opts) => { ... },
  "onPostBuild": async (ctx) => { ... }

Note: The descriptor is strictly required. Plugins without it will fail to load.

The docmd Namespace (new in 0.8.9)

In addition to the runtime plugin descriptor, every official plugin must declare a docmd namespace in its package.json. This namespace is the build-time contract that the registry generator reads to build the single source of truth that the runtime loader consumes.

{
  "name": "@docmd/plugin-foo",
  "version": "1.0.0",
  "docmd": {
    "key": "foo",
    "kind": "plugin",
    "displayName": "Foo",
    "tagline": "What this plugin does in one line",
    "capabilities": ["head", "body", "post-build"]
  }
}

Engines have the same docmd namespace but no capabilities — they don’t participate in the hook system, only in the engine loader.

The build-time cross-check (also new in 0.8.9) surfaces drift between the JS descriptor and the manifest, including the “implemented hook without declared capability” silent-drop bug that was previously invisible.

Core Capabilities

The capabilities array dictates which hooks your plugin is allowed to use.

Note: the template capability is exclusive — if a plugin declares it, it cannot also declare head, build, post-build, etc. Templates ship slots and assets only; they do not run lifecycle hooks. If you need both, ship two separate packages.

Plugin API Reference

A docmd plugin is a standard JavaScript object that implements one or more of the following hooks.

Building a template plugin (new in 0.8.7)

A template is a plugin with capabilities: ['template']. It ships a templates[] array (slot overrides) and a templateAssets[] array (CSS/JS bundle). See the dedicated Templates guide and Theming → Templates for the full authoring walkthrough, slot table, and resolution chain. The minimum viable template looks like:

export default {
  plugin: {
    name: 'template-foo',
    version: '1.0.0',
    capabilities: ['template'],
  },
  templates: [
    { type: 'menubar', templatePath: '/abs/path/to/templates/partials/menubar.ejs' },
    { type: 'footer',  templatePath: '/abs/path/to/templates/partials/footer.ejs' },
  ],
  templateAssets: [
    { type: 'css', path: '/abs/path/to/assets/css/foo.css', priority: 10, position: 'head' },
  ],
};

Creating a Local Plugin

Creating a plugin is as simple as defining a JavaScript file. For example, my-plugin.js:

import path from "path";

export default {
  plugin: {
    "name": "my-plugin",
    "version": "1.0.0",
    "capabilities": ["head", "post-build"]
  },

  markdownSetup: (md, options) => {
    // Add custom parser rules
  },

  generateMetaTags: async (config, page, relativePathToRoot) => {
    return `<meta name="x-build-id" content="${config._buildHash}">`;
  },

  onPostBuild: async ({ config, pages, outputDir, log, options }) => {
    log(`Custom Plugin: Verified ${pages.length} pages.`);
  }
};

To enable your plugin, reference its full package name in your docmd.config.json:

  "plugins": {
    "my-awesome-plugin": {}
  }

Note: Shorthand names (e.g. math, search) are reserved for official @docmd/plugin-* packages. Third-party plugins must always use their full npm package name.

Plugin Resolution

The docmd engine resolves plugin names as follows:

• Official shorthands (math, search) expand to @docmd/plugin-<name>. Only official packages can exist under the @docmd scope.
• Third-party plugins must use their full package name (e.g. my-awesome-plugin, @myorg/docmd-extras). There is no alias system for external plugins. This eliminates supply-chain attack vectors.

Plugin Isolation

Every hook invocation is wrapped in a try/catch block. A broken plugin cannot crash the build or interfere with other plugins. Errors are logged and collected into a summary.

Scoping Plugins (noStyle)

Plugins inject their CSS/JS universally by default. Developers can explicitly prevent their plugin from rendering on noStyle pages by exporting a noStyle boolean:

export default {
  noStyle: false, 

  generateScripts: () => { ... }
}

Users can override this via configuration (plugins: { math: { noStyle: false } }) or dynamically via Markdown frontmatter (plugins: { math: true }).

Lifecycle Hooks

Docmd provides deep integration hooks. They allow plugins to manipulate configuration, raw sources, and page data.

Engine Acceleration & Background Tasks (runWorkerTask)

docmd executes intensive operations via a Pluggable Engine Architecture. Plugins can easily offload custom heavy I/O or CPU-bound subroutines through the configured build engine (e.g., JavaScript or native Rust workers).

The runWorkerTask method is injected transparently into PageContext, PostBuildContext, and ActionContext.

{
  "plugin": { "name": "my-plugin", "version": "1.0.0", "capabilities": ["post-build"] },

  "onPostBuild": async (ctx) => {
    // Pass a registered engine action name or absolute script path
    const result = await ctx.runWorkerTask('/path/to/worker.js', 'parseData', [ctx.outputDir]);
  }
}

Data Fetching and Indexing (onBeforeBuild)

The onBeforeBuild hook runs after markdown parsing but before the HTML rendering loop begins. It is optimal for heavy data indexing or API calls.

It receives the BeforeBuildContext, containing all pages and the tui instance. This allows plugins to show isolated progress bars.

export async function onBeforeBuild({ pages, tui }) {
  tui.step('Fetching remote plugin data', 'WAIT');

  let processed = 0;
  for (const page of pages) {
    if (page.sourcePath) {
      page.frontmatter.remoteData = await fetchHeavyData(page.sourcePath);
    }
    processed++;
    if (processed % 10 === 0 || processed === pages.length) {
      tui.progress('Fetching remote plugin data', processed, pages.length);
    }
  }

  tui.step('Fetching remote plugin data', 'DONE');
}

onBeforeRender and PageContext

Use onBeforeRender to inject build-time data derived from the source file.

interface PageContext {
  sourcePath: string;           
  frontmatter: Record<string, any>; 
  html: string;                 
  localeId?: string;
  versionId?: string;
  relativePathToRoot?: string;
  runWorkerTask<T = any>(modulePath: string, functionName: string, args: any[]): Promise<T>; 
}

export default {
  plugin: {
    name: "my-metadata-plugin",
    version: "1.0.0",
    capabilities: ["build"]
  },

  onBeforeRender: async (page) => {
    const stats = fs.statSync(page.sourcePath);
    page.frontmatter.wordCount = page.html.split(/\s+/).length;
    page.frontmatter.fileSize = stats.size;
  }
}

Deep Dive: Asset Injection

The getAssets() hook allows your plugin to bundle client-side logic securely.

export default {
  getAssets: (options) => {
    return [
      {
        url: "https://example.com/script.js",
        type: "js",
        location: "head"
      },
      {
        src: path.join(__dirname, "plugin-init.js"), 
        dest: "assets/js/plugin-init.js",            
        type: "js",
        location: "body"
      }
    ];
  }
}

Translating Plugins (i18n)

Plugins rendering client-side UI should expose strings via the translations(localeId) hook. The engine merges these with core strings automatically.

The standard pattern stores a JSON file for each language in an i18n/ directory:

import fs from "fs";
import path from "path";

export default {
  plugin: {
    name: "my-plugin",
    version: "1.0.0",
    capabilities: ["translations", "body"]
  },

  translations: (localeId) => {
    try {
      const p = path.join(__dirname, "i18n", `${localeId}.json`);
      return JSON.parse(fs.readFileSync(p, "utf8"));
    } catch { }

    return {};
  }
}

WebSocket RPC Actions

Plugins can register action handlers and event handlers that run on the dev server. They are callable from the browser via the window.docmd API.

export default {
  plugin: {
    name: "my-live-plugin",
    version: "1.0.0",
    capabilities: ["actions", "events"]
  },

  actions: {
    "my-plugin:save-note": async (payload, ctx) => {
      const content = await ctx.readFile(payload.file);
      const updated = content + "\n\n> " + payload.note;
      await ctx.writeFile(payload.file, updated);
      return { "saved": true };
    }
  },

  events: {
    "my-plugin:page-viewed": (data, ctx) => {
      console.log(`Page viewed: ${data.path}`);
    }
  }
};

The ctx (ActionContext) provides:

All file operations are sandboxed to the project root.

Best Practices

1. Declare Capabilities: Always export a plugin descriptor with declared capabilities.
2. Use onBeforeRender for data injection: If your plugin computes frontmatter fields, use onBeforeRender.
3. Async/Await: Always use async functions for onPostBuild, onBeforeRender, and action handlers.
4. Statelessness: Avoid maintaining state within the plugin object. The engine may re-initialise plugins dynamically.
5. Naming Convention: Prefix community package names with docmd-plugin-.
6. Action Namespacing: Prefix action names with your plugin name (e.g., my-plugin:save-note).
7. Action Validation: Define and require an explicit payload schema in your actions.
8. Logging: Use the provided log() helper in onPostBuild to respect user verbosity settings.

ESM Exports — the default Condition

Your plugin’s package.json must include a "default" condition in
exports["."], alongside the import condition:

"exports": {
  ".": {
    "types": "./dist/index.d.ts",
    "import": "./dist/index.js",
    "default": "./dist/index.js"
  }
}

If you declare only import, the auto-installer’s first attempt throws
ERR_PACKAGE_PATH_NOT_EXPORTED because Node’s CommonJS resolver cannot
match any condition. The retry path will still succeed (it uses dynamic
import() directly), but the build will print a redundant “Plugin
installed” TUI line every time.

This convention matches what @docmd/plugin-git, @docmd/plugin-openapi,
and @docmd/plugin-threads already ship with. Templates (@docmd/template-*)
have the same requirement.