Writing Release Notes

Openchangelog supports the full range of Markdown syntax in .md files as well as frontmatter YAML to define metadata such as a title, description and more.

Naming Convention

Each release note is a separate Markdown file, this allows adding custom metadata for each article using frontmatter.
To ensure proper chronological ordering (newest first), we recommend prefixing each filename with its release version. Here are some examples:

{version}.{title}.md
v0.0.1.darkmode.md
v0.0.2.i81n.md

Frontmatter

Frontmatter is set at the top of your files between --- separators. It’s used to define Metadata for each release note.

Title

The title attribute specifies the title of the release note. Choose wisely ;)

Description

The description attribute specifies the description of the release note.

PublishedAt

The publishedAt attribute specifies the publishing date of the release note in ISO 8601 datetime format.

Content

It’s the main body of your release note, Openchangelog supports the full range of of Markdown syntax, allowing you to be creative with writing your release notes.

You can structure your content with:

Headings

Organize your release notes with a clear hierarchy using # for main headings and ## or ### for subheadings.

Bold & Italics

Highlight important information using **bold** or _italic_ text.

Lists

Use ordered (1.) and unordered lists (-) to break down features or bug fixes.

Code Blocks

A code block is indicated by a block with three backticks ``` at the start and end. You can indicate the programming language being used after the opening backticks.

// Javascript code with syntax highlighting.
var fun = function lang(l) {
  dateformat.i18n = require('./lang/' + l);
  return true;
};

Links & Images

Include links [alt](url) to documentation or images ![alt](url) to make your notes more visual.