Sections & blocks›Conversation

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

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

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="{&quot;align&quot;:&quot;left&quot;}" 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="{&quot;align&quot;:&quot;right&quot;}" 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="{&quot;align&quot;:&quot;left&quot;}" 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="{&quot;align&quot;:&quot;right&quot;}" 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>
Alice

Alice: Hey, have you tried refrakt.md yet?

Bob

Bob: Not yet — what makes it different?

Alice

Alice: You write plain Markdown and runes decide how it renders. Same list can be nav links, feature cards, or action buttons.

Bob

Bob: That sounds really flexible. I'll check it out!

<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 writeIt becomes
A blockquoteA 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 setA 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="{&quot;align&quot;:&quot;left&quot;}" 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="{&quot;align&quot;:&quot;right&quot;}" 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="{&quot;align&quot;:&quot;left&quot;}" 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="{&quot;align&quot;:&quot;right&quot;}" 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>
Support

Support: How can I help you today?

Customer

Customer: I'm having trouble with the installation.

Support

Support: Have you tried running npm install with the --legacy-peer-deps flag?

Customer

Customer: That fixed it — thank you!

<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

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

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

conversation-message

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

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