Configuration

Both compiler plugins accept the same settings. Start with the minimal setup; most sites need only repository.url.

Required and optional settingsCopy Anchor Link

repository.url must have no credentials, query, or fragment. It is provided explicitly and is never inferred from remote credentials. Local paths and account-matching selectors stay in the build process.

Author mappingsCopy Anchor Link

const options = {
  repository: { url: 'https://github.com/owner/repository' },
  authorMappings: [
    { gitName: 'Alex', githubUsername: 'alex' },
    { gitEmail: 'alex@example.com', githubUsername: 'alex' },
  ],
};

Every mapping needs githubUsername and at least one of gitName or gitEmail. Names and emails ignore case and surrounding whitespace. When both selectors are present, both must match. Email-qualified mappings take precedence over name-only mappings. Multiple mappings can credit the same account.

Resolution order is explicit mappings, GitHub noreply addresses, then optional GitHub lookup for unresolved primary authors. Other identities keep their Git names and initials. Account names are never guessed from arbitrary Git names or emails.

Each account counts once per commit, including co-authors. Counts reflect returned history records. Matching emails and selectors are not included in public author records.

DisplayCopy Anchor Link

Set display in plugin settings, or pass these props to GitChangelog:

const display = {
  locale: 'zh-CN',
  defaultExpanded: true,
  commitsRelativeTime: true,
};

Dates use the browser's time zone. Server HTML and the initial client render use UTC; mounted pages use the browser zone. A date near midnight may change after hydration. There is no time-zone setting.

locale controls dates and contributor names. Interface labels use the site's translation provider; see the complete Chinese setup.

Visible section headings appear in On this page. Automatic anchors avoid existing headings. Multiple manual instances need distinct IDs; a custom id gives contributors the default anchor <id>-contributors. Screens up to 640px hide commit hashes to leave space for messages.

Per-page controlsCopy Anchor Link

Extend your page schema while keeping existing compiler settings:

import { pageSchema } from 'fumadocs-core/source/schema';
import { gitChangelogSchema } from 'fumadocs-page-history/schema';

const schema = pageSchema.extend(gitChangelogSchema.shape);

Explicit contributors can be credited without commits. Pages with neither commits nor explicit contributors have no footer.

Collection optionsCopy Anchor Link

A collection's compiler options replace global options. Register the plugin there if the collection has its own options. For MDX, retain the Fumadocs preset:

import { applyMdxPreset, defineDocs } from 'fumadocs-mdx/config';
import { remarkGitChangelog } from 'fumadocs-page-history/remark';

export const docs = defineDocs({
  docs: {
    mdxOptions: applyMdxPreset({
      remarkPlugins: [
        [
          remarkGitChangelog,
          {
            repository: { url: 'https://github.com/owner/repository' },
          },
        ],
      ],
    }),
  },
});

Sätteri collections register gitChangelog(options) in docs.satteriOptions.mdastPlugins and set docs.compiler to 'satteri'.

Advanced Git controlsCopy Anchor Link

History follows Git-detected renames, includes merge changes relative to the first parent, and sorts by author date. Lightweight and annotated tags are supported. Commit Markdown links #123 to /issues/123; raw HTML is disabled.

Copied documentsCopy Anchor Link

When compilation uses a copy of your documents, declare where it belongs in the checkout:

{
  repository: {
    url: 'https://github.com/owner/repository',
    directory: '/workspace/repository',
  },
  content: {
    directory: '/workspace/document-copy',
    pathInRepository: 'apps/docs/content',
  },
}

A copied guide.mdx reads history for apps/docs/content/guide.mdx. The package resolves native Windows or POSIX disk paths, handles symlinked directories, and produces Git-relative paths internally. Files outside content.directory and repository paths that escape the checkout are rejected. Use pathInRepository: '.' when the content directory represents the repository root.

Optional GitHub lookupCopy Anchor Link

Ordinary emails can be associated with GitHub accounts during compilation:

{
  repository: { url: 'https://github.com/owner/repository' },
  github: { token: process.env.GITHUB_TOKEN },
}

Only unresolved primary authors are queried. Commits must already exist in that GitHub repository. Co-authors are not assigned the primary author's account. Provide the token to the documentation build step; public repositories need no additional repository permission, and fine-grained tokens for private repositories need Contents: read.

Successful mappings are cached for seven days; unavailable or unassociated commits for five minutes. Network failures and rate limits are not persisted. Cache keys hash identity emails and are separated by repository. Tokens and emails are never included in pages or cached records.

Requests are serialized within each reader, with deduplication and shared disk caching. Workers have separate budgets and may duplicate cold-cache requests. Authentication failures, rate limits, server errors, and timeouts stop further requests in that reader; cached mappings remain available. Lookup or cache failures fall back to local author information, with at most one warning per reader. Omit github for offline builds.