Plan›Milestone

plan

Milestone

Named release target with scope, goals, and status tracking

Install

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

About the plugin and its runes

Source

import Markdoc from '@markdoc/markdoc';
const { Tag } = Markdoc;
import {
	createContentModelSchema,
	createComponentRenderable,
	renderNodes,
	fieldMetas,
} from '@refrakt-md/runes';
import { VALID_STATUS } from '../commands/enums.js';
import { stripHorizontalRules } from '../util.js';

export const milestoneSections = { title: 'title', blurb: 'description', body: 'body' } as const;

export const milestone = createContentModelSchema({
	sections: milestoneSections,
	provides: ['prose'],
	attributes: {
		name: { type: String, required: true, description: 'Milestone name (e.g., "v0.5.0").' },
		target: {
			type: String,
			required: false,
			description: 'Target date (aspirational, not a commitment).',
		},
		status: {
			type: String,
			required: false,
			matches: [...VALID_STATUS.milestone],
			description: 'Current status: planning, active, or complete.',
		},
		created: {
			type: String,
			required: false,
			description: 'Creation date (ISO 8601). Defaults to file creation date from git.',
		},
		modified: {
			type: String,
			required: false,
			description: 'Last modified date (ISO 8601). Defaults to file modification date from git.',
		},
	},
	contentModel: {
		type: 'sequence',
		fields: [
			{ name: 'title', match: 'heading', optional: true },
			{ name: 'description', match: 'paragraph', optional: true, greedy: true },
			{ name: 'body', match: 'any', optional: true, greedy: true },
		],
	},
	transform(resolved, attrs, config) {
		const titleNodes = renderNodes(resolved.title, config);
		const descNodes = renderNodes(resolved.description, config);
		const bodyNodes = renderNodes(resolved.body, config);

		const title = titleNodes.count() > 0 ? titleNodes.wrap('header') : undefined;
		const blurb = descNodes.count() > 0 ? descNodes.wrap('div').next() : undefined;
		const bodyDiv = new Tag('div', {}, stripHorizontalRules(bodyNodes.toArray()));

		return createComponentRenderable({
			rune: 'milestone',
			tag: 'section',
			properties: fieldMetas(attrs, config, {
				name: '',
				target: '',
				status: 'planning',
				created: { from: ['attrs.created', 'file.created'], default: '' },
				modified: { from: ['attrs.modified', 'file.modified'], default: '' },
			}),
			refs: {
				title: title?.tag('header'),
				blurb,
				body: bodyDiv,
			},
			children: [...(title ? [title.next()] : []), ...(blurb ? [blurb] : []), bodyDiv],
		});
	},
});

View plugins/plan/src/tags/milestone.ts on GitHub

A named release target or goal. Not a sprint — no timebox, no velocity, no ceremonies. A milestone is a coherent set of capabilities that together deliver value. When all work items assigned to it are done, the milestone is complete.

Active milestone

A milestone currently in progress with goals.

{% milestone name="v0.5.0" target="2026-03-29" status="active" %}
# v0.5.0 — Layout & Tint

- Complete alignment system migration
- Ship tint rune with dark mode support
- Publish layout spec as site documentation
- Resolve showcase bleed overflow bug
{% /milestone %}
<section data-rune="milestone" data-rune-fields="{&quot;name&quot;:&quot;v0.5.0&quot;,&quot;target&quot;:&quot;2026-03-29&quot;,&quot;status&quot;:&quot;active&quot;,&quot;created&quot;:&quot;2026-11-11&quot;,&quot;modified&quot;:&quot;2026-11-11&quot;}">
  <header data-name="title">
    <h1 id="v050-layout-tint">v0.5.0 — Layout &amp; Tint</h1>
  </header>
  <div data-name="body">
    <ul>
      <li>Complete alignment system migration</li>
      <li>Ship tint rune with dark mode support</li>
      <li>Publish layout spec as site documentation</li>
      <li>Resolve showcase bleed overflow bug</li>
    </ul>
  </div>
</section>
v0.5.0active

v0.5.0 — Layout & Tint

  • Complete alignment system migration
  • Ship tint rune with dark mode support
  • Publish layout spec as site documentation
  • Resolve showcase bleed overflow bug
<section class="rf-milestone rf-milestone--v0.5.0 rf-milestone--active" data-name="v0.5.0" data-status="active" data-target="2026-03-29" data-created="2026-11-11" data-modified="2026-11-11" data-rune="milestone" data-density="full">
  <div data-name="eyebrow" data-zone="eyebrow" data-zone-layout="bar" class="rf-milestone__eyebrow">
    <span data-meta-type="id" data-field="name">v0.5.0</span>
    <span data-meta-type="status" data-meta-sentiment="positive" data-align="end" data-field="status">active</span>
  </div>
  <header data-name="title" class="rf-milestone__title" data-section="title">
    <h1 id="v050-layout-tint">v0.5.0 — Layout &amp; Tint</h1>
  </header>
  <dl data-name="metadata" data-zone="metadata" data-zone-layout="definition-list" class="rf-milestone__metadata">
    <div data-name="row" data-field="target" class="rf-milestone__row">
      <dt data-meta-label="">Target</dt>
      <dd>
        <time data-meta-type="temporal" datetime="2026-03-29">2026-03-29</time>
      </dd>
    </div>
    <div data-name="row" data-field="created" class="rf-milestone__row">
      <dt data-meta-label="">Created</dt>
      <dd>
        <time data-meta-type="temporal" datetime="2026-11-11">2026-11-11</time>
      </dd>
    </div>
    <div data-name="row" data-field="modified" class="rf-milestone__row">
      <dt data-meta-label="">Modified</dt>
      <dd>
        <time data-meta-type="temporal" datetime="2026-11-11">2026-11-11</time>
      </dd>
    </div>
  </dl>
  <div data-name="body" class="rf-milestone__body" data-section="body">
    <ul>
      <li>Complete alignment system migration</li>
      <li>Ship tint rune with dark mode support</li>
      <li>Publish layout spec as site documentation</li>
      <li>Resolve showcase bleed overflow bug</li>
    </ul>
  </div>
</section>

How Markdown is read

You writeIt becomes
A headingThe milestone's title
The paragraphs right after itThe milestone's lead
Everything after them: a goals list, notes, ## sectionsThe body, in the order written

Planning milestone

A future milestone still being scoped.

{% milestone name="v1.0" target="2026-06-01" status="planning" %}
# v1.0 — Stable Release

- Stabilise all public APIs
- Complete documentation for all runes
- Launch theme marketplace
- Publish migration guide from v0.x
{% /milestone %}
<section data-rune="milestone" data-rune-fields="{&quot;name&quot;:&quot;v1.0&quot;,&quot;target&quot;:&quot;2026-06-01&quot;,&quot;status&quot;:&quot;planning&quot;,&quot;created&quot;:&quot;2026-11-11&quot;,&quot;modified&quot;:&quot;2026-11-11&quot;}">
  <header data-name="title">
    <h1 id="v10-stable-release">v1.0 — Stable Release</h1>
  </header>
  <div data-name="body">
    <ul>
      <li>Stabilise all public APIs</li>
      <li>Complete documentation for all runes</li>
      <li>Launch theme marketplace</li>
      <li>Publish migration guide from v0.x</li>
    </ul>
  </div>
</section>
v1.0planning

v1.0 — Stable Release

  • Stabilise all public APIs
  • Complete documentation for all runes
  • Launch theme marketplace
  • Publish migration guide from v0.x
<section class="rf-milestone rf-milestone--v1.0 rf-milestone--planning" data-name="v1.0" data-status="planning" data-target="2026-06-01" data-created="2026-11-11" data-modified="2026-11-11" data-rune="milestone" data-density="full">
  <div data-name="eyebrow" data-zone="eyebrow" data-zone-layout="bar" class="rf-milestone__eyebrow">
    <span data-meta-type="id" data-field="name">v1.0</span>
    <span data-meta-type="status" data-meta-sentiment="neutral" data-align="end" data-field="status">planning</span>
  </div>
  <header data-name="title" class="rf-milestone__title" data-section="title">
    <h1 id="v10-stable-release">v1.0 — Stable Release</h1>
  </header>
  <dl data-name="metadata" data-zone="metadata" data-zone-layout="definition-list" class="rf-milestone__metadata">
    <div data-name="row" data-field="target" class="rf-milestone__row">
      <dt data-meta-label="">Target</dt>
      <dd>
        <time data-meta-type="temporal" datetime="2026-06-01">2026-06-01</time>
      </dd>
    </div>
    <div data-name="row" data-field="created" class="rf-milestone__row">
      <dt data-meta-label="">Created</dt>
      <dd>
        <time data-meta-type="temporal" datetime="2026-11-11">2026-11-11</time>
      </dd>
    </div>
    <div data-name="row" data-field="modified" class="rf-milestone__row">
      <dt data-meta-label="">Modified</dt>
      <dd>
        <time data-meta-type="temporal" datetime="2026-11-11">2026-11-11</time>
      </dd>
    </div>
  </dl>
  <div data-name="body" class="rf-milestone__body" data-section="body">
    <ul>
      <li>Stabilise all public APIs</li>
      <li>Complete documentation for all runes</li>
      <li>Launch theme marketplace</li>
      <li>Publish migration guide from v0.x</li>
    </ul>
  </div>
</section>

Completed milestone

A milestone with all goals achieved.

{% milestone name="v0.4.0" status="complete" %}
# v0.4.0 — Foundation

- Core rune system operational
- Static site build complete
- Lumina theme baseline shipped
{% /milestone %}
<section data-rune="milestone" data-rune-fields="{&quot;name&quot;:&quot;v0.4.0&quot;,&quot;target&quot;:&quot;&quot;,&quot;status&quot;:&quot;complete&quot;,&quot;created&quot;:&quot;2026-11-11&quot;,&quot;modified&quot;:&quot;2026-11-11&quot;}">
  <header data-name="title">
    <h1 id="v040-foundation">v0.4.0 — Foundation</h1>
  </header>
  <div data-name="body">
    <ul>
      <li>Core rune system operational</li>
      <li>Static site build complete</li>
      <li>Lumina theme baseline shipped</li>
    </ul>
  </div>
</section>
v0.4.0complete

v0.4.0 — Foundation

  • Core rune system operational
  • Static site build complete
  • Lumina theme baseline shipped
<section class="rf-milestone rf-milestone--v0.4.0 rf-milestone--complete" data-name="v0.4.0" data-status="complete" data-target="" data-created="2026-11-11" data-modified="2026-11-11" data-rune="milestone" data-density="full">
  <div data-name="eyebrow" data-zone="eyebrow" data-zone-layout="bar" class="rf-milestone__eyebrow">
    <span data-meta-type="id" data-field="name">v0.4.0</span>
    <span data-meta-type="status" data-meta-sentiment="positive" data-align="end" data-field="status">complete</span>
  </div>
  <header data-name="title" class="rf-milestone__title" data-section="title">
    <h1 id="v040-foundation">v0.4.0 — Foundation</h1>
  </header>
  <dl data-name="metadata" data-zone="metadata" data-zone-layout="definition-list" class="rf-milestone__metadata">
    <div data-name="row" data-field="created" class="rf-milestone__row">
      <dt data-meta-label="">Created</dt>
      <dd>
        <time data-meta-type="temporal" datetime="2026-11-11">2026-11-11</time>
      </dd>
    </div>
    <div data-name="row" data-field="modified" class="rf-milestone__row">
      <dt data-meta-label="">Modified</dt>
      <dd>
        <time data-meta-type="temporal" datetime="2026-11-11">2026-11-11</time>
      </dd>
    </div>
  </dl>
  <div data-name="body" class="rf-milestone__body" data-section="body">
    <ul>
      <li>Core rune system operational</li>
      <li>Static site build complete</li>
      <li>Lumina theme baseline shipped</li>
    </ul>
  </div>
</section>

Attributes

AttributeTypeRequiredDescription
namestring✓Milestone name (e.g., "v0.5.0").
targetstring—Target date (aspirational, not a commitment).
status"planning" | "active" | "complete"—Current status: planning, active, or complete.
createdstring—Creation date (ISO 8601). Defaults to file creation date from git.
modifiedstring—Last modified date (ISO 8601). Defaults to file modification date from git.

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)
dropcap

Per-instance drop-cap opt-in.

AttributeTypeRequiredDescription
dropcapboolean—Style the opening letter of a prose body as a drop cap. Honoured only when the body reads as prose; ignored otherwise.
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)
reading

Editorial register for body text. You pick the register; the theme decides how it looks.

AttributeTypeRequiredDescription
reading"fine" | "ui" | "prose"—Reading register for this block’s body: fine | ui | prose. The theme sets how each one looks.
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
framethis rune declares neither a `frameTarget` nor a media section