docs
Changelog
Version history with release notes
Install
- Add the package:
npm install @refrakt-md/docs - Add it to the
pluginsarray inrefrakt.config.json:"plugins": ["@refrakt-md/docs"]
Source
import Markdoc from '@markdoc/markdoc';
import type { RenderableTreeNode } from '@markdoc/markdoc';
const { Ast, Tag } = Markdoc;
import {
createComponentRenderable,
createContentModelSchema,
bodyOnly,
asNodes,
renderNodes,
RenderableNodeCursor,
pageSectionProperties,
} from '@refrakt-md/runes';
export function parseReleaseHeading(text: string): {
version: string;
title: string;
date: string;
} {
const version = String.raw`v?(\d[\w.]*(?:-[\w.]+)?)`;
const titled = text.match(new RegExp(`^${version}\\s+·\\s+(.+?)(?:\\s+[-–—]\\s+(.+))?$`));
if (titled)
return { version: titled[1], title: titled[2].trim(), date: (titled[3] ?? '').trim() };
const dated = text.match(new RegExp(`^${version}\\s*[-–—]\\s*(.+)$`));
if (dated) return { version: dated[1], title: '', date: dated[2].trim() };
const bare = text.trim().match(new RegExp(`^${version}$`));
if (bare) return { version: bare[1], title: '', date: '' };
return { version: text, title: '', date: '' };
}
export const changelogRelease = createContentModelSchema({
attributes: {
version: { type: String, required: false },
title: { type: String, required: false },
date: { type: String, required: false },
},
contentModel: bodyOnly(),
transform(resolved, attrs, config) {
const titleTag = attrs.title ? new Tag('span', {}, [attrs.title]) : undefined;
const versionTag = new Tag('h3', {}, [
attrs.version ?? '',
...(titleTag ? [' ', titleTag] : []),
]);
const dateTag = new Tag('time', {}, [attrs.date ?? '']);
const body = renderNodes(resolved.body, config).wrap('div');
return createComponentRenderable({
rune: 'changelog-release',
tag: 'section',
properties: {
date: dateTag,
},
refs: {
version: versionTag,
...(titleTag ? { title: titleTag } : {}),
body: body.tag('div'),
},
children: [versionTag, dateTag, body.next()],
});
},
});
export const changelogSections = { preamble: 'preamble', headline: 'title' } as const;
export const changelog = createContentModelSchema({
sections: changelogSections,
attributes: {
project: {
type: String,
required: false,
description: 'Project name displayed in the changelog header.',
},
},
contentModel: () => ({
type: 'sections' as const,
sectionHeading: 'heading',
fields: [
{ name: 'header', match: 'heading|paragraph', optional: true, greedy: true },
{ name: 'items', match: 'tag', optional: true, greedy: true },
],
sectionModel: {
type: 'sequence' as const,
fields: [{ name: 'body', match: 'any', optional: true, greedy: true }],
},
}),
transform(resolved, attrs, config) {
const headerNodes = renderNodes(resolved.header, config);
const projectMeta = new Tag('meta', { content: attrs.project ?? '' });
const sections = resolved.sections as any[];
const releaseTagNodes = sections.map((section: any) => {
const { version, title, date } = parseReleaseHeading(section.$heading as string);
const attributes = title ? { version, title, date } : { version, date };
return new Ast.Node('tag', attributes, asNodes(section.body), 'changelog-release');
});
const allReleases = [...asNodes(resolved.items), ...releaseTagNodes];
const sectionNodes = new RenderableNodeCursor(
Markdoc.transform(allReleases, config) as RenderableTreeNode[],
);
const releases = sectionNodes.tag('section').typeof('ChangelogRelease');
const releasesDiv = new Tag('div', {}, releases.toArray());
const children: any[] = [];
if (headerNodes.count() > 0) {
children.push(headerNodes.wrap('header').next());
}
children.push(releasesDiv);
return createComponentRenderable({
rune: 'changelog',
tag: 'section',
properties: {
project: projectMeta,
release: releases,
},
refs: { ...pageSectionProperties(headerNodes), releases: releasesDiv },
children,
});
},
});
A product's version history: one entry per release, with its notes. For dated events that are not releases, such as a company's history, use timeline; for instructions a reader follows in order, steps.
Heading-based changelog
{% changelog %}
## v1.2.0 - January 2025
- Added timeline and changelog runes
- Added breadcrumb navigation rune
- Fixed grid column spanning on mobile
## v1.1.0 - December 2024
- Added testimonial and compare runes
- Improved pricing tier card styling
- Fixed tab panel content not rendering
{% /changelog %}<section data-rune="changelog" data-rune-fields="{"project":""}">
<div data-name="releases">
<section data-rune="changelog-release" data-field="release">
<h3 data-name="version">1.2.0</h3>
<time data-field="date">January 2025</time>
<div data-name="body">
<ul>
<li>Added timeline and changelog runes</li>
<li>Added breadcrumb navigation rune</li>
<li>Fixed grid column spanning on mobile</li>
</ul>
</div>
</section>
<section data-rune="changelog-release" data-field="release">
<h3 data-name="version">1.1.0</h3>
<time data-field="date">December 2024</time>
<div data-name="body">
<ul>
<li>Added testimonial and compare runes</li>
<li>Improved pricing tier card styling</li>
<li>Fixed tab panel content not rendering</li>
</ul>
</div>
</section>
</div>
</section>1.2.0
- Added timeline and changelog runes
- Added breadcrumb navigation rune
- Fixed grid column spanning on mobile
1.1.0
- Added testimonial and compare runes
- Improved pricing tier card styling
- Fixed tab panel content not rendering
<section class="rf-changelog" data-elevation="flush" data-rune="changelog" data-density="full">
<div data-name="releases" class="rf-changelog__releases">
<section class="rf-changelog-release" data-field="release" data-rune="changelog-release" data-density="full">
<h3 data-name="version" class="rf-changelog-release__version">1.2.0</h3>
<time data-field="date">January 2025</time>
<div data-name="body" class="rf-changelog-release__body">
<ul>
<li>Added timeline and changelog runes</li>
<li>Added breadcrumb navigation rune</li>
<li>Fixed grid column spanning on mobile</li>
</ul>
</div>
</section>
<section class="rf-changelog-release" data-field="release" data-rune="changelog-release" data-density="full">
<h3 data-name="version" class="rf-changelog-release__version">1.1.0</h3>
<time data-field="date">December 2024</time>
<div data-name="body" class="rf-changelog-release__body">
<ul>
<li>Added testimonial and compare runes</li>
<li>Improved pricing tier card styling</li>
<li>Fixed tab panel content not rendering</li>
</ul>
</div>
</section>
</div>
</section>How Markdown is read
| You write | It becomes |
|---|---|
A heading such as v1.2.0 - January 2025 | A release; the version, then the date after the dash |
| The content under the heading, usually a list | The release notes |
| A short paragraph, then a heading one level above the releases, before the first release | The eyebrow and headline (Page sections) |
Release titles
Give a release a title by putting it after the version, separated by a middle dot (·). The date still follows a dash. The title renders inside the release heading, after the version.
{% changelog %}
## v1.3.0 · Faster builds - March 2025
Builds reuse their cache, and the CLI reports what it skipped.
## v1.2.0 - January 2025
- Added timeline and changelog runes
{% /changelog %}<section data-rune="changelog" data-rune-fields="{"project":""}">
<div data-name="releases">
<section data-rune="changelog-release" data-field="release">
<h3 data-name="version">
1.3.0
<span data-name="title">Faster builds</span>
</h3>
<time data-field="date">March 2025</time>
<div data-name="body">
<p>Builds reuse their cache, and the CLI reports what it skipped.</p>
</div>
</section>
<section data-rune="changelog-release" data-field="release">
<h3 data-name="version">1.2.0</h3>
<time data-field="date">January 2025</time>
<div data-name="body">
<ul>
<li>Added timeline and changelog runes</li>
</ul>
</div>
</section>
</div>
</section>1.3.0 Faster builds
Builds reuse their cache, and the CLI reports what it skipped.
1.2.0
- Added timeline and changelog runes
<section class="rf-changelog" data-elevation="flush" data-rune="changelog" data-density="full">
<div data-name="releases" class="rf-changelog__releases">
<section class="rf-changelog-release" data-field="release" data-rune="changelog-release" data-density="full">
<h3 data-name="version" class="rf-changelog-release__version">
1.3.0
<span data-name="title" class="rf-changelog-release__title">Faster builds</span>
</h3>
<time data-field="date">March 2025</time>
<div data-name="body" class="rf-changelog-release__body">
<p>Builds reuse their cache, and the CLI reports what it skipped.</p>
</div>
</section>
<section class="rf-changelog-release" data-field="release" data-rune="changelog-release" data-density="full">
<h3 data-name="version" class="rf-changelog-release__version">1.2.0</h3>
<time data-field="date">January 2025</time>
<div data-name="body" class="rf-changelog-release__body">
<ul>
<li>Added timeline and changelog runes</li>
</ul>
</div>
</section>
</div>
</section>After a title, the dash before the date needs a space on each side, so a title can contain a hyphen (render-stack) but not -. Both the title and the date are optional.
Explicit releases
Use {% changelog-release %} tags for more control over version and date values.
{% changelog %}
{% changelog-release version="2.0.0" date="March 2025" %}
- Complete rewrite of the rendering engine
- New plugin API for custom runes
{% /changelog-release %}
{% changelog-release version="1.0.0" date="January 2025" %}
- Initial stable release
{% /changelog-release %}
{% /changelog %}<section data-rune="changelog" data-rune-fields="{"project":""}">
<div data-name="releases">
<section data-rune="changelog-release" data-field="release">
<h3 data-name="version">2.0.0</h3>
<time data-field="date">March 2025</time>
<div data-name="body">
<ul>
<li>Complete rewrite of the rendering engine</li>
<li>New plugin API for custom runes</li>
</ul>
</div>
</section>
<section data-rune="changelog-release" data-field="release">
<h3 data-name="version">1.0.0</h3>
<time data-field="date">January 2025</time>
<div data-name="body">
<ul>
<li>Initial stable release</li>
</ul>
</div>
</section>
</div>
</section>2.0.0
- Complete rewrite of the rendering engine
- New plugin API for custom runes
1.0.0
- Initial stable release
<section class="rf-changelog" data-elevation="flush" data-rune="changelog" data-density="full">
<div data-name="releases" class="rf-changelog__releases">
<section class="rf-changelog-release" data-field="release" data-rune="changelog-release" data-density="full">
<h3 data-name="version" class="rf-changelog-release__version">2.0.0</h3>
<time data-field="date">March 2025</time>
<div data-name="body" class="rf-changelog-release__body">
<ul>
<li>Complete rewrite of the rendering engine</li>
<li>New plugin API for custom runes</li>
</ul>
</div>
</section>
<section class="rf-changelog-release" data-field="release" data-rune="changelog-release" data-density="full">
<h3 data-name="version" class="rf-changelog-release__version">1.0.0</h3>
<time data-field="date">January 2025</time>
<div data-name="body" class="rf-changelog-release__body">
<ul>
<li>Initial stable release</li>
</ul>
</div>
</section>
</div>
</section>Attributes
| Attribute | Type | Required | Description |
|---|---|---|---|
project | string | — | Project name displayed in the changelog header. |
Universal attributes
bg
The background layer: image, video, gradient, flat overlay wash and legibility scrim, in a single injected layer behind the rune's content.
| Attribute | Type | Required | Description |
|---|---|---|---|
bg | string | — | Background preset applied to this block |
bg-from | string | — | Gradient start colour — a semantic token name (→ var(--rf-color-*)) |
bg-gradient | "to-t" | "to-b" | "to-l" | "to-r" | "to-tr" | "to-br" | "to-bl" | "to-tl" | — | Gradient direction (bounded named set) |
bg-gradient-type | "linear" | "radial" | "conic" | — | Gradient type |
bg-to | string | — | Gradient end colour — a semantic token name |
bg-via | string | — | Optional middle gradient stop — a semantic token name |
scrim | "top" | "bottom" | "left" | "right" | "none" | — | Scrim direction (heaviest edge); presence turns the scrim on, "none" opts out of the default cover scrim |
scrim-blur | "none" | "sm" | "md" | "lg" | — | Frost scrim blur amount |
scrim-strength | "sm" | "md" | "lg" | — | Gradient scrim strength |
scrim-tone | "dark" | "light" | — | Whether the scrim darkens (for light text) or lightens (for dark text) |
scrim-type | "gradient" | "frost" | — | Scrim treatment: gradient (default) or frost (backdrop blur) |
elevation
How far the rune sits off the page, from sunken to overlay. The theme decides what each step looks like.
| Attribute | Type | Required | Description |
|---|---|---|---|
elevation | "sunken" | "flush" | "flat" | "raised" | "floating" | "overlay" | "none" | "sm" | "md" | "lg" | — | Surface depth, from sunken to overlay. Deprecated: none, sm, md and lg (read as flat, raised, raised and floating) |
inset
Internal padding override.
| Attribute | Type | Required | Description |
|---|---|---|---|
inset | "flush" | "tight" | "default" | "loose" | "breathe" | — | Inner padding of this block |
motion
Scroll-reveal entrance. You choose its character; the theme decides how it moves.
| Attribute | Type | Required | Description |
|---|---|---|---|
reveal | "none" | "fade" | "slide" | "scale" | "blur" | — | Scroll-reveal entrance character (none|fade|slide|scale|blur); the theme owns the choreography |
stagger | boolean | — | Cascade this block's items in as it reveals (no-op on single-child runes) |
prominence
Header emphasis. Scales a rune's header, or its featured quotation; the theme decides the type size for each step.
| Attribute | Type | Required | Description |
|---|---|---|---|
prominence | "quiet" | "normal" | "prominent" | "display" | "marquee" | — | Emphasis of a page-section header or a featured quotation (only on runes that have one) |
spacing
Block-level rhythm override.
| Attribute | Type | Required | Description |
|---|---|---|---|
spacing | "flush" | "tight" | "default" | "loose" | "breathe" | — | Vertical spacing above and below this block |
substrate
Generated pattern fills behind the content, drawn by the theme.
| Attribute | Type | Required | Description |
|---|---|---|---|
substrate | "dots" | "grid" | "lines" | "cross" | "checker" | "none" | — | Generated surface pattern |
substrate-fill | "inherit" | "inset" | — | Surface fill the pattern sits on (full colour stays with tint) |
substrate-opacity | "sm" | "md" | "lg" | — | Pattern ink strength |
substrate-size | "sm" | "md" | "lg" | — | Pattern cell size |
substrate-target | "self" | "media" | — | Which surface the pattern fills (overrides the rune/theme default) |
tint
Per-rune colour override: a named tint from the theme registry, with inline per-token overrides layered on top.
| Attribute | Type | Required | Description |
|---|---|---|---|
tint | string | — | Color tint preset applied to this block |
tint-mode | "auto" | "dark" | "light" | — | Whether the tint adapts to auto, dark, or light mode |
width
The track a block rune occupies.
| Attribute | Type | Required | Description |
|---|---|---|---|
width | "compact" | "narrow" | "content" | "wide" | "full" | — | Maximum width constraint for this block |
| Not available | Why |
|---|---|
| dropcap, reading | this rune declares no prose body |
| frame | this rune declares neither a `frameTarget` nor a media section |
changelog-release
| Attribute | Type | Required | Description |
|---|---|---|---|
version | string | — | |
title | string | — | |
date | string | — |
Universal attributes
bg
The background layer: image, video, gradient, flat overlay wash and legibility scrim, in a single injected layer behind the rune's content.
| Attribute | Type | Required | Description |
|---|---|---|---|
bg | string | — | Background preset applied to this block |
bg-from | string | — | Gradient start colour — a semantic token name (→ var(--rf-color-*)) |
bg-gradient | "to-t" | "to-b" | "to-l" | "to-r" | "to-tr" | "to-br" | "to-bl" | "to-tl" | — | Gradient direction (bounded named set) |
bg-gradient-type | "linear" | "radial" | "conic" | — | Gradient type |
bg-to | string | — | Gradient end colour — a semantic token name |
bg-via | string | — | Optional middle gradient stop — a semantic token name |
scrim | "top" | "bottom" | "left" | "right" | "none" | — | Scrim direction (heaviest edge); presence turns the scrim on, "none" opts out of the default cover scrim |
scrim-blur | "none" | "sm" | "md" | "lg" | — | Frost scrim blur amount |
scrim-strength | "sm" | "md" | "lg" | — | Gradient scrim strength |
scrim-tone | "dark" | "light" | — | Whether the scrim darkens (for light text) or lightens (for dark text) |
scrim-type | "gradient" | "frost" | — | Scrim treatment: gradient (default) or frost (backdrop blur) |
elevation
How far the rune sits off the page, from sunken to overlay. The theme decides what each step looks like.
| Attribute | Type | Required | Description |
|---|---|---|---|
elevation | "sunken" | "flush" | "flat" | "raised" | "floating" | "overlay" | "none" | "sm" | "md" | "lg" | — | Surface depth, from sunken to overlay. Deprecated: none, sm, md and lg (read as flat, raised, raised and floating) |
inset
Internal padding override.
| Attribute | Type | Required | Description |
|---|---|---|---|
inset | "flush" | "tight" | "default" | "loose" | "breathe" | — | Inner padding of this block |
motion
Scroll-reveal entrance. You choose its character; the theme decides how it moves.
| Attribute | Type | Required | Description |
|---|---|---|---|
reveal | "none" | "fade" | "slide" | "scale" | "blur" | — | Scroll-reveal entrance character (none|fade|slide|scale|blur); the theme owns the choreography |
stagger | boolean | — | Cascade this block's items in as it reveals (no-op on single-child runes) |
spacing
Block-level rhythm override.
| Attribute | Type | Required | Description |
|---|---|---|---|
spacing | "flush" | "tight" | "default" | "loose" | "breathe" | — | Vertical spacing above and below this block |
substrate
Generated pattern fills behind the content, drawn by the theme.
| Attribute | Type | Required | Description |
|---|---|---|---|
substrate | "dots" | "grid" | "lines" | "cross" | "checker" | "none" | — | Generated surface pattern |
substrate-fill | "inherit" | "inset" | — | Surface fill the pattern sits on (full colour stays with tint) |
substrate-opacity | "sm" | "md" | "lg" | — | Pattern ink strength |
substrate-size | "sm" | "md" | "lg" | — | Pattern cell size |
substrate-target | "self" | "media" | — | Which surface the pattern fills (overrides the rune/theme default) |
tint
Per-rune colour override: a named tint from the theme registry, with inline per-token overrides layered on top.
| Attribute | Type | Required | Description |
|---|---|---|---|
tint | string | — | Color tint preset applied to this block |
tint-mode | "auto" | "dark" | "light" | — | Whether the tint adapts to auto, dark, or light mode |
width
The track a block rune occupies.
| Attribute | Type | Required | Description |
|---|---|---|---|
width | "compact" | "narrow" | "content" | "wide" | "full" | — | Maximum width constraint for this block |
| Not available | Why |
|---|---|
| dropcap, reading | this rune declares no prose body |
| frame | this rune declares neither a `frameTarget` nor a media section |
| prominence | this rune has no page-section header or featured quotation |