feat: add date parsing to keep-a-changelog

.changeset/clean-dates-smile.md

@@ -0,0 +1,5 @@
+---
+'starlight-changelogs': minor
+---
+
+Extracts release dates from version headings when using the Keep a Changelog provider.

docs/src/content/docs/providers/keep-a-changelog.mdx

@@ -6,7 +6,8 @@ description: Learn how to display changelogs using the Keep a Changelog format w
 The Starlight Changelogs plugin uses Astro’s [content collections](https://docs.astro.build/en/guides/content-collections/), which are configured in the `src/content.config.ts` file.
 The provided `changelogsLoader()` loader can be used to load one or more changelog files from different providers, including [Keep a Changelog](https://keepachangelog.com).
 
-[Unreleased versions](https://keepachangelog.com/en/1.1.0/#effort) are ignored and release dates are stripped from version titles by default.
+[Unreleased versions](https://keepachangelog.com/en/1.1.0/#effort) are ignored.
+Release dates using the ISO 8601 `YYYY-MM-DD` format are automatically extracted from [standard version headings](https://keepachangelog.com/en/1.1.0/#confusing-dates) and stripped from version titles.
 
 Changelog files using the Keep a Changelog format can be loaded by using the `provider: 'keep-a-changelog'` option.
 

packages/starlight-changelogs/providers/keep-a-changelog.ts

@@ -18,10 +18,17 @@ export const KeepAChangelogProviderConfigSchema = ProviderBaseConfigSchema.exten
 })
 
 const provider: MarkdownProviderConfig['provider'] = { name: 'keep-a-changelog', label: 'Keep a Changelog' }
+const versionHeadingRegex = /^(?<version>.+) - (?<date>\d{4}-\d{2}-\d{2})$/
 const markdown: MarkdownProviderConfig['markdown'] = {
   ignoredVersions: ['Unreleased'],
   process({ title }) {
-    return title.replace(/(?<version>.*?)\s-\s?\d{4}-\d{2}-\d{2}\s*$/, '$<version>')
+    const match = versionHeadingRegex.exec(title)
+    const date = match?.groups?.['date']
+
+    return {
+      title: match?.groups?.['version'] ?? title,
+      ...(date ? { date: new Date(`${date}T00:00:00`) } : {}),
+    }
   },
   versionHeadingLevel: 2,
 }

packages/starlight-changelogs/providers/markdown.ts

@@ -144,20 +144,24 @@ function parseMarkdownVersion(
 ): VersionDataEntry | undefined {
   let title = version.title
 
-  const process = config.process ?? config.markdown.process
+  const process = config.process
 
   if (process) {
     const processedTitle = process({ title })
     if (!processedTitle) return
     title = processedTitle
   }
 
+  const processed = config.markdown.process?.({ title: version.title })
+  if (!process) title = processed?.title ?? title
+
   const [id, slug] = slugifyVersion(config, title)
 
   return {
     id,
     body: toMarkdown({ type: 'root', children: version.nodes as RootContent[] }),
     base: config.base,
+    ...(processed?.date ? { date: processed.date } : {}),
     index,
     provider: config.provider,
     slug,
@@ -177,12 +181,8 @@ export interface MarkdownProviderConfig extends z.output<typeof ProviderBaseConf
   markdown: {
     /** Version titles to ignore when parsing the changelog (applied after `process` function). */
     ignoredVersions?: string[]
-    /**
-     * An optional default function called if no `process` function is defined in the main provider configuration.
-     *
-     * @see ProviderBaseConfigSchema
-     */
-    process?: z.output<typeof ProviderBaseConfigSchema>['process']
+    /** An optional function called to process data from the original version title. */
+    process?: (context: { title: string }) => MarkdownProcessResult
     /** The heading level used to indicate version entries in the changelog. */
     versionHeadingLevel: number
   }
@@ -192,6 +192,11 @@ export interface MarkdownProviderConfig extends z.output<typeof ProviderBaseConf
 
 type ChangelogContent = { modified: false } | { modified: true; content: string }
 
+interface MarkdownProcessResult {
+  date?: Date
+  title: string
+}
+
 interface MarkdownVersion {
   title: string
   nodes: Node[]

packages/starlight-changelogs/tests/keep-a-changelog.test.ts

@@ -50,6 +50,12 @@ describe('fs', () => {
     expect(versions[3]?.data.title).toBe('0.3.0')
   })
 
+  test('extracts release dates from standard version headings', () => {
+    const version = store.values()[0]
+
+    expect(version?.data.date).toEqual(new Date('2023-03-05T00:00:00'))
+  })
+
   test('loads the first version', () => {
     const version = store.values().at(-1)