本文面向 Cogita 框架、主题和插件贡献者,介绍本地开发、质量检查、测试和发布验证。
使用 CLI 创建博客、文档或知识库站点:
博客模板读取 posts/,文档模板读取 content/,Knowledge 模板同时读取两种内容。生成后运行 pnpm run dev。
要求:Node.js >= 18、pnpm >= 9、TypeScript ^5。安装依赖:
常用命令:
修改包源代码后,先运行 pnpm run build:packages,避免文档站或测试消费过期的 dist 输出。preview:lucid 默认读取同级的 cogita-blog 仓库,也可以通过 COGITA_BLOG_DIR 指定其他内容仓库。
demos/ 包含四个独立 Cogita 消费者,而不是现有博客的镜像:Docs、Lucid、Editorial 和 Knowledge。运行 pnpm run demo 构建四个 Demo 并在 http://localhost:3100/ 提供入口。每个新增官方主题都应添加独立 Demo 和索引项,方便贡献者验证消费者配置。
推荐结构:
插件应使用工厂模式,读取自己的配置命名空间;禁用或缺少能力时返回 null;通过 getCogitaBuildContext 使用共享索引、布局和日志;通过能力声明与虚拟模块提供稳定契约;并覆盖默认值、禁用配置、缺少能力和非法配置测试。
主题组合页面布局、样式和默认插件能力。入口应声明 pageLayouts、全局样式和 plugins,不要在主题中校验插件选项或把站点内容写死在布局里。
项目使用 Biome,而不是 ESLint 或 Prettier:
代码注释、JSDoc、TODO 和 FIXME 使用中文;保持 TypeScript 严格模式;遵循 Conventional Commits。完整验证包括包构建、docs-site 构建、检查和测试;发布前再运行 pnpm run check:release。
代码变化时同步更新包 README 与 docs-site/content 对应页面;发布包变化时添加 Changeset;不要手动修改版本号。提交前确认分支基于最新 main、包构建和检查通过、文档站构建成功,且没有私有内容或凭据进入框架仓库。