Docs changelog (RSS and HTML)

[angelovdev]

Is there a way to allow users to track changes of the documentation using RSS and perhaps displaying it on a page somewhere?

As a user, I might visit the docs after 1 month and I can't know what's new and what isn't. I know badges exist but they are manual and you have to decide when something isn't new anymore.

[delucis]

Interesting idea! Definitely not something that’s available out of the box. The closest thing currently is our last-update date feature, which uses git history to display a date in the page footer that shows when it was last changed.

In theory, it would be possible to use a similar technique.

The simplest way currently might be to do something with git log and generate it automatically with that.

For example:

---
// src/pages/docs-changes.astro
import { spawnSync } from 'node:child_process';
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';

// Use `git log` to get a list of all changes to the docs.
// The format is:
// ~~~~~~~~~~                      <= separator                     
// 1709037743                      <= commit time (seconds since Unix epoch)
// Commit message                  <= the commit message
//
// src/content/docs/example.md.    <= paths to one
// ...                             <= or more files changed in this commit
const separator = '~~~~~~~~~~';
const result = spawnSync(
	'git',
	['log', `--format=${separator}%n%ct%n%s`, '--name-only', 'src/content/docs/**'],
	{ encoding: 'utf-8' }
);
// Iterate over the lines of git logging to generate a structured array of entries:
const log = result.stdout
	.split(separator)
	.filter(Boolean)
	.map((logEntry) => logEntry.split('\n').filter(Boolean))
	.map(([timestamp, message, ...files]) => ({
		date: new Date(parseInt(timestamp) * 1000),
		message,
		files: files.map((path) => path.replace('src/content/docs/', '')),
	}))
	.filter(({ files }) => files.length);

// We now have an array of `{ message: string; date: Date; files: string[] }`
// and we can use it to build our page.
---

<StarlightPage frontmatter={{ title: 'Documentation Changes' }}>
	<ul>
		{
			log.map((entry) => (
				<li>
					{entry.date.toLocaleDateString('en', { dateStyle: 'medium' })}: {entry.message}
					<ul>
						{entry.files.map((path) => (
							<li>{path}</li>
						))}
					</ul>
				</li>
			))
		}
	</ul>
</StarlightPage>

For example, using this for the Starlight docs we’d get a page a bit like this:

Obviously relies on you writing nice commit messages. You could extend from here to change formatting, add links etc. OR instead of a single page, use a similar technique to generate a small per-page changelog listing recent commits for the current page.

[angelovdev]

Impressive! And how about RSS?

[delucis]

You could probably use a similar git technique with Astro’s RSS package!

https://docs.astro.build/en/guides/rss/

[Fryuni]

Chris!!!!

That was in my list to turn into an integration!!

Would be great if someone else did it before me though 😁

[angelovdev]

For anyone that does not need transforming RSS for commits, GitHub and GitLab support RSS feeds for commits.

GitHub: https://github.com/withastro/starlight/commits/main.atom

GitLab: https://gitlab.com/gitlab-org/gitlab-foss/-/commits/master?format=atom

[Fryuni]

It also works for filtering by directory.

A feed of all Starlight commits changing the docs content: https://github.com/withastro/starlight/commits/main/docs/src/content/docs.atom