Changelog System
Page path: admin/changelog-system.md
Original writing date: 2026-07-08
Original published date: 2026-07-08
Most recent editing date: 2026-07-08
Title changed: No
Previous title: None
What changed
implemented pages for each changelog
Compared with the previous version
@@ -1,85 +1,92 @@
---
title: Changelog System
created: 2026-07-08
published: 2026-07-08
title_changed: false
previous_titles: []
---
# Changelog System
The public changelog is generated from Markdown files in `docs/` and local Git history. It gives visitors a readable summary of documentation updates without exposing private Forgejo links, commit hashes, branches, or raw Git history.
+The generator creates two kinds of pages:
+
+| Generated file | Purpose |
+| --- | --- |
+| `docs/changelog.md` | Public index of documentation changes, newest first. |
+| `docs/changelog/*.md` | One detail page per page change, including a sanitized diff against the previous version. |
+
## Supported frontmatter
Each documentation page can include metadata at the top of the file:
```yaml
---
title: Server Setup
created: 2026-06-10
published: 2026-06-14
title_changed: false
previous_titles: []
---
```
Supported fields:
| Field | Meaning | Fallback |
| --- | --- | --- |
| `title` | Public page name shown in the changelog. | First `# Heading`, then filename. |
| `created` | Original writing date. | First Git commit date for the file. |
| `published` | Original posting or published date. | First Git commit date for the file. |
| `title_changed` | Whether the current title replaced an older title. | `false` |
| `previous_titles` | Earlier page titles. | Empty list. |
## Marking a title change
When a page title changes, update the page frontmatter:
```yaml
title: New Page Title
title_changed: true
previous_titles:
- Old Page Title
```
Use `previous_titles` for titles that visitors might remember from older versions of the site.
-## What changed text
+## What changed text and detail pages
-The changelog uses the latest Git commit message that touched each page as the short "what changed" description.
+The changelog uses Git commit messages as the short "what changed" descriptions. Each committed page change gets its own generated detail page showing what was edited compared with the previous version.
Write documentation commit messages for readers, not just for developers. For example:
```text
Clarify server setup steps
Explains the Nginx reload step and fixes the published path.
```
-The generator removes public URLs and commit-like hashes from the changelog output so private Forgejo details are not exposed.
+The generator removes public URLs, commit-like hashes, and raw Git diff metadata from the changelog output so private Forgejo details are not exposed.
## Regenerating manually
Run this from the repo root:
```bash
python3 scripts/generate_changelog.py
mkdocs build --clean
```
-The generated page is written to `docs/changelog.md`. Do not edit that file by hand because the next generator run will replace it.
+The generated index is written to `docs/changelog.md`, and generated detail pages are written to `docs/changelog/`. Do not edit those files by hand because the next generator run will replace them.
## Deployment
The server deploy workflow should run the generator after pulling the latest commit and before building MkDocs:
```bash
git pull origin main
python3 scripts/generate_changelog.py
mkdocs build --clean
```
The public Nginx site only serves the built MkDocs output. Forgejo can remain private on Tailscale because the generated changelog contains only public page metadata and summarized commit messages.