Releases & Changelog
The releases feature has two kinds of page: one index that lists every release as a table, and one detail page per release that shows the version, status, a download button with a verification hash, tabbed details, and a roadmap timeline on the right.
It's generic: the same structure works for any dated, versioned, downloadable
entry — not just software builds. Detail pages are recognised by location
(they live in a releases/ or changelog/ folder), or by opting in with
release: true from any folder.
Image and download paths resolve against the asset base (public/), so
download: files/app.zip serves <plugin>/public/files/app.zip. An absolute
https://… URL is used as-is.
The index page
One file (for example releases.md) turns on the table:
| Key | Required | Description |
|---|---|---|
title | yes | Heading for the list page. |
releases_dir | yes | The folder holding detail pages. Normally releases. |
description | no | Short intro. |
order | no | Sidebar/sort weight. |
---
title: Releases
description: Downloads, changelogs, and what's coming next.
releases_dir: releases
order: 70
---
Every SepoDesk release, with verified downloads.Each non-underscore file in the folder becomes a table row — Release · Date ·
Status · Download — sorted by order (highest first), then newest date.
A release detail page
One Markdown file per release inside the releases/ folder. Only title is
required; every other key is optional and the page adapts to whatever you supply
(empty tabs and the timeline panel simply don't render).
Header & download
| Key | Description |
|---|---|
title | Release name/headline. Falls back to version if omitted. |
version | Version string, shown as a v… badge. |
date | Release date, shown in the header and table. |
status | Free text — stable, beta, rc, planned, deprecated, … Colour is auto. |
summary | One-line lead under the title (alias: description). Also shown in the table. |
download | Package to download — a public/ path or an absolute URL (alias: download_url). |
size | Human size shown beside the button, e.g. 12.4 MB. |
hash | Checksum shown with a copy button (aliases: sha256, checksum). |
hash_algo | Checksum label. Defaults to SHA-256. |
order | Table sort weight. Higher sorts earlier. |
release | Set true only to force detail rendering from outside releases//changelog/. |
Tab content
Each of these is a comma-separated list; entries use Label|Note, where the note
is optional. A tab appears only when it has content.
| Key | Tab | Entry format | |
|---|---|---|---|
| (body) | Overview | Markdown body of the file, shown after the summary. | |
added | What's changed | `Label\ | Note` |
removed | What's changed | `Label\ | Note` |
changed | What's changed | `Label\ | Note (alias: improved`) |
fixed | What's changed | `Label\ | Note` |
requirements | Requirements | `Label\ | Note (alias: requires`) |
known_issues | Requirements | `Label\ | Note (alias: known`) |
Roadmap timeline (right panel)
| Key | Description | ||
|---|---|---|---|
timeline | Vertical roadmap. Entries are `Label\ | Duration\ | Status (alias: roadmap`). |
The Status word drives the dot colour with the same mapping as the header
badge (stable/done → green, beta/in progress → amber, planned → blue,
deprecated → grey).
Pipe-list syntax
Lists are comma-separated; fields within an entry use |. Avoid commas inside a
label or note, since commas separate entries.
added:
[Multi-root URLs|app and asset bases resolve separately, Grid view for blogs]
timeline: [Auth tokens|2 weeks|In progress, Media library|3 weeks|Planned]Full detail example
---
title: Router rewrite
version: 2.1.0
date: 2026-08-01
status: stable
summary: Multi-root URL resolution, a faster page store, and a new docs mount.
download: files/sepodesk-2.1.0.zip
size: 12.4 MB
hash: 9f2b1c4e7a8d0b3f5e6172839a0bc4d5e6f70819a2b3c4d5e6f7081920a1b2c3
hash_algo: SHA-256
added:
[
Multi-root URL resolution|app_url and asset_url resolve separately,
Grid view for blogs,
]
removed: [Legacy single-root router|superseded by the resolver]
changed: [Sidebar folder state persists per browser]
fixed: [Version badge fell back to 1.0.0, Breadcrumb overflow on long titles]
requirements: [PHP 8.1+, ext-json, ext-mbstring]
known_issues: [Tables break on pipe characters in cells|escape with a backslash]
timeline:
[Auth refresh tokens|2 weeks|In progress, Media library|3 weeks|Planned]
order: 210
---
## Highlights
The routing rewrite is complete. Download the package above and verify the
checksum before extracting.Reachability
Detail files are hidden from the left sidebar automatically — releases is in
the sidebar's exclusion list, and the index page is hidden by its releases_dir
key. Surface the index in the top navigation via _nav.md:
- [Releases](/docs/releases)