本指南总结让 Cogita 站点易于演进的约定:清晰的仓库边界、精简配置、可组合的主题和插件、可靠的内容,以及可诊断的部署路径。
站点内容应与框架包分离。站点仓库负责配置、内容、资源和本地扩展,Cogita 包作为依赖安装:
手册文档使用 contentDir,文章集合使用 posts.dir。Knowledge 可以同时展示两种内容,而 Docs 通常以 contentDir 为主要来源。
选择一种主要信息架构并保持 URL 稳定:日志或发布归档适合按时间组织,手册或参考资料适合按主题组织,只有在确实需要两种导航时才采用浅层混合结构。不要把临时工作流状态编码进公开 URL;草稿应使用专用目录或 frontmatter。
从最小可用配置开始,只在站点需要时增加能力:
让 site 负责品牌、语言、URL 和 base path;contentDir 与 posts 负责内容来源;theme 负责渲染系统;插件配置放在各自命名空间。
新安装应以英文作为默认回退,让消息字典不完整时站点仍可用:
@cogita/plugin-i18n 只翻译主题和插件的界面文案,不翻译 Markdown、文章标题或用户元数据。多语言内容应按站点内容策略独立编写和发布。
为读者和机器同时维护简洁标题、有用描述和稳定日期。页面使用一个 # 标题和有意义的 ## 层级;把结论放在前面;用短段落和列表提升可扫描性;为信息性图片提供替代文本;链接到下一篇相关页面,不要重复整段说明。
草稿不要进入生产构建。使用与生产相同的 base path 和主题进行本地预览:
把主题视为渲染边界,把插件视为能力提供者:
主题声明所需插件和布局;插件校验自己的命名空间,未配置时返回 null,并通过稳定虚拟模块提供构建数据。需要被多个主题复用的能力应做成插件;改变页面组成的能力应做成主题扩展;站点业务规则留在站点仓库。
静态站点最有价值的性能工作通常是减少无效构建,并保持输出可缓存:优先使用共享 ContentIndex,只有需要正文的功能才读取正文,并尽可能在元数据中保存图片尺寸和替代文本。
GitHub Pages 流程应构建站点、检查暂存产物并发布生成目录。重点确认 site.base 与项目路径一致,导航链接都能解析,资源使用同一前缀,并且输出包含英文入口和主题 Demo。自定义域名通常使用 /,项目 Pages 则使用仓库路径。
站点描述、页面描述和社交图片分别承担不同职责,不要把同一段描述复制到所有页面。使用语义化标题、可见焦点状态、键盘可操作控件以及搜索和语言控件的标签,不要只用颜色表达状态。
页面空白时先检查首个 SSG 错误,确认全局 UI 可在 Node 静态渲染中安全执行。主题或插件无法解析时,先重新构建工作区包,再核对包名和主题声明的依赖。