Docs›Changelog

docs

Changelog

Version history with release notes

Install

  1. Add the package: npm install @refrakt-md/docs
  2. Add it to the plugins array in refrakt.config.json: "plugins": ["@refrakt-md/docs"]

About the plugin and its runes

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,
		});
	},
});

View plugins/docs/src/tags/changelog.ts on GitHub

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="{&quot;project&quot;:&quot;&quot;}">
  <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 writeIt becomes
A heading such as v1.2.0 - January 2025A release; the version, then the date after the dash
The content under the heading, usually a listThe release notes
A short paragraph, then a heading one level above the releases, before the first releaseThe 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="{&quot;project&quot;:&quot;&quot;}">
  <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="{&quot;project&quot;:&quot;&quot;}">
  <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

AttributeTypeRequiredDescription
projectstring—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.

AttributeTypeRequiredDescription
bgstring—Background preset applied to this block
bg-fromstring—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-tostring—Gradient end colour — a semantic token name
bg-viastring—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.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
reveal"none" | "fade" | "slide" | "scale" | "blur"—Scroll-reveal entrance character (none|fade|slide|scale|blur); the theme owns the choreography
staggerboolean—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.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
spacing"flush" | "tight" | "default" | "loose" | "breathe"—Vertical spacing above and below this block
substrate

Generated pattern fills behind the content, drawn by the theme.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
tintstring—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.

AttributeTypeRequiredDescription
width"compact" | "narrow" | "content" | "wide" | "full"—Maximum width constraint for this block
Not availableWhy
dropcap, readingthis rune declares no prose body
framethis rune declares neither a `frameTarget` nor a media section

changelog-release

AttributeTypeRequiredDescription
versionstring—
titlestring—
datestring—

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.

AttributeTypeRequiredDescription
bgstring—Background preset applied to this block
bg-fromstring—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-tostring—Gradient end colour — a semantic token name
bg-viastring—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.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
reveal"none" | "fade" | "slide" | "scale" | "blur"—Scroll-reveal entrance character (none|fade|slide|scale|blur); the theme owns the choreography
staggerboolean—Cascade this block's items in as it reveals (no-op on single-child runes)
spacing

Block-level rhythm override.

AttributeTypeRequiredDescription
spacing"flush" | "tight" | "default" | "loose" | "breathe"—Vertical spacing above and below this block
substrate

Generated pattern fills behind the content, drawn by the theme.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
tintstring—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.

AttributeTypeRequiredDescription
width"compact" | "narrow" | "content" | "wide" | "full"—Maximum width constraint for this block
Not availableWhy
dropcap, readingthis rune declares no prose body
framethis rune declares neither a `frameTarget` nor a media section
prominencethis rune has no page-section header or featured quotation