Metadatos de Git

El paquete @bdocs/plugin-git-meta incluye dos plugins que leen el historial de tu repositorio: uno para la fecha de última actualización de cada página y otro para la lista de contribuidores. Ambos comparten un único escaneo de git log, así que activarlos juntos apenas añade coste.

Conceptos y arquitectura

Cómo funciona

1. Un escaneo por build. El paquete ejecuta un solo git log --name-only sobre el directorio de documentación y agrega el resultado por archivo.
2. Caché por HEAD. El escaneo se cachea por raíz del repositorio y HEAD. El segundo plugin reutiliza el resultado del primero, y el servidor de desarrollo detecta commits nuevos sin reiniciar.
3. Enriquecimiento en routes:resolved. Ambos plugins usan el hook documentado routes:resolved, después de descubrir, normalizar y ordenar las rutas. Los metadatos llegan tanto a la tabla de rutas del SSG como al módulo cliente virtual:boltdocs-routes.
4. Renderizado en el layout. Las rutas exponen lastUpdated y contributors; el pie de página por defecto muestra ambos. Los temas personalizados pueden leerlos con useRoutes().

Solo se tienen en cuenta commits que no son merges. Las fechas usan la fecha de commit (%cI) y las identidades se agrupan por email antes de la fusión opcional por nombre.

Qué añade cada plugin

Instalación

pnpm add @bdocs/plugin-git-meta

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

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

Los dos plugins son independientes. Activa solo el que necesites.

Configuración

lastUpdatedPlugin

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

Si fallbackToMtime está desactivado y un archivo no tiene historial de git, la fecha existente de la ruta se mantiene. Las fechas explícitas del frontmatter siempre ganan salvo que actives overrideFrontmatter.

contributorsPlugin

Perfiles y avatares

Los emails noreply de GitHub (12345+usuario@users.noreply.github.com) generan automáticamente un avatar y una URL de perfil. Para autores que hacen commit con un email personal, mapéalos explícitamente:

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

Las claves de profiles se comparan primero con el email y después con el nombre visible. Los emails nunca se envían al cliente salvo que actives includeEmail.

Renderizar fechas y contribuidores

La UI vive en el plugin, no en el core. contributorsPlugin() monta el componente exportado Contributors en el lado izquierdo del pie de página por defecto mediante el slot de cliente page:footer:start, junto a la fecha de última actualización del framework. Desactiva el montaje automático si prefieres renderizarlo tú:

contributorsPlugin({ autoRender: false });

Pies de página personalizados

La entrada cliente del plugin exporta Contributors, LastUpdated y un GitMetaFooter listo para usar. Todos los componentes aceptan class slots y 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" }}
    />
  );
}

Usa Contributors por separado cuando la fecha se renderiza en otro sitio:

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]}
/>;

Props de los componentes

Forma de los datos

Cada contribuidor es un RouteContributor:

Rendimiento y limitaciones

• Clones superficiales: solo exponen los commits clonados. En CI, usa un fetch más profundo (por ejemplo fetch-depth: 0) si quieres el historial completo de contribuidores.
• Squash merges: convierten un pull request en un único commit, así que el autor del squash recibe el crédito de todo el cambio.
• Renombrados: no se siguen. Un archivo renombrado empieza su historial en el commit del renombrado.
• Commits merge: se omiten a propósito; atribuirían todos los archivos del pull request a quien hizo el merge.
• Sin repositorio git: ambos plugins no hacen nada; lastUpdated conserva la fecha de modificación del core y contributors queda vacío.

Solución de problemas

Ver también

• Lifecycle Hooks — routes:resolved y el resto del ciclo de vida de plugins.
• Collections — lastUpdated y metadatos de autor en posts de colecciones.
• Frontmatter — sobrescribir lastUpdated manualmente.

Jesús Alcalá

Last updated on October 18, 2026