Typematter API

Experimentalv0.4.0-rc

版本关联

当前版本v0.4.0-rc更新日志v0.4.0-rc

Typematter 的 API 设计对齐主流文档系统的共性能力：统一 CLI、声明式配置、插件/钩子机制、内置 MDX 组件库，以及编译期生成导航与搜索索引。目标是保持内容与渲染解耦，同时保证构建可缓存、可回滚、可扩展。

构建期优先

所有内容扫描、路由生成与索引构建必须在编译期完成，运行时仅允许轻量交互，不允许再次扫描文件系统。

CLI 命令层

typematter dev：本地开发服务器，监听 content/ 并增量刷新 registry。
typematter build：扫描内容、生成 registry、运行验证并输出静态站点。
typematter validate：仅运行文档质量验证，适合 CI。
typematter new：脚手架新项目或添加语言目录。
typematter export-registry：导出 contentRegistry.json 供运行时或外部系统使用。
typematter serve（可选）：预览已构建站点。

站点配置

站点配置集中在 site.config.ts，负责全局行为与插件注册，建议通过 defineSiteConfig() 提供强类型约束：

export default defineSiteConfig({  title: "Typematter",  contentDir: "content",  i18n: {    defaultLanguage: "cn",    languages: [      { code: "cn", label: "简体中文" },      { code: "en", label: "English" },    ],  },  repo: {    url: "https://example.com/typematter",    branch: "main",    docsPath: "content",    editBaseUrl: "https://example.com/typematter/edit/main",  },  feedback: { url: "mailto:docs@example.com" },  plugins: [searchIndex(), apiReference()],  validation: {    rules: {      brokenLinks: "error",      duplicateTitles: "error",      orphanPages: "warn",    },  },});

导航配置

nav.config.ts 只负责展示顺序与隐藏，不允许创建虚拟页面。所有 doc 项必须引用真实存在的路由：

export default defineNavConfig<Route>()({  appendUnlisted: true,  groups: [    {      title: "API",      items: [        { type: "doc", slug: "api/typematter-api" },        { type: "doc", slug: "api/content-registry" },      ],    },  ],});

插件与钩子

插件用于扩展 Markdown 语法、生成搜索索引、生成 API 参考页、版本切换等逻辑。所有钩子在构建期执行：

export type TypematterPlugin = {  name: string;  mdx?: {    remark?: any[];    rehype?: any[];    components?: Record<string, unknown>;  };  hooks?: {    buildStart?(ctx): void | Promise<void>;    contentCollected?(ctx, pages): void | Promise<void>;    pageParsed?(ctx, page): void | Promise<void>;    pageRendered?(ctx, page): void | Promise<void>;    registryReady?(ctx, registry): void | Promise<void>;    validate?(ctx, report): void | Promise<void>;    buildEnd?(ctx, result): void | Promise<void>;  };};

构建/导出路径中的执行顺序固定为： buildStart -> contentCollected -> pageParsed(逐页) -> registryReady -> buildEnd。

validate 路径会先跑内建规则，再执行插件 validate 钩子。 mdx.remark / mdx.rehype / mdx.components 在 MDX 渲染链中真实执行。

MDX 组件与语义一致性

内置组件库用于保证一致的阅读语义（Callout、Columns、Diff、Tabs 等）。新增组件需同步更新组件注册表与构建期使用检测，避免出现一次性变体。

内容注册表

构建期生成 contentRegistry.json，包含路由、标题、顺序、章节、状态/版本/标签、TOC 与组件使用信息，并支持缓存：

type ContentRegistry = {  pages: Array<{    route: string;    title: string;    order: number;    section: string;    status?: string;    version?: string | number;    tags?: string[];    toc: Array<{ id: string; title: string; level: number }>;  }>;};

运行时只读取 registry，不再扫描文件系统。

构建验证

验证是第一等公民，内置规则包括：断链、失效锚点、重复标题、孤立页面、无效 frontmatter、空目录、i18n 结构、导航一致性等。

新增治理规则：

headingDepth：标题最大深度与层级跳跃校验（例如 h2 -> h4）。
missingTranslations：以默认语言为基线，检查缺页、关键 frontmatter 缺失、单语页面。
frontmatterSchema：基于路径规则的分层 frontmatter schema 校验。

规则支持 error | warn | off 并允许插件扩展。 schema 规则按声明顺序合并，路径匹配使用 include / exclude，后规则覆盖前规则。