core
Conversation
Chat and dialogue display with alternating speaker messages
Source
import Markdoc from '@markdoc/markdoc';
import type { Node } from '@markdoc/markdoc';
const { Ast, Tag } = Markdoc;
import {
createComponentRenderable,
createContentModelSchema,
bodyOnly,
asNodes,
renderNodes,
} from '../lib/index.js';
import { RenderableNodeCursor } from '../lib/renderable.js';
export const conversationMessage = createContentModelSchema({
attributes: {
speaker: { type: String, required: false },
align: { type: String, required: false, matches: ['left', 'right'] },
},
contentModel: bodyOnly(),
transform(resolved, attrs, config) {
const speakerTag = new Tag('span', {}, [attrs.speaker ?? '']);
const alignMeta = new Tag('meta', { content: attrs.align ?? 'left' });
const body = renderNodes(resolved.body, config).wrap('div');
return createComponentRenderable({
rune: 'conversation-message',
tag: 'div',
properties: {
speaker: speakerTag,
align: alignMeta,
},
refs: {
body: body.tag('div'),
},
children: [speakerTag, body.next()],
});
},
});
function convertConversationChildren(nodes: Node[], attrs: Record<string, unknown>): Node[] {
const speakerList = attrs.speakers
? String(attrs.speakers)
.split(',')
.map((s) => s.trim())
: [];
const converted: Node[] = [];
let messageIndex = 0;
for (const node of nodes) {
if (node.type === 'blockquote') {
let speaker = '';
const children = [...node.children];
const firstPara =
children.length > 0 && children[0].type === 'paragraph' ? children[0] : null;
const inlineHost =
firstPara && firstPara.children[0]?.type === 'inline' ? firstPara.children[0] : firstPara;
if (inlineHost) {
const firstInline = inlineHost.children[0];
if (firstInline && firstInline.type === 'strong') {
const nameText = Array.from(firstInline.walk())
.filter((n) => n.type === 'text')
.map((n) => n.attributes.content)
.join('')
.replace(/:\s*$/, '');
speaker = nameText;
}
}
if (!speaker && speakerList.length > 0) {
speaker = speakerList[messageIndex % speakerList.length];
if (inlineHost) {
const strongTag = new Ast.Node('strong', {}, [
new Ast.Node('text', { content: `${speaker}:` }, []),
]);
const spaceText = new Ast.Node('text', { content: ' ' }, []);
inlineHost.children = [strongTag, spaceText, ...inlineHost.children];
}
}
const align = messageIndex % 2 === 0 ? 'left' : 'right';
converted.push(
new Ast.Node(
'tag',
{
speaker,
align,
},
node.children,
'conversation-message',
),
);
messageIndex++;
} else {
converted.push(node);
}
}
return converted;
}
export const conversation = createContentModelSchema({
attributes: {
speakers: {
type: String,
required: false,
description: 'Comma-separated speaker names for alternating messages',
},
},
contentModel: {
type: 'custom',
processChildren: (nodes, attrs) => convertConversationChildren(nodes as Node[], attrs),
description:
'Converts blockquotes to conversation messages with alternating left/right alignment. ' +
'Extracts speaker name from bold text in first paragraph, falls back to speakers list.',
},
transform(resolved, attrs, config) {
const body = new RenderableNodeCursor(
Markdoc.transform(
asNodes(resolved.children),
config,
) as import('@markdoc/markdoc').RenderableTreeNode[],
);
const messages = body.tag('div').typeof('ConversationMessage');
const messagesContainer = messages.wrap('div');
return createComponentRenderable({
rune: 'conversation',
tag: 'div',
properties: {
message: messages,
},
refs: { messages: messagesContainer },
children: [messagesContainer.next()],
});
},
});
Chat-style dialogue display. Blockquotes become alternating speaker messages with a chat bubble UI.
Basic usage
Use blockquotes with bold speaker names to create a conversation.
{% conversation %}
> **Alice:** Hey, have you tried refrakt.md yet?
> **Bob:** Not yet — what makes it different?
> **Alice:** You write plain Markdown and runes decide how it renders. Same list can be nav links, feature cards, or action buttons.
> **Bob:** That sounds really flexible. I'll check it out!
{% /conversation %}<div data-rune="conversation">
<div data-name="messages">
<div data-rune="conversation-message" data-rune-fields="{"align":"left"}" data-field="message">
<span data-field="speaker">Alice</span>
<div data-name="body">
<p>
<strong marker="**">Alice:</strong>
Hey, have you tried refrakt.md yet?
</p>
</div>
</div>
<div data-rune="conversation-message" data-rune-fields="{"align":"right"}" data-field="message">
<span data-field="speaker">Bob</span>
<div data-name="body">
<p>
<strong marker="**">Bob:</strong>
Not yet — what makes it different?
</p>
</div>
</div>
<div data-rune="conversation-message" data-rune-fields="{"align":"left"}" data-field="message">
<span data-field="speaker">Alice</span>
<div data-name="body">
<p>
<strong marker="**">Alice:</strong>
You write plain Markdown and runes decide how it renders. Same list can be nav links, feature cards, or action buttons.
</p>
</div>
</div>
<div data-rune="conversation-message" data-rune-fields="{"align":"right"}" data-field="message">
<span data-field="speaker">Bob</span>
<div data-name="body">
<p>
<strong marker="**">Bob:</strong>
That sounds really flexible. I'll check it out!
</p>
</div>
</div>
</div>
</div><div class="rf-conversation" data-elevation="flush" data-rune="conversation" data-density="compact">
<div data-name="messages" class="rf-conversation__messages">
<div class="rf-conversation-message rf-conversation-message--left" data-field="message" data-align="left" data-rune="conversation-message" data-density="full">
<span data-field="speaker">Alice</span>
<div data-name="body" class="rf-conversation-message__body">
<p>
<strong marker="**">Alice:</strong>
Hey, have you tried refrakt.md yet?
</p>
</div>
</div>
<div class="rf-conversation-message rf-conversation-message--right" data-field="message" data-align="right" data-rune="conversation-message" data-density="full">
<span data-field="speaker">Bob</span>
<div data-name="body" class="rf-conversation-message__body">
<p>
<strong marker="**">Bob:</strong>
Not yet — what makes it different?
</p>
</div>
</div>
<div class="rf-conversation-message rf-conversation-message--left" data-field="message" data-align="left" data-rune="conversation-message" data-density="full">
<span data-field="speaker">Alice</span>
<div data-name="body" class="rf-conversation-message__body">
<p>
<strong marker="**">Alice:</strong>
You write plain Markdown and runes decide how it renders. Same list can be nav links, feature cards, or action buttons.
</p>
</div>
</div>
<div class="rf-conversation-message rf-conversation-message--right" data-field="message" data-align="right" data-rune="conversation-message" data-density="full">
<span data-field="speaker">Bob</span>
<div data-name="body" class="rf-conversation-message__body">
<p>
<strong marker="**">Bob:</strong>
That sounds really flexible. I'll check it out!
</p>
</div>
</div>
</div>
</div>How Markdown is read
| You write | It becomes |
|---|---|
| A blockquote | A message; messages alternate left and right |
Bold text at the start of a blockquote, such as **Alice:** | The message's speaker |
A blockquote with no bold name, when speakers is set | A message from the next name in speakers, in turn |
Named speakers
Use the speakers attribute to automatically alternate between named speakers without inline bold markup.
{% conversation speakers="Support, Customer" %}
> How can I help you today?
> I'm having trouble with the installation.
> Have you tried running npm install with the --legacy-peer-deps flag?
> That fixed it — thank you!
{% /conversation %}<div data-rune="conversation">
<div data-name="messages">
<div data-rune="conversation-message" data-rune-fields="{"align":"left"}" data-field="message">
<span data-field="speaker">Support</span>
<div data-name="body">
<p>
<strong>Support:</strong>
How can I help you today?
</p>
</div>
</div>
<div data-rune="conversation-message" data-rune-fields="{"align":"right"}" data-field="message">
<span data-field="speaker">Customer</span>
<div data-name="body">
<p>
<strong>Customer:</strong>
I'm having trouble with the installation.
</p>
</div>
</div>
<div data-rune="conversation-message" data-rune-fields="{"align":"left"}" data-field="message">
<span data-field="speaker">Support</span>
<div data-name="body">
<p>
<strong>Support:</strong>
Have you tried running npm install with the --legacy-peer-deps flag?
</p>
</div>
</div>
<div data-rune="conversation-message" data-rune-fields="{"align":"right"}" data-field="message">
<span data-field="speaker">Customer</span>
<div data-name="body">
<p>
<strong>Customer:</strong>
That fixed it — thank you!
</p>
</div>
</div>
</div>
</div><div class="rf-conversation" data-elevation="flush" data-rune="conversation" data-density="compact">
<div data-name="messages" class="rf-conversation__messages">
<div class="rf-conversation-message rf-conversation-message--left" data-field="message" data-align="left" data-rune="conversation-message" data-density="full">
<span data-field="speaker">Support</span>
<div data-name="body" class="rf-conversation-message__body">
<p>
<strong>Support:</strong>
How can I help you today?
</p>
</div>
</div>
<div class="rf-conversation-message rf-conversation-message--right" data-field="message" data-align="right" data-rune="conversation-message" data-density="full">
<span data-field="speaker">Customer</span>
<div data-name="body" class="rf-conversation-message__body">
<p>
<strong>Customer:</strong>
I'm having trouble with the installation.
</p>
</div>
</div>
<div class="rf-conversation-message rf-conversation-message--left" data-field="message" data-align="left" data-rune="conversation-message" data-density="full">
<span data-field="speaker">Support</span>
<div data-name="body" class="rf-conversation-message__body">
<p>
<strong>Support:</strong>
Have you tried running npm install with the --legacy-peer-deps flag?
</p>
</div>
</div>
<div class="rf-conversation-message rf-conversation-message--right" data-field="message" data-align="right" data-rune="conversation-message" data-density="full">
<span data-field="speaker">Customer</span>
<div data-name="body" class="rf-conversation-message__body">
<p>
<strong>Customer:</strong>
That fixed it — thank you!
</p>
</div>
</div>
</div>
</div>Attributes
| Attribute | Type | Required | Description |
|---|---|---|---|
speakers | string | — | Comma-separated speaker names for alternating messages |
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 |
conversation-message
| Attribute | Type | Required | Description |
|---|---|---|---|
speaker | string | — | |
align | "left" | "right" | — |
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 |