Add `lastUpdated` global and frontmatter options (#256)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

8 files changed, 70 insertions, 4 deletions

diff --git a/.changeset/six-fishes-taste.md b/.changeset/six-fishes-taste.md
new file mode 100644
index 00000000..7ec2df40
--- /dev/null
+++ b/.changeset/six-fishes-taste.md
@@ -0,0 +1,13 @@
+---
+"@astrojs/starlight": minor
+---
+
+Add new global `lastUpdated` option defaulting to `false` to define whether or not the last updated date is shown in the footer. A page can override this setting or the generated date using the new `lastUpdated` frontmatter field.
+
+⚠️ Breaking change. Starlight will no longer show this date by default. To keep the previous behavior, you must explicitly set `lastUpdated` to `true` in your configuration.
+
+```diff
+starlight({
++ lastUpdated: true,
+}),
+```
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 51ab0697..7b3a9854 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -112,6 +112,7 @@ export default defineConfig({
           autogenerate: { directory: 'reference' },
         },
       ],
+      lastUpdated: true,
     }),
   ],
   image: { service: { entrypoint: 'astro/assets/services/sharp' } },
diff --git a/docs/src/content/docs/reference/configuration.md b/docs/src/content/docs/reference/configuration.md
index a291ae53..b61aa560 100644
--- a/docs/src/content/docs/reference/configuration.md
+++ b/docs/src/content/docs/reference/configuration.md
@@ -319,3 +319,12 @@ interface HeadConfig {
   content?: string;
 }
 ```
+
+### `lastUpdated`
+
+**type:** `boolean`  
+**default:** `false`
+
+Control whether the footer shows when the page was last updated.
+
+By default, this feature relies on your repository’s Git history and may not be accurate on some deployment platforms performing [shallow clones](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt). A page can override this setting or the Git-based date using the [`lastUpdated` frontmatter field](/reference/frontmatter/#lastupdated).
diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md
index 66620541..14dded59 100644
--- a/docs/src/content/docs/reference/frontmatter.md
+++ b/docs/src/content/docs/reference/frontmatter.md
@@ -133,3 +133,16 @@ interface HeroConfig {
   }>;
 }
 ```
+
+### `lastUpdated`
+
+**type:** `Date | boolean`
+
+Overrides the [global `lastUpdated` option](/reference/configuration/#lastupdated). If a date is specified, it must be a valid [YAML timestamp](https://yaml.org/type/timestamp.html) and will override the date stored in Git history for this page.
+
+```md
+---
+title: Page with a custom last update date
+lastUpdated: 2022-08-09
+---
+```
diff --git a/packages/starlight/components/Footer.astro b/packages/starlight/components/Footer.astro
index c550d31d..d5925c1f 100644
--- a/packages/starlight/components/Footer.astro
+++ b/packages/starlight/components/Footer.astro
@@ -24,7 +24,20 @@ const prevNextLinks = getPrevNextLinks(sidebar);
         <EditLink data={entry.data} id={entry.id} {locale} />
       )
     }
-    <LastUpdated id={entry.id} {lang} {locale} />
+    {
+      (entry.data.lastUpdated ?? config.lastUpdated) && (
+        <LastUpdated
+          id={entry.id}
+          {lang}
+          lastUpdated={
+            typeof entry.data.lastUpdated !== 'boolean'
+              ? entry.data.lastUpdated
+              : undefined
+          }
+          {locale}
+        />
+      )
+    }
   </div>
   <PrevNextLinks {...prevNextLinks} {dir} {locale} />
 </footer>
diff --git a/packages/starlight/components/LastUpdated.astro b/packages/starlight/components/LastUpdated.astro
index c1e0476d..5a2c42e7 100644
--- a/packages/starlight/components/LastUpdated.astro
+++ b/packages/starlight/components/LastUpdated.astro
@@ -8,19 +8,22 @@ import { useTranslations } from '../utils/translations';
 interface Props {
   id: CollectionEntry<'docs'>['id'];
   lang: string;
+  lastUpdated: Date | undefined;
   locale: string | undefined;
 }
 
-const { id, lang, locale } = Astro.props;
+const { id, lang, lastUpdated, locale } = Astro.props;
 const t = useTranslations(locale);
 
 const currentFilePath = fileURLToPath(
   new URL('src/content/docs/' + id, project.root)
 );
 
-let date: Date | undefined;
+let date = lastUpdated;
 try {
-  ({ date } = getFileCommitDate(currentFilePath, 'newest'));
+  if (!date) {
+    ({ date } = getFileCommitDate(currentFilePath, 'newest'));
+  }
 } catch {}
 ---
 
diff --git a/packages/starlight/schema.ts b/packages/starlight/schema.ts
index 690e1555..4bdbbc60 100644
--- a/packages/starlight/schema.ts
+++ b/packages/starlight/schema.ts
@@ -113,5 +113,11 @@ export function docsSchema() {
             .default([]),
         })
         .optional(),
+      
+      /**
+       * The last update date of the current page.
+       * Overrides the `lastUpdated` global config or the date generated from the Git history.
+       */
+      lastUpdated: z.union([z.date(), z.boolean()]).optional(),
     });
 }
diff --git a/packages/starlight/utils/user-config.ts b/packages/starlight/utils/user-config.ts
index af756d32..bd7ca026 100644
--- a/packages/starlight/utils/user-config.ts
+++ b/packages/starlight/utils/user-config.ts
@@ -235,6 +235,14 @@ const UserConfigSchema = z.object({
    * })
    */
   customCss: z.string().array().optional().default([]),
+
+  /** Define if the last update date should be visible in the page footer. */
+  lastUpdated: z
+    .boolean()
+    .default(false)
+    .describe(
+      'Define if the last update date should be visible in the page footer.'
+    ),
 });
 
 export const StarlightConfigSchema = UserConfigSchema.strict().transform(