Git content source adapter

@cogita/plugin-content-source-git reads an independently checked-out Markdown directory, adds it to the shared ContentIndex, and generates static pages for entries with bodies. It does not run git clone, git pull, or any other network operation. GitHub Actions, submodules, or the deployment platform own the repository version, credentials, and update policy.

Configuration

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',
    }),
  ],
});

The adapter scans md and mdx by default and maps title, description, dates, tags, categories, and image fields. Non-Markdown files are published under the isolated /external-content/<source>/... namespace. Only relative resource references that match a real file are rewritten; external URLs and missing references remain unchanged.

Boundary with JSON content

  • Git content is for Markdown source managed by version control; deployment chooses the commit to check out.
  • JSON content is for stable snapshots generated by a CMS, API, or another system.
  • Both sources feed search, tags, content relations, and diagnostics through ContentIndex.

When a source provides getContent, Core generates an additional page for the body. Custom sources can publish assets through getAssets, and load, getContent, and getAssets should support Core's parallel calls.

GitHub Actions integration

- 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 }}

Private content repositories need a read-only COGITA_CONTENT_TOKEN; never place it in configuration or commit it. Pinning COGITA_CONTENT_REF to a branch, tag, or commit makes builds traceable. See examples/github-actions/external-content-deploy.yml for the complete workflow.

For the Chinese version, see Git 内容源适配器.