@docmd/api 是插件系统的专属包。它提供 hook 注册、WebSocket RPC 分发、源文件编辑工具，以及集中的 URL 工具。

npm install @docmd/api

URL 工具

插件应使用这些集中工具，而不是各自实现 URL 逻辑。

outputPathToSlug(outputPath)

将构建引擎的输出路径转换为干净的目录式 slug。

import { outputPathToSlug } from '@docmd/api';

outputPathToSlug('guide/index.html');   // returns 'guide/'
outputPathToSlug('index.html');         // returns '/'
outputPathToSlug('de/v1/api/index.html'); // returns 'de/v1/api/'

outputPathToPathname(outputPath)

转换为根相对的 pathname。

import { outputPathToPathname } from '@docmd/api';

outputPathToPathname('guide/index.html'); // returns '/guide/'
outputPathToPathname('index.html');       // returns '/'

outputPathToCanonical(outputPath, siteUrl)

拼接出完整的 canonical URL。

import { outputPathToCanonical } from "@docmd/api";

outputPathToCanonical("guide/index.html", "https://docs.example.com");

sanitizeUrl(url)

合并多余斜杠（协议后的双斜杠除外）。

import { sanitizeUrl } from "@docmd/api";

sanitizeUrl("https://docs.example.com//guide"); // returns "https://docs.example.com/guide"
sanitizeUrl("/foo//bar"); // returns "/foo/bar"

buildAbsoluteUrl(base, localePrefix, versionPrefix, pagePath)

拼出带 locale、version 前缀的绝对 URL。

import { buildAbsoluteUrl } from '@docmd/api';

buildAbsoluteUrl('/', 'de/', 'v1/', 'guide/'); // returns '/de/v1/guide/'

resolveHref(href)

把用户手写的 href 规整为干净的 URL。处理 .md 剥离、尾部斜杠，以及 external: 与 raw: 前缀。

import { resolveHref } from "@docmd/api";

resolveHref("overview.md"); // returns "overview/"
resolveHref("external:https://github.com"); // returns "https://github.com"
resolveHref("raw:docs/readme.md"); // returns "docs/readme.md"

预计算好的页面 URL

每个 page 对象都带有预计算的 URL 字段。插件可以直接读取，无需额外计算。

export async function onPostBuild({ pages, config }) {
  for (const page of pages) {
    console.log(page.urls.slug);
    console.log(page.urls.canonical);
    console.log(page.urls.pathname);
  }
}

Action 与 Event 分发

createActionDispatcher(hooks, options)

创建一个分派器，把 WebSocket RPC 消息路由到插件的 action / event 处理器。

import { createActionDispatcher } from "@docmd/api";

const dispatcher = createActionDispatcher(
  { "actions": myPlugin.actions, "events": myPlugin.events },
  { "projectRoot": "/path/to/project", config, broadcast }
);

const { result, reload } = await dispatcher.handleCall("my-action", payload);

createSourceTools({ projectRoot })

生成用于编辑 Markdown 源文件的工具集。

import { createSourceTools } from "@docmd/api";

const source = createSourceTools({ "projectRoot": "/path/to/project" });

const block = await source.getBlockAt("docs/page.md", [10, 12]);
await source.wrapText("docs/page.md", [10, 12], "important", 0, "**", "**");

loadPlugins(config, options)

加载、校验并注册所有在配置中声明的插件，返回填充好的 hook 注册表。支持接收 isDev（布尔值）以声明当前是否处于开发模式（用于控制需要实时服务器的插件是否引入前端资源）。

import { loadPlugins, hooks } from "@docmd/api";

const registeredHooks = await loadPlugins(config, {
  "resolvePaths": [__dirname],
  "isDev": true // 可选，默认为 false
});

客户端运行时 API (window.docmd)

在本地开发运行期间（docmd dev），浏览器会在 /__dev/docmd-api.js 加载客户端 RPC 桥接脚本，向全局注入 window.docmd，用于 WebSocket 通信及开发服务器在线状态检测。

docmd.isLive()

同步返回布尔值。当与本地开发服务器的 WebSocket 连接处于建立且可用状态时返回 true。

if (window.docmd && window.docmd.isLive()) {
  // 本地实时开发服务器已连接
}

docmd.ping(timeoutMs = 2000)

通过内置的 system:ping RPC 动作向开发服务器发送异步心跳检测。在超时时间内响应成功返回 true，若断开或超时则返回 false。

const ok = await window.docmd.ping();

引擎加载器 API

可插拔的引擎架构允许通过 @docmd/api 直接以编程方式解析并实例化加速层。

loadEngine(engineName)

解析并初始化所请求的构建引擎后端。当原生二进制不可用时，会优雅回退到高性能的 JavaScript 引擎。

import { loadEngine } from "@docmd/api";

const engine = await loadEngine("rust");
const gitLogResult = await engine.runWorkerTask("git:log", { "paths": ["docs/guide.md"] });

registerEngine(engineName, engineInstance)

允许自定义工具或第三方集成方通过编程方式注册自定义的执行引擎。

import { registerEngine } from "@docmd/api";

registerEngine("custom", myCustomEngineImpl);

类型导出

对于 TypeScript 插件作者，以下类型可用：

import type {
  PluginModule,
  PluginDescriptor,
  PluginHooks,
  PageContext,
  BeforeBuildContext,
  PostBuildContext,
  Capability,
  ActionContext,
  ActionHandler,
  EventHandler,
  SourceTools,
  BlockInfo,
  TextLocation,
  Engine,
} from '@docmd/api';

下一步

• 开发插件:, 起点。
• 插件示例:, 查看完整的插件演练。
• 引擎与架构:, Rust 引擎、N-API 与引擎加载器内部。