feat: automated revision history with commit messages

Replaces manual history tracking with automated revision tracking based on git commits. The revisions.json file is now part of 11ty's data layer, making revision history accessible to templates. Each revision now includes the commit message, and a new revision-history component displays this information on articles.

Author: limulus

.github/workflows/cd.yaml

@@ -58,7 +58,7 @@ jobs:
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add "www/**/*.md" .revisions.json
+          git add "www/**/*.md" www/_data/revisions.json
           git diff --cached --quiet || \
             git commit -m "chore: auto-generate teasers [skip ci]" && git push --no-verify
       - run: npm run build

11ty/revisions.ts

@@ -4,7 +4,7 @@ import { readFile, writeFile } from 'node:fs/promises'
 
 export const HASH_ALGORITHM = 'shake128'
 export const HASH_OUTPUT_BYTES = 6
-export const REVISIONS_PATH = '.revisions.json'
+export const REVISIONS_PATH = 'www/_data/revisions.json'
 
 export interface Revision {
   hash: string
@@ -14,6 +14,7 @@ export interface Revision {
   separator: string
   date: string
   commit: string
+  message?: string
 }
 
 export interface RevisionEntry {
@@ -63,6 +64,16 @@ export function getCurrentCommit(): string {
   }
 }
 
+export function getCommitMessage(commit: string): string {
+  try {
+    return execFileSync('git', ['log', '--format=%s', '-1', commit], {
+      encoding: 'utf-8',
+    }).trim()
+  } catch {
+    return ''
+  }
+}
+
 export async function loadRevisions(path: string = REVISIONS_PATH): Promise<RevisionsFile> {
   try {
     const content = await readFile(path, 'utf-8')

11ty/update-revisions.ts

@@ -6,6 +6,7 @@ import {
   HASH_ALGORITHM,
   HASH_OUTPUT_BYTES,
   computeHash,
+  getCommitMessage,
   getCurrentCommit,
   hashFields,
   loadRevisions,
@@ -37,6 +38,7 @@ async function main() {
     const latestRevision = entry.revisions[entry.revisions.length - 1]
 
     if (!latestRevision || latestRevision.hash !== hash) {
+      const message = getCommitMessage(commit)
       entry.revisions.push({
         hash,
         algorithm: HASH_ALGORITHM,
@@ -45,6 +47,7 @@ async function main() {
         separator: '\\n',
         date: new Date().toISOString(),
         commit,
+        ...(message && { message }),
       })
       revisions[filePath] = entry
       revisionCount++

README.md

@@ -123,12 +123,6 @@ Most content should be written in a Markdown file under the `www` directory.
 - `subhead`: A subhead or alternate title that appears below the title of an article. It is
   used as the page meta description if present.
 - `date`: The date and time of first publication, in ISO 8601 format
-- `history`: A list of significant edits to the page. The most recent edit must be listed
-  first. Each entry in this list should contain:
-  - `date`: The date and time of the edit, in ISO 8601 format
-  - `change`: ⚠️ Not yet implemented but the idea would be to be an annotation that could be
-    included on the page and RSS feed. This would remain optional for edits that are just
-    fixes for typos or to fix search engine indexing.
 - `image`: Photo identifier used only for the preview images on article cards and Open Graph
   tags
 - `teaser`: A short description of the article or page used in previews and page metadata.

bin/backfill-revision-messages.ts

@@ -0,0 +1,31 @@
+import {
+  getCommitMessage,
+  loadRevisions,
+  saveRevisions,
+  REVISIONS_PATH,
+} from '../11ty/revisions.ts'
+
+async function main() {
+  const revisions = await loadRevisions()
+  let updated = 0
+
+  for (const entry of Object.values(revisions)) {
+    for (const revision of entry.revisions) {
+      if (!revision.message) {
+        const message = getCommitMessage(revision.commit)
+        if (message) {
+          revision.message = message
+          updated++
+        }
+      }
+    }
+  }
+
+  await saveRevisions(revisions, REVISIONS_PATH)
+  console.log(`Done. ${updated} revision message(s) backfilled.`)
+}
+
+main().catch((error: unknown) => {
+  console.error(error)
+  process.exit(1)
+})

www/_data/eleventyComputed.js

@@ -69,6 +69,15 @@ export default {
     }
   },
 
+  // ISO date of the most recent revision, if modified after creation
+  lastModified: (data) => {
+    const filePath = data.page?.inputPath?.replace(/^\.\//, '')
+    const revs = filePath && data.revisions?.[filePath]?.revisions
+    if (revs?.length > 1) {
+      return revs.at(-1).date
+    }
+  },
+
   // Calculate reading time for articles
   readingTime(data) {
     if (data.tags?.includes('article') && data.page?.rawInput) {