文章 frontmatter 是 Cogita 多个插件共同依赖的数据源。此前 posts-frontmatter、文章列表、标签、分类、合集、搜索、RSS、SEO、站点地图等插件分别扫描文章目录并解析 frontmatter。文章数量增加后,这种实现会带来重复 IO、重复解析和不同插件数据不一致的问题。
core 在创建主题插件之前,为每次构建注入一个惰性 ContentIndex:
索引只在第一个插件调用 getEntries() 或 getPosts() 时扫描,后续插件复用同一个 Promise。getEntries() 返回文章、contentDir 文档和显式内容源条目,getPosts() 保持只返回文章的旧行为,同时包含内容源声明的 post 条目。正文通过 getPostContent(filePath) 按需读取并缓存,搜索、RSS 等需要全文的插件不再各自重复读取同一文件。core 会在重新触发构建期插件钩子前调用 invalidate(),让下一轮构建重新读取文章、文档和内容源。getEntries() 和正文读取方法都是可选的,以保持第三方插件自行实现 ContentIndex 时的兼容性。索引使用与 posts-frontmatter 一致的文章路由规则,并根据 contentDir 生成普通文档路由。
站点可以通过 contentSources 显式注册第三方内容源。适配器只负责把外部数据转换为统一的
ContentSourceEntry,不需要依赖某个主题,也不应该直接修改 ContentIndex。sourceId 和缺省的
url 会由 Core 统一补齐:
外部内容源如果需要随正文发布图片或其他静态文件,可以额外实现 getAssets(context),返回
{ filePath, publicPath } 描述。Core 会在开发预览和生产构建前复制资源;适配器负责把 Markdown 中的
相对引用改写为公开路径,资源发布不应把外部 checkout 目录直接挂到站点根目录。
id 在一个站点内必须唯一,filePath 是条目的稳定标识,不要求一定是本地文件路径;如果要让
搜索全文和内容关系插件读取外部正文,适配器必须实现 getContent。没有正文读取器时,条目仍可被
Knowledge 主题的元数据、标签和搜索结果消费,但全文搜索和关系提取会按现有能力降级。内容源的
路由不能与 posts、contentDir 或其他内容源重复,避免同一个 URL 对应多个内容实体。实现
getContent 后,Core 会把返回的 Markdown 正文作为附加页面生成;这使 Git checkout 和 JSON 快照都能
在站点中拥有真正可访问的内容入口,而不是只出现在搜索索引中。
插件工厂收到的配置现在还包含 buildContext。它集中承载 root、cwd、contentIndex、主题布局路径和构建元数据等框架内部状态。旧版插件仍可读取同名顶层字段;新插件应通过 getCogitaBuildContext(config) 获取上下文,避免继续扩展配置对象的内部字段。
本阶段已迁移:
plugin-posts-frontmatter:优先使用索引生成 virtual-posts-data。plugin-blog-list:优先使用索引生成列表、筛选、分页和归档数据。plugin-tags、plugin-categories、plugin-collections:优先使用索引派生聚合数据。聚合插件统一使用 @cogita/shared 导出的 ContentPostReference,不再各自复制文章引用字段;依赖文章能力的插件也只消费 Core 注入的 ContentIndex,不再直接依赖文章扫描插件包。
文章运行时虚拟模块 virtual-posts-data 额外暴露 contentDataVersion,外部主题可据此拒绝不兼容的数据契约。
@cogita/plugin-content-relations 是第一个建立在共享索引之上的知识库基础插件。它按需读取
文章正文,提取站内 Markdown 文本链接,并通过 virtual-content-relations-data 暴露出链、反向链接
和相关文章查询。插件只消费 ContentIndex,不会再次扫描文章目录,也不绑定具体主题的页面布局。
当前实现的索引对象已经覆盖文章、contentDir 普通文档页和显式内容源条目;Knowledge 主题组合搜索、
标签、关系和文档导航,带正文的外部条目还会由 Core 生成静态页面。第三方适配器仍应围绕稳定的条目
元数据、正文读取和来源版本策略进行扩展。
@cogita/shared 暴露以下稳定版本字段,新增不兼容字段时递增对应版本:
| 契约 | 版本字段 | 作用 |
|---|---|---|
| 构建上下文 | COGITA_BUILD_CONTEXT_VERSION / buildContext.contractVersion |
识别 CogitaBuildContext 的字段形状 |
| 内容索引 | COGITA_CONTENT_INDEX_VERSION / contentIndex.contractVersion |
识别 ContentIndex 的方法和数据模型 |
| 虚拟模块 | COGITA_VIRTUAL_MODULE_SCHEMA_VERSION / cogitaVirtualModuleVersion |
识别所有 Cogita 虚拟运行时模块的公共数据头 |
| 文章数据 | COGITA_CONTENT_DATA_VERSION / contentDataVersion |
保留 virtual-posts-data 的文章数据兼容性 |
虚拟模块 ID 统一从 COGITA_VIRTUAL_MODULE_IDS 获取,内置文章能力统一使用
COGITA_CAPABILITIES.CONTENT_POSTS。第三方插件仍可以声明自己的能力标识,但不应重新定义
content.posts 或复用已有虚拟模块 ID。插件生成虚拟模块时应使用
createCogitaVirtualModule(source) 写入版本头:
contractVersion 对第三方兼容实现保持可选,以便旧插件继续工作;Core 创建的原生实现总是提供
版本字段。第三方主题如果消费自己关心的模块,应在版本不兼容时显式降级或给出诊断,而不是静默
按旧字段继续渲染。
plugin-search:优先使用索引生成搜索元数据,正文仅在显式开启正文索引时按文件读取。plugin-rss、plugin-seo、plugin-sitemap:优先使用索引生成 Feed、页面 SEO 和站点地图数据。plugin-images:优先使用索引中的文章封面字段关联公共图片。plugin-reading-progress、plugin-comments:优先使用索引中的文章路径和文件路径。依赖 content.posts 能力的内置插件不再保留独立扫描路径,而是由 Core 在能力契约校验阶段保证索引存在;缺少索引时仅在非严格模式下记录告警并降级为空数据。这样可以避免外部站点同时安装多个文章解析实现,也避免不同插件对同一篇文章产生不一致的解析结果。第三方插件仍可在迁移期通过自己的 ContentIndex 实现兼容。
ContentIndex 属于构建期插件配置,不会进入浏览器运行时。buildContext 属于构建期上下文,不应被序列化到虚拟运行时模块。@cogita/shared,core 不依赖具体业务插件,避免 core 与插件产生反向耦合。beforeBuild、addPages 和 addRuntimeModules,因此新增文章、筛选路由和聚合数据可以同步更新。普通正文编辑仍可由 Rspress HMR 处理,完整重建只针对需要重新生成 Cogita 页面数据的输入。getPostContent,并为第三方索引实现保留摘要降级行为。plugin-posts-frontmatter 的直接依赖;后续只需在发布前持续验证独立消费者构建。content.relations 能力和 virtual-content-relations-data 模块。迁移完成后,主题仍负责声明文章插件,内容消费者插件只依赖共享能力契约;独立插件若要兼容旧版 Core,应自行提供适配层,而不应把旧文章解析实现重新带入核心插件包。