CONTRIBUTOR GUIDE

Changelog authoring guide

Everything you need to create, edit, preview, and publish changelog entries for this project.

Get started View changelog files

Content directory

content/changelog/

File format

*.mdx

Publishing

Build / redeploy required

01 / WORKFLOW

How it works

A changelog entry is just an MDX file. The system handles the rest.

Create the entry

Create a new .mdx file inside content/changelog/. The filename becomes the permanent URL.

content/changelog/v1.2.0.mdx

Add frontmatter

Add the required title, version, and date fields. Description, tags, and images are optional.

title: Your release title
version: v1.2.0
date: 2026-10-06

Write the release notes

Write the changelog content below the frontmatter using MDX. Start body headings at ##.

## Added

- New feature
- Another improvement

Add images

If your release needs screenshots or other visuals, place them inside the public/changelog directory.

public/changelog/v1.2.0/cover.png

Test locally

Run the development server and verify both the changelog list and your individual release page.

npm run dev

Commit & deploy

Commit your changes and deploy. Changelog pages are generated at build time.

git add . && git commit -m "docs: add v1.2.0 changelog"

02 / FILES

File naming

The filename becomes the public changelog URL, so treat it as permanent.

content/changelog/v1.2.0.mdx

v1.2.0.mdx

URL: /changelog/v1.2.0

Use lowercase filenames with no spaces. Hyphens and dots are fine.

GOOD

v1.2.0.mdx

v2.0.0-beta.1.mdx

2026-10-launch.mdx

AVOID

Version 1.2.mdx

release notes.mdx

ReleaseNotes.mdx

03 / FRONTMATTER

Required metadata

Every changelog entry needs title, version, and date.

v1.2.0.mdx

---
title: Faster Dashboard
description: Dashboard performance improvements.
version: v1.2.0
date: 2026-10-06
tags: [feature, performance]
image: /changelog/v1.2.0/cover.png
imageAlt: Faster dashboard
---

FieldRequired

titleYes

versionYes

dateYes

descriptionRecommended

tagsOptional

imageOptional

imageAltOptional

Missing a mandatory field or using an invalid date causes the build to fail. This prevents broken changelog entries from reaching production.

04 / CONTENT

Write the release notes

Everything below the closing frontmatter delimiter is rendered as MDX.

v1.2.0.mdx

---
title: Faster Dashboard
description: Dashboard performance improvements.
version: v1.2.0
date: 2026-10-06
tags: [feature, performance]
---

This release focuses on speed and reliability.

## Added

- Faster dashboard loading
- Improved search

## Fixed

- Fixed sidebar flickering

Use ## for the first body heading

Use consistent sections such as Added, Improved, Fixed

Markdown formatting is supported

Links and tables are supported

Code blocks are supported

MDX syntax is supported

05 / IMAGES

Add release images

Store changelog images under public/changelog/<version>/.

Project structure

public/
└── changelog/
    └── v1.2.0/
        ├── cover.png
        ├── dashboard.png
        └── invite.png

v1.2.0.mdx

---
image: /changelog/v1.2.0/cover.png
imageAlt: The redesigned dashboard
---

![Dashboard redesign](/changelog/v1.2.0/dashboard.png)

Recommended ratio

16:9

Formats

WebP or PNG

Target size

~500 KB or less

06 / MDX

Avoid common MDX errors

MDX is stricter than regular Markdown because it also parses JSX and JavaScript expressions.

Curly braces are interpreted as expressions.

AVOID

{id}

USE

`{id}`

Angle brackets can be interpreted as JSX.

AVOID

<something>

USE

`<something>`

JSX tags must be properly closed.

AVOID

<br>

USE

<br />

Quote YAML values containing a colon.

AVOID

title: Performance: 60% faster

USE

title: "Performance: 60% faster"

07 / PUBLISH

Before you publish

Use this checklist before opening your pull request.

title, version, and date are present

date uses YYYY-MM-DD format

filename is lowercase and stable

description is filled in

body starts with ##, not #

all images have meaningful alt text

image paths start with /

the changelog page works locally

the individual release page works locally

Ready to add a changelog entry?

Create an MDX file, follow the guide, test it locally, and submit your changes.

Open changelog directory View changelog