Git Metadata

The @bdocs/plugin-git-meta package ships two plugins that read your repository's history: one for page last-updated dates and one for contributor lists. Both share a single git log scan, so enabling them together costs almost nothing extra.

Concepts & Architecture

How it works

1. One scan per build. The package runs a single git log --name-only over the documentation directory and aggregates the result per file.
2. HEAD-keyed cache. The scan is cached by repository root and HEAD. The second plugin reuses the first plugin's result, and a dev server automatically sees new commits without a restart.
3. routes:resolved enrichment. Both plugins run through the documented routes:resolved hook, after routes are crawled, normalized, and sorted. The enriched metadata reaches the SSG route table and the client virtual:boltdocs-routes module.
4. Layout rendering. Routes carry lastUpdated and contributors; the default page footer renders both. Custom themes can read them with useRoutes().

Only non-merge commits are considered. Dates use the committer date (%cI), and contributor identities are grouped by email before the optional name merge.

What each plugin adds

Installation

pnpm add @bdocs/plugin-git-meta

import { defineConfig } from "boltdocs";
import { contributorsPlugin, lastUpdatedPlugin } from "@bdocs/plugin-git-meta";

export default defineConfig({
  plugins: [lastUpdatedPlugin(), contributorsPlugin()],
});

Both plugins are independent. Enable only the one you need.

Configuration

lastUpdatedPlugin

lastUpdatedPlugin({
  overrideFrontmatter: true,
  excludePaths: ["/changelog"],
});

When fallbackToMtime is disabled and a file has no git history, the existing route date is left untouched. Explicit frontmatter dates always win unless overrideFrontmatter is enabled.

contributorsPlugin

Profiles and avatars

GitHub noreply emails (12345+user@users.noreply.github.com) automatically produce an avatar and a profile URL. For authors who commit with a personal email, map them explicitly:

contributorsPlugin({
  max: 8,
  profiles: {
    "jane@example.com": {
      name: "Jane Doe",
      avatar: "https://github.com/janedoe.png?size=64",
      url: "https://github.com/janedoe",
    },
  },
});

Profile keys are matched against the email first, then the display name. Emails are never exposed to the client unless includeEmail is enabled.

Rendering dates and contributors

The UI lives in the plugin, not in the core. contributorsPlugin() mounts the exported Contributors component on the left side of the default page footer through the page:footer:start client slot, next to the framework's last-updated date. Disable the automatic mount when you want to render it yourself:

contributorsPlugin({ autoRender: false });

Custom footers

The plugin client entry exports Contributors, LastUpdated, and a ready-made GitMetaFooter. Every component accepts class slots and render props:

import { GitMetaFooter } from "@bdocs/plugin-git-meta/client";
import { useRoutes } from "boltdocs/client";

export function MyPageFooter() {
  const { currentRoute } = useRoutes();

  return (
    <GitMetaFooter
      date={currentRoute?.lastUpdated}
      contributors={currentRoute?.contributors}
      maxContributors={5}
      labels={{ contributors: "Autores", lastUpdated: "Actualizado el" }}
      className="mt-16 border-t border-subtle pt-6"
      contributorClassNames={{ avatar: "ring-2 ring-surface" }}
    />
  );
}

Use Contributors alone when the date is rendered elsewhere:

import { Contributors } from "@bdocs/plugin-git-meta/client";

<Contributors
  contributors={currentRoute?.contributors}
  max={3}
  size="md"
  classNames={{ link: "font-medium" }}
  renderName={(contributor) => contributor.name.split(" ")[0]}
/>;

Component props

Route data shape

Each contributor is a RouteContributor:

Performance & limitations

• Shallow clones only expose the commits that were cloned. In CI, use a deeper fetch (for example fetch-depth: 0) if you want complete contributor history.
• Squash merges collapse a pull request into one commit, so the squashed author receives the credit for the whole change.
• Renames are not followed. A renamed file starts its history at the rename commit.
• Merge commits are skipped on purpose: they would attribute every file in a pull request to the person who merged it.
• No git repository in the build environment? Both plugins are no-ops; lastUpdated keeps the core's file modification time and contributors stays empty.

Troubleshooting

See also

• Lifecycle Hooks — routes:resolved and the rest of the plugin lifecycle.
• Collections — lastUpdated and author metadata in collection posts.
• Frontmatter — manually overriding lastUpdated.

Jesús Alcalá

Last updated on October 18, 2026