Disclosure›Accordion

core

Accordion

Collapsible accordion sections for FAQ-style content

Source

import Markdoc from '@markdoc/markdoc';
import type { RenderableTreeNode } from '@markdoc/markdoc';
const { Tag } = Markdoc;
import {
	createComponentRenderable,
	createContentModelSchema,
	bodyOnly,
	asNodes,
	renderNodes,
	stripSchemaOrg,
} from '../lib/index.js';
import { RenderableNodeCursor } from '../lib/renderable.js';
import { pageSectionProperties } from './common.js';

export const accordionItemSections = { body: 'body' } as const;

export const accordionItemSchema = {
	type: 'Question',
	properties: { name: 'name' },
	children: {
		body: { type: 'Answer', property: 'acceptedAnswer', text: { body: 'text' } },
	},
} as const;

export const accordionItem = createContentModelSchema({
	schema: accordionItemSchema,
	sections: accordionItemSections,
	provides: ['prose'],
	attributes: {
		name: { type: String, required: true },
	},
	contentModel: bodyOnly(),
	transform(resolved, attrs, config) {
		const nameTag = new Tag('summary', {}, [attrs.name ?? '']);
		const body = renderNodes(resolved.body, config).wrap('div');
		const bodyDivs = body.tag('div');

		return createComponentRenderable({
			rune: 'accordion-item',
			tag: 'details',
			properties: {
				name: nameTag,
			},
			refs: {
				body: bodyDivs,
			},
			children: [nameTag, body.next()],
		});
	},
});

export const accordionSections = {
	preamble: 'preamble',
	eyebrow: 'eyebrow',
	headline: 'title',
	blurb: 'description',
} as const;

export const accordionSchema = {
	type: 'FAQPage',
	children: { 'accordion-item': { type: 'Question', property: 'mainEntity' } },
} as const;

export const accordion = createContentModelSchema({
	schema: accordionSchema,
	sections: accordionSections,
	attributes: {
		multiple: {
			type: Boolean,
			required: false,
			description: 'Allow multiple panels to be open at once',
		},
		schema: {
			type: String,
			required: false,
			matches: ['none'],
			description:
				'Set to "none" to emit no schema.org markup. Use it when the panels are not a FAQ — a list of definitions, say — so the page does not publish fabricated Question entries. Suppresses the items too, not just the container.',
		},
	},
	contentModel: () => ({
		type: 'sections' as const,
		sectionHeading: 'heading',
		emitTag: 'accordion-item',
		emitAttributes: { name: '$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 allItems = [...asNodes(resolved.items), ...asNodes(resolved.sections)];
		const sectionNodes = new RenderableNodeCursor(
			Markdoc.transform(allItems, config) as RenderableTreeNode[],
		);

		const items = sectionNodes.tag('details').typeof('AccordionItem');
		const itemsContainer = items.wrap('div');

		if (items.count() === 0 && headerNodes.count() === 0) return null;

		// Stripped here, not in a later pass: `extractSeo` reads this output.
		const noSchema = attrs.schema === 'none';
		if (noSchema) stripSchemaOrg(sectionNodes.nodes);

		const children =
			headerNodes.count() > 0
				? [headerNodes.wrap('header').next(), itemsContainer.next()]
				: [itemsContainer.next()];

		return createComponentRenderable({
			rune: 'accordion',
			tag: 'section',
			properties: {
				item: items,
			},
			refs: { ...pageSectionProperties(headerNodes), items: itemsContainer },
			children,
		});
	},
});

View packages/runes/src/tags/accordion.ts on GitHub

Collapsible accordion sections. Use explicit {% accordion-item %} tags, or write headings directly and they will be automatically converted into accordion panels. For a single collapsible block, use details; to switch between panels behind a row of labels, use tabs; to uncover content one step at a time, use reveal.

Basic usage

Wrap each section in an {% accordion-item %} tag with a name.

{% accordion %}
	{% accordion-item name="What is refrakt.md?" %}
	A content framework built on Markdoc that extends Markdown with semantic runes. You write standard Markdown — runes decide how it's interpreted.
	{% /accordion-item %}

	{% accordion-item name="How do runes work?" %}
	Runes are Markdoc tags that wrap ordinary Markdown. The same list renders as navigation links, a feature grid, or action buttons — depending on which rune contains it.
	{% /accordion-item %}

	{% accordion-item name="Do I need to learn a new syntax?" %}
	No. Runes use standard Markdoc tag syntax, and the content inside is regular Markdown.
	{% /accordion-item %}
{% /accordion %}
<section data-rune="accordion" typeof="FAQPage">
  <div data-name="items">
    <details data-rune="accordion-item" typeof="Question" data-field="item" property="mainEntity">
      <summary data-field="name" property="name">What is refrakt.md?</summary>
      <div data-name="body" typeof="Answer" property="acceptedAnswer">
        <div property="text">
          <p>A content framework built on Markdoc that extends Markdown with semantic runes. You write standard Markdown — runes decide how it's interpreted.</p>
        </div>
      </div>
    </details>
    <details data-rune="accordion-item" typeof="Question" data-field="item" property="mainEntity">
      <summary data-field="name" property="name">How do runes work?</summary>
      <div data-name="body" typeof="Answer" property="acceptedAnswer">
        <div property="text">
          <p>Runes are Markdoc tags that wrap ordinary Markdown. The same list renders as navigation links, a feature grid, or action buttons — depending on which rune contains it.</p>
        </div>
      </div>
    </details>
    <details data-rune="accordion-item" typeof="Question" data-field="item" property="mainEntity">
      <summary data-field="name" property="name">Do I need to learn a new syntax?</summary>
      <div data-name="body" typeof="Answer" property="acceptedAnswer">
        <div property="text">
          <p>No. Runes use standard Markdoc tag syntax, and the content inside is regular Markdown.</p>
        </div>
      </div>
    </details>
  </div>
</section>
What is refrakt.md?

A content framework built on Markdoc that extends Markdown with semantic runes. You write standard Markdown — runes decide how it's interpreted.

How do runes work?

Runes are Markdoc tags that wrap ordinary Markdown. The same list renders as navigation links, a feature grid, or action buttons — depending on which rune contains it.

Do I need to learn a new syntax?

No. Runes use standard Markdoc tag syntax, and the content inside is regular Markdown.

<section class="rf-accordion" typeof="FAQPage" data-rune="accordion" data-density="full">
  <div data-name="items" class="rf-accordion__items">
    <details class="rf-accordion-item" typeof="Question" data-field="item" property="mainEntity" data-rune="accordion-item" data-density="full" data-state="closed">
      <summary data-field="name" property="name" data-name="header" class="rf-accordion-item__header">What is refrakt.md?</summary>
      <div data-name="body" typeof="Answer" property="acceptedAnswer" class="rf-accordion-item__body" data-section="body">
        <div property="text">
          <p>A content framework built on Markdoc that extends Markdown with semantic runes. You write standard Markdown — runes decide how it's interpreted.</p>
        </div>
      </div>
    </details>
    <details class="rf-accordion-item" typeof="Question" data-field="item" property="mainEntity" data-rune="accordion-item" data-density="full" data-state="closed">
      <summary data-field="name" property="name" data-name="header" class="rf-accordion-item__header">How do runes work?</summary>
      <div data-name="body" typeof="Answer" property="acceptedAnswer" class="rf-accordion-item__body" data-section="body">
        <div property="text">
          <p>Runes are Markdoc tags that wrap ordinary Markdown. The same list renders as navigation links, a feature grid, or action buttons — depending on which rune contains it.</p>
        </div>
      </div>
    </details>
    <details class="rf-accordion-item" typeof="Question" data-field="item" property="mainEntity" data-rune="accordion-item" data-density="full" data-state="closed">
      <summary data-field="name" property="name" data-name="header" class="rf-accordion-item__header">Do I need to learn a new syntax?</summary>
      <div data-name="body" typeof="Answer" property="acceptedAnswer" class="rf-accordion-item__body" data-section="body">
        <div property="text">
          <p>No. Runes use standard Markdoc tag syntax, and the content inside is regular Markdown.</p>
        </div>
      </div>
    </details>
  </div>
</section>

How Markdown is read

You writeIt becomes
A short paragraph, then a heading and a paragraph, before the first panel headingThe eyebrow, headline and blurb (Page sections)
A headingA panel's title; the content up to the next heading of the same level is its body
An {% accordion-item %} tagA panel, titled by its name

Heading conversion

Headings are automatically converted into accordion items — no explicit tags needed.

{% accordion %}
## What is refrakt.md?

A content framework built on Markdoc.

## How do runes work?

Runes create interpretation contexts for Markdown content.
{% /accordion %}
<section data-rune="accordion" typeof="FAQPage">
  <div data-name="items">
    <details data-rune="accordion-item" typeof="Question" data-field="item" property="mainEntity">
      <summary data-field="name" property="name">What is refrakt.md?</summary>
      <div data-name="body" typeof="Answer" property="acceptedAnswer">
        <div property="text">
          <p>A content framework built on Markdoc.</p>
        </div>
      </div>
    </details>
    <details data-rune="accordion-item" typeof="Question" data-field="item" property="mainEntity">
      <summary data-field="name" property="name">How do runes work?</summary>
      <div data-name="body" typeof="Answer" property="acceptedAnswer">
        <div property="text">
          <p>Runes create interpretation contexts for Markdown content.</p>
        </div>
      </div>
    </details>
  </div>
</section>
What is refrakt.md?

A content framework built on Markdoc.

How do runes work?

Runes create interpretation contexts for Markdown content.

<section class="rf-accordion" typeof="FAQPage" data-rune="accordion" data-density="full">
  <div data-name="items" class="rf-accordion__items">
    <details class="rf-accordion-item" typeof="Question" data-field="item" property="mainEntity" data-rune="accordion-item" data-density="full" data-state="closed">
      <summary data-field="name" property="name" data-name="header" class="rf-accordion-item__header">What is refrakt.md?</summary>
      <div data-name="body" typeof="Answer" property="acceptedAnswer" class="rf-accordion-item__body" data-section="body">
        <div property="text">
          <p>A content framework built on Markdoc.</p>
        </div>
      </div>
    </details>
    <details class="rf-accordion-item" typeof="Question" data-field="item" property="mainEntity" data-rune="accordion-item" data-density="full" data-state="closed">
      <summary data-field="name" property="name" data-name="header" class="rf-accordion-item__header">How do runes work?</summary>
      <div data-name="body" typeof="Answer" property="acceptedAnswer" class="rf-accordion-item__body" data-section="body">
        <div property="text">
          <p>Runes create interpretation contexts for Markdown content.</p>
        </div>
      </div>
    </details>
  </div>
</section>

When the panels are not a FAQ

An accordion declares itself a FAQPage, with each panel a Question and its body an Answer. That is right for a genuine FAQ and wrong for every other use — a list of definitions, a set of options, the universal-attribute sections on these rune pages. Publishing questions that nobody asked is structured data asserting something untrue.

{% accordion schema="none" %}

Suppresses the whole subtree, panels included, and the JSON-LD with it. Nothing else changes — same markup, same classes, same behaviour.

"none" is the only value. FAQPage has no subtype to narrow to, and switching to another type (ItemList, say) would need the container's property renamed and each panel's type and properties changed, which an attribute on the container cannot reach.

Attributes

AttributeTypeRequiredDescription
multipleboolean—Allow multiple panels to be open at once
schema"none"—Set to "none" to emit no schema.org markup. Use it when the panels are not a FAQ — a list of definitions, say — so the page does not publish fabricated Question entries. Suppresses the items too, not just the container.

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

accordion-item

AttributeTypeRequiredDescription
namestring✓

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)
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
prominencethis rune has no page-section header or featured quotation