Documentation

Release notes

Setting up the release notes feature

The release notes feature is toggled by creating a conventionally named file src/content/releases.mdx. The file is written like a regular content page. The Docs-Kit is automatically generating the release notes list below the content of that file and is applying a custom layout with filters for finding release notes.

See the test site for an example.

Creating a new release note

Release note files can be found in src/content/releases and are written in MDX like regular content. You can also place files in folders to better organize the release notes.

The Docs-Kit provides an interactive command-line script to create new release notes.

Calling yarn create-docs-release-note in the terminal guides through the creation

The files' location does not imply the URL like for content. The URL is built from the frontmatter fields for date and title. This way you can reorganize the files without changing the URL of the release note.

To learn the full release note file format including the full specification of the frontmatter fields, see the specification by example file.

Template

When not using the CLI tool to create a release note, you can use this template:

---
date: 2020-01-01
title: (TEMPLATE) TITLE
description:
  | # title content and what this is good for //  max 256 characters // for MC, RSS and other feeds
  (TEMPLATE) DESCRIPTION
type: enhancement # feature | fix | enhancement | announcement
topics:
# uncomment matching topics. Stay focused.
#  - Products
#  - Product List
#  - Categories
#  - Carts
#  - API Clients
#  - Settings
---


FooBar Intro Line: What this is good for (like description)


- [API] FooBar


<!--more-->


A longer explanation here that is just shown on the details page.
If there is no more, remove the marker above, too.

Available frontmatters:

  • date (date, required): A YYYY-MM-DD date format (not a text, it's parsed as an ISO date)
  • orderHint (number, optional): Sorts release notes that share a release date within the same microsite. Uses an ascending order with 1 being the most recent release note.
  • title (string, required): The title for the website
  • description (string, required): Max 256 characters plain text containing the change and its advantage ("tweet-able" and for RSS). 256 = 280 twitter minus 23 for a link. Do not imply the title, this text is used stand-alone in Merchant Center and other feed recipients. It must convey the value proposition and key change topic.
  • type (string, optional): Must be either feature (for "New Feature"), fix (for "Resolved Issue") or enhancement (for "Enhancement")
  • topics (array of string, optional): YAML array of free to choose text entries. The Filter UI may be constrained to pre-defined topics.
  • published (boolean, optional, defaults to true): false prevents rendering of the release in the site. Should not be used in the main documentation, reserved for atypical situations. Not included in the template.
  • slug (string, optional, defaults to $date-$title (slugified)): optional, allows overriding the autogenerated URL slug. Should not be used in the main documentation, reserved for migrating legacy docs.