Git Times
When writing a content rich site a common requirement is to show when some content was published and when it was last updated. Instead of tracking this manually for each entry in your content collections, this library allows you to retrieve those dates from your Git history.
Git is only necessary during build, so you can deploy your site anywhere. Even on platforms that don’t provide Git, access to binaries or native modules (yes, even on Cloudflare).
How to use
-
Install
@inox-tools/content-utils
:Terminal - <project root> astro add @inox-tools/content-utils -
Import the time getter you want from
@it-astro:content/git
:src/pages/blog/[...slug].astro ---import { getLatestCommitDate, getOldestCommitDate } from '@it-astro:content/git';--- -
Get the time from any collection entry using the same signature as Astro’s
getEntry
:src/pages/blog/[...slug].astro ---import { getOldestCommitDate } from '@it-astro:content/git';const { slug } = Astro.params;const entry = await getEntry('blog', slug);const creationDate = await getOldestCommitDate('blog', slug);// ORconst creationDate = await getOldestCommitDate(entry);---
API
getLatestCommitDate
Returns the commit time of the last commit that changed the selected entry.
If the entry has not been commited yet, this function returns the current time.
getOldestCommitDate
Returns the commit time of the first commit that created the selected entry.
If the entry has not been commited yet, this function returns the current time.
Hooks
Integrations can hook into the lifecycle of the content collections git times, this allows you to:
- Ignore some collection entries;
- Override times for entries.
@it/content:git:listed
This hook is called on astro build
once the collection entries tracked by Git are listed.
import { defineIntegration } from 'astro-integration-kit';import '@inox-tools/content-utils';
export default defineIntegration({ name: 'your-integration', setup() { return { hooks: { '@it/content:git:listed': ({ trackedFiles, ignoreFiles, logger }) => { // your code }, }, }; },});
trackedFiles
Type: string[]
List of all content collection entry files that are tracked by Git. The values are in
ignoreFiles
Type: (files: string[]) => void
A callback to exclude files from tracking. Values that is not on trackedFiles
are ignored.
logger
Type: AstroIntegrationLogger
A standard AstroIntegrationLogger
, configured the same as for the official Astro hooks.
@it/content:git:resolved
This hook is called twice for each tracked content collection entry, once for each git time that is resolved (oldest and latest).
import { defineIntegration } from 'astro-integration-kit';import '@inox-tools/content-utils';
export default defineIntegration({ name: 'your-integration', setup() { return { hooks: { '@it/content:git:resolved': ({ age, file, resolvedDate, overrideDate, logger }) => { // your code }, }, }; },});
age
Type: 'oldest' | 'latest'
Which age of the entry is being resolved, oldest
, latest
.
file
Type: string
Absolute path to the content collection entry file.
resolvedDate
Type: Date
Date resolved from the Git history.
overrideDate
Type: (newDate: Date) => void
Callback function to override the resolved date.