API 参考
本文档集中说明 Cogita 的公共配置、主题、插件、内容索引和运行时模块接口。英文页面是默认入口;本页保留中文说明。
核心 API
@cogita/core
defineConfig(config: CogitaConfig): CogitaConfig
定义类型安全的站点配置。它返回同一个配置对象,供 TypeScript 和 IDE 校验。
import { defineConfig } from '@cogita/core';
export default defineConfig({
site: {
title: '我的文档',
description: '项目使用手册',
},
theme: '@cogita/theme-docs',
});
loadCogitaConfig(root?: string): Promise<CogitaConfig>
从项目根目录异步加载 cogita.config.ts、cogita.config.js 或 cogita.config.mjs。未传入 root 时使用 process.cwd()。
createRspressConfig(cogitaConfig: CogitaConfig, root: string): Promise<UserConfig>
将 Cogita 配置转换为 Rspress 配置,期间会解析主题、实例化主题声明的插件并合并配置。
配置接口
interface CogitaConfig {
site?: SiteConfig;
theme?: string;
contentDir?: string;
contentSources?: readonly ContentSource[];
plugins?: CogitaPluginFactory[];
themeConfig?: ThemeConfig;
builderConfig?: BuilderConfig;
locales?: readonly SiteLocale[];
languageParity?: LanguageParityConfig;
}
contentDir 用于普通 Markdown 文档。contentSources 用于接入 Git、API 或其他知识库;Core 会把这些条目统一纳入 ContentIndex。有正文读取器的外部条目还会生成静态页面。
SiteConfig
interface SiteConfig {
title?: string;
description?: string;
lang?: string;
icon?: string;
base?: string;
}
ContentSource
内容源至少需要在站点内唯一的 id 和 load 函数。条目应提供 kind、title、filePath、route 和 updateDate;实现 getContent 后,全文搜索、内容关系和静态页面都可以消费该来源。
import type { ContentSource } from '@cogita/core';
const notes: ContentSource = {
id: 'notes',
async load() {
return [{
kind: 'document',
title: '远程笔记',
filePath: 'source://notes/remote-note',
route: '/notes/remote-note',
updateDate: '2026-08-25T00:00:00.000Z',
}];
},
async getContent(entry) {
return `# ${entry.title}\n\n来自外部知识库的正文。`;
},
};
主题与构建配置
ThemeConfig 和 BuilderConfig 分别透传 Rspress 的 themeConfig 和 builderConfig。站点级多语言路由使用 locales 声明语言列表;languageParity 用于配置翻译缺失时的回退策略。
主题 API
interface CogitaTheme {
name: string;
pageLayouts: {
home: string;
};
globalStyles?: string[];
plugins?: CogitaPluginFactory[];
}
主题负责布局和视觉边界,并通过 plugins 声明需要的功能。配置验证和内容扫描属于插件或 Core,不应下沉到布局组件。
export function getThemeConfig(): CogitaTheme {
return {
name: '@cogita/theme-lucid',
pageLayouts: { home: './layouts/Home.js' },
plugins: [pluginPostsFrontmatter, pluginTags],
};
}
布局组件使用 LayoutProps,其中包含 routePath、Rspress config、页面数据和可选的 children。
插件 API
type CogitaPluginFactory = (
config: CogitaPluginConfig,
) => RspressPlugin | RspressPlugin[] | null | undefined;
插件工厂接收 Core 增强后的配置。插件应验证自己的配置;未启用时返回 null,避免把无效插件注册到 Rspress。
export const pluginExample: CogitaPluginFactory = (config) => {
if (!config.example?.enabled) return null;
return {
name: '@cogita/plugin-example',
async beforeBuild() {},
};
};
常用生命周期包括 beforeBuild、afterBuild、addPages、addRuntimeModules 和 config。新增页面使用 routePath、Markdown content 和组件 filepath 描述。站点自定义插件在 cogita.config.ts 的 plugins 数组中注册。
插件的构建上下文通过 getCogitaBuildContext(config) 获取,包含 root、cwd、contentIndex、主题布局路径和构建元数据。完整的注册、能力和版本规则见插件 API 规范。
内容索引与共享类型
interface ContentIndex {
getPosts(): Promise<readonly ContentPost[]>;
getEntries?(): Promise<readonly ContentEntry[]>;
getPostContent?(filePath: string): Promise<string>;
invalidate?(): void;
}
Core 创建惰性索引,多个插件共享同一个扫描结果。getEntries 覆盖文章、contentDir 文档和外部内容源;正文读取按需缓存。索引契约和外部内容源边界详见内容索引设计。
文章引用统一使用 @cogita/shared 的 ContentPostReference。主题如果只需要渲染文章列表,应消费插件提供的运行时模块,不要重复扫描文件系统。
虚拟模块
virtual-posts-data
由文章插件提供文章数据和 contentDataVersion:
declare module 'virtual-posts-data' {
export const contentDataVersion: 1;
export const allPosts: PostFrontmatter[];
}
virtual-content-relations-data
由内容关系插件提供出链、反向链接和相关文章查询:
declare module 'virtual-content-relations-data' {
export const cogitaVirtualModuleVersion: 1;
export function getBacklinks(route: string): ContentRelationLink[];
export function getOutgoingLinks(route: string): ContentRelationLink[];
export function getRelatedContent(route: string, limit?: number): ContentRelationLink[];
}
插件应从 COGITA_VIRTUAL_MODULE_IDS 获取模块 ID,并用 createCogitaVirtualModule(source) 写入公共版本头。主题在版本不兼容时应明确降级或输出诊断。
生命周期与错误处理
配置加载、主题解析和插件实例化之后,Core 执行 beforeBuild、addPages、addRuntimeModules,再交给 Rspress 构建,最后执行 afterBuild。开发服务器会在相关输入变化时重新加载配置并重建插件数据。
CLI 会把配置缺失、加载失败和主题解析失败转换为稳定诊断码,例如 COGITA_CONFIG_NOT_FOUND。插件应在配置错误时给出明确提示,并在可选能力未配置时优雅降级。
相关资源