| name | changelog |
| description | Build a timeline changelog page from a folder of version-named Markdown files. Mark the folder with `changelog: true` in its index.yml; name one file per release (v1.2.0.md). Use when documenting releases / "what's new". |
Changelog (version-folder)
Neko turns a folder into a single, timeline-style changelog page. You keep one
small Markdown file per release — named after its version — and Neko parses each
file name as a version, sorts them newest-first, and renders one page at the
folder URL. Version files are not standalone pages; the folder collapses to
a single sidebar entry, and the aggregated page is what is indexed for search.
Setup
Mark a folder as a changelog with its folder config (index.yml or
<foldername>.yml):
changelog: true
title: Changelog
description: All notable changes to this project.
icon: memo
order: 2
Then add one file per release, named after the version:
changelog/
├── index.yml
├── v1.2.0.md
├── v1.1.0.md
└── v1.0.0.md
Folder config keys
| Key | Notes |
|---|
changelog | true to turn the folder into a changelog. Required. |
title | Page heading (used when there is no index.md). |
description | Lead paragraph under the title. |
icon | Sidebar icon (UIcon / :emoji: / image path). |
order | Sidebar position, same rules as any folder. |
label | Sidebar text (defaults to title, then the folder name). |
Version file names
The file name (minus extension) is parsed into numeric components for ordering.
A leading v/V is optional; ., -, _ separators all work.
| File | Display | Kind |
|---|
v1.2.0.md | v1.2.0 | Semantic versioning |
1.0.0.md | v1.0.0 | v added for display |
v26.6.md | v26.6 | Calendar versioning |
v26.3.16.md | v26.3.16 | CalVer + patch |
Ordering is numeric, component-by-component — v26.6 sorts above v26.3.16.
Entry frontmatter (optional)
---
title: Ready for Production # headline next to the version badge
date: 2024-06-18 # rendered verbatim in the header
link: https://www.nuget.org/packages/YourPkg/1.0.0 # version → release link
---
All three keys are optional:
| Key | Notes |
|---|
title | Headline shown next to the version badge. |
date | Rendered verbatim in the version header. |
link | A link for the version — turns the version badge in the sticky header into a link (e.g. the NuGet/release page, a GitHub release, or release notes). For packaged projects, link to the latest package of that month/release. |
Sections and entries
The body is authored as sections with entries:
- A section is a Markdown
# heading prefixed with an icon
shortcode. It renders as a labelled header with the icon in a coloured box.
- Each entry is a
::: change {badge="…" title="…"} block: the badge renders in
a left column (vertically aligned across entries), with the title +
description next to it.
---
date: Jun 2026
link: https://www.nuget.org/packages/YourPkg/26.6.1802
---
# :icon-sparkles: Features
::: change {badge="New" title="Folder-based changelogs"}
Changelogs are now built from a folder of version-named files.
:::
# :icon-bug: Fixes
::: change {badge="Fixed" title="Skip commented directives"}
Re-running image generation no longer regenerates commented-out directives.
:::
Badge values & section icons
badge= is free text; these well-known values get colours automatically
(override with badge-color="…"):
| Badge | Colour | Suggested section |
|---|
New / Feature | primary | # :icon-sparkles: Features |
Improved | neutral | # :icon-wrench-simple: Improvements |
Fixed | green | # :icon-bug: Fixes |
Docs | sky | # :icon-document: Documentation |
Changed | amber | |
Removed | red | |
Security | purple | |
The change body is ordinary Markdown — code spans, links, lists, or any
component. Plain Markdown outside ::: change
blocks still renders, but the section + entry form is preferred.
Examples
A minimal release file:
# changelog/v1.0.0.md
---
title: First stable release
date: 2024-06-18
link: https://www.nuget.org/packages/YourPkg/1.0.0
---
# :icon-rocket: Highlights
::: change {badge="New" title="Public API"}
Shipped the public API.
:::
Adding changelog/v1.1.0.md later automatically appears above v1.0.0 on
the /changelog page — no manual reordering.
Intro content
To add prose above the timeline, drop an index.md in the folder. Its content
(and H1) become the page header and the timeline is appended below; the
index.yml title/description then act only as fallbacks.
Tips
- One file per release. Don't accumulate everything in a single file.
- Keep file names purely versions (
v1.2.0.md), not titles — put the headline
in frontmatter title:.
- Link to it from
neko.yml top nav with link: /changelog.
- The folder name is not special; any folder with
changelog: true works.
