Git 内容源适配器
@cogita/plugin-content-source-git 读取部署流程已经 checkout 好的独立 Markdown 内容目录,将其接入统一 ContentIndex,并为有正文的条目生成静态页面。它不执行 git clone、git pull 或其他网络操作,版本、凭据和更新策略由部署平台管理。
配置
import { defineConfig } from '@cogita/core';
import { createGitContentSource } from '@cogita/plugin-content-source-git';
export default defineConfig({
contentSources: [
createGitContentSource({
id: 'team-notes',
directory: '../team-notes',
kind: 'document',
routePrefix: 'notes',
}),
],
});
适配器默认扫描 md 和 mdx 文件,并映射标题、描述、日期、标签、分类和图片字段。非 Markdown 文件会发布到隔离的 /external-content/<source>/... 命名空间;只有能匹配真实文件的相对资源引用会被改写,外部 URL 和不存在的引用保持不变。
与 JSON 内容源的边界
- Git 内容源适合由版本控制系统管理的 Markdown 原文,部署流程负责 checkout 某个 commit;
- JSON 内容源适合 CMS、API 或其他系统生成的稳定快照;
- 两者都通过
ContentIndex 提供给搜索、标签、内容关系和诊断插件。
只要内容源提供 getContent,Core 会自动生成正文附加页面;自定义内容源还可以通过 getAssets 发布资源。适配器的 load、getContent 和 getAssets 应支持 Core 的并行调用。
GitHub Actions 接入
- name: Checkout content repository
uses: actions/checkout@v4
with:
repository: ${{ vars.COGITA_CONTENT_REPOSITORY }}
ref: ${{ vars.COGITA_CONTENT_REF || 'main' }}
path: git-content
token: ${{ secrets.COGITA_CONTENT_TOKEN || github.token }}
私有内容仓库需要具备读取权限的 COGITA_CONTENT_TOKEN,不要把令牌写入配置或提交到仓库。固定 COGITA_CONTENT_REF 可以让站点构建具备可回溯性。完整示例见 examples/github-actions/external-content-deploy.yml。