Basic Markdown

Comark supports full GitHub Flavored Markdown: headings, bold, italic, strikethrough, inline code, blockquotes, lists, tables, links, and horizontal rules.

Rendered Output

Heading 1

Heading 2

Heading 3

This is a paragraph with bold, italic, ~~strikethrough~~, and inline code.

This is a blockquote with nested formatting.

Unordered list item 1
Unordered list item 2
- Nested item

Ordered list item 1
Ordered list item 2

Name	Role	Status
Alice	Engineer	Active
Bob	Designer	Active
Carol	PM	Away

Here is a link to the Comark docs.

MDC Source

# Heading 1
## Heading 2
### Heading 3

This is a paragraph with **bold**, *italic*, ~~strikethrough~~, and `inline code`.

> This is a blockquote with **nested formatting**.

- Unordered list item 1
- Unordered list item 2
  - Nested item

1. Ordered list item 1
2. Ordered list item 2

---

| Name   | Role       | Status  |
|--------|------------|---------|
| Alice  | Engineer   | Active  |
| Bob    | Designer   | Active  |
| Carol  | PM         | Away    |

Here is a [link](https://comark.dev) to the Comark docs.

Block Components

Block components use ::component-name{props} syntax and occupy their own line. They receive children as React children and props from the {key="value"} syntax.

Rendered Output

This is an info alert. Block components use the ::component-name syntax.

This is a warning alert with a different type prop.

This is an error alert. Props are passed via {key="value"} syntax.

This is a success alert. Components receive children as React children.

MDC Source

::alert{type="info"}
This is an **info** alert. Block components use the `::component-name` syntax.
::

::alert{type="warning"}
This is a **warning** alert with a different type prop.
::

::alert{type="error"}
This is an **error** alert. Props are passed via `{key="value"}` syntax.
::

::alert{type="success"}
This is a **success** alert. Components receive children as React children.
::

Inline Components

Inline components use :component-name[content]{props} syntax and flow within paragraph text. Content in brackets becomes the component's children.

Rendered Output

Inline components use a single colon :component-name and flow within text.

The status is Active and priority is High.

You can combine Multiple inline Badges in one paragraph.

MDC Source

Inline components use a single colon `:component-name` and flow within text.

The status is :badge[Active]{color="green"} and priority is :badge[High]{color="red"}.

You can combine :badge[Multiple]{color="blue"} inline :badge[Badges]{color="yellow"} in one paragraph.

Component Props

Components accept props via {key="value"} for strings, {bool} for booleans, {#id} for IDs, and {.class} for CSS classes. All are passed to your React component.

Rendered Output

Components support several attribute syntaxes within {...}:

This alert uses type="warning" as a key-value prop.

Prop Syntax Cheatsheet

key="value" - String prop
bool - Boolean (true)
#my-id - ID attribute
.my-class - CSS class
Multiple: {type="info" .highlighted #special}

MDC Source

Components support several attribute syntaxes within `{...}`:

::alert{type="warning"}
This alert uses `type="warning"` as a key-value prop.
::

::card{title="Prop Syntax Cheatsheet"}
- `key="value"` - String prop
- `bool` - Boolean (true)
- `#my-id` - ID attribute
- `.my-class` - CSS class
- Multiple: `{type="info" .highlighted #special}`
::

YAML Frontmatter Props

For components with many or complex properties (arrays, objects, nested config), use YAML frontmatter between --- delimiters right after the opening :: tag.

Rendered Output

For components with many properties, use YAML frontmatter:

Configuration-Heavy Component

YAML props go between --- delimiters right after the opening :: tag. They support all YAML types: strings, numbers, booleans, arrays, and objects.

YAML props and inline attributes can be combined. Inline attributes take precedence when both specify the same key.

MDC Source

For components with many properties, use YAML frontmatter:

::card
---
title: Configuration-Heavy Component
---
YAML props go between `---` delimiters right after the opening `::` tag. They support all YAML types: strings, numbers, booleans, arrays, and objects.
::

::alert{type="info"}
YAML props and inline attributes can be **combined**. Inline attributes take precedence when both specify the same key.
::

Named Slots

Block components support named slots with #slot-name syntax. In React, the default slot maps to children and named slots become slotPascalName props.

Rendered Output

Custom Header

This goes into the slotHeader prop

This is the default slot content (becomes children).

Footer content goes into the slotFooter prop.

Named slots use #slot-name syntax inside block components. In React:

Default slot becomes children
Named slots become slot{PascalName} props (e.g. #footer becomes slotFooter)

MDC Source

::card{title="Card with Named Slots"}
#header
## Custom Header
*This goes into the `slotHeader` prop*

This is the **default slot** content (becomes `children`).

#footer
Footer content goes into the `slotFooter` prop.
::

Named slots use `#slot-name` syntax inside block components. In React:
- Default slot becomes `children`
- Named slots become `slot{PascalName}` props (e.g. `#footer` becomes `slotFooter`)

Nested Components

Components can be nested inside each other by adding extra colons for each nesting level. The parser matches opening and closing tags automatically.

Rendered Output

Outer Card

This card contains a nested alert component inside it:

I am nested inside a card! Use extra colons (:::) for each nesting level.

And regular markdown continues after the nested component.

MDC Source

::card{title="Outer Card"}
This card contains a **nested** alert component inside it:

:::alert{type="success"}
I am nested inside a card! Use extra colons (`:::`) for each nesting level.
:::

And regular markdown continues after the nested component.
::

Element Attributes

Add custom classes, IDs, styles, and data attributes to native Markdown elements like bold, italic, links, and images using {.class #id key="value"} after the element.

Rendered Output

Comark lets you add attributes to native Markdown elements:

Bold with a class

Italic with an ID

Styled link

Span syntax wraps inline text: highlighted text in a <span>.

Status: Online - uses multiple classes.

MDC Source

Comark lets you add **attributes to native Markdown elements**:

**Bold with a class**{.text-primary}

*Italic with an ID*{#my-italic}

[Styled link](https://comark.dev){target="_blank"}

Span syntax wraps inline text: [highlighted text]{.bg-accent/20 .px-1 .rounded} in a `<span>`.

[Status: Online]{.text-secondary .font-bold} - uses multiple classes.

Plugins

Comark ships with built-in plugins that extend markdown with emoji, syntax highlighting, math, alerts, task lists, and more. Pass them via the plugins prop.

import emoji      from "comark/plugins/emoji"
import footnotes  from "comark/plugins/footnotes"
import math       from "comark/plugins/math"
import highlight  from "comark/plugins/highlight"
import mermaid    from "comark/plugins/mermaid"
import jsonRender from "comark/plugins/json-render"
import security   from "comark/plugins/security"

// Alerts (> [!NOTE]) are built-in — no import needed!

<ComarkClient plugins={[emoji(), math(), footnotes(), highlight(), mermaid(), jsonRender()]}>
  {content}
</ComarkClient>

Alerts (built-in)

GitHub-style alert blockquotes are built into Comark -- no plugin import needed. Uses > [!TYPE] syntax for NOTE, TIP, IMPORTANT, WARNING, and CAUTION. Register a custom blockquote component to add icons and colors.

Rendered Output

GitHub-style alerts are built-in — no plugin import needed:

Note

Useful information that users should know, even when skimming content.

Tip

Helpful advice for doing things better or more easily.

Important

Key information users need to know to achieve their goal.

Warning

Urgent info that needs immediate user attention to avoid problems.

Caution

Advises about risks or negative outcomes of certain actions.

MDC Source

GitHub-style alerts are **built-in** — no plugin import needed:

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

Emoji Plugin

Converts emoji shortcodes like :smile: and :rocket: into real Unicode emoji characters. Import from comark/plugins/emoji. No configuration needed.

Rendered Output

Emoji shortcodes are converted to real emoji characters:

I ❤️ Comark! It's 🚀 fast and ✨ beautiful.

👋 Hello! How are you 😄 today?

Combine with markdown: 🔥 Hot take — Comark is 💯 percent awesome 🎉

Some more: 👍 👎 👀 ⚠️ 💡 📝

MDC Source

Emoji shortcodes are converted to real emoji characters:

I :heart: Comark! It's :rocket: fast and :sparkles: beautiful.

:wave: Hello! How are you :smile: today?

Combine with markdown: **:fire: Hot take** — Comark is _:100: percent_ awesome :tada:

Some more: :thumbsup: :thumbsdown: :eyes: :warning: :bulb: :memo:

Footnotes Plugin

Adds footnote references [^label] and definitions [^label]: content. References become superscript links; definitions collect into a numbered list at the end. Import from comark/plugins/footnotes.

Rendered Output

Comark supports footnotes^[1] with automatic back-references^[2].

References are rendered as superscript links, and definitions are collected into a numbered list at the end of the output.

The standard model^[3] describes three of the four fundamental forces. Gravity is described by general relativity^[4].

Footnotes

Footnotes are rendered as a list at the end of the document. ↩
Each footnote includes a back-reference link to return to the text. ↩
The Standard Model of particle physics classifies all known elementary particles. ↩
Einstein's general theory of relativity, published in 1915. ↩

MDC Source

Comark supports footnotes[^1] with automatic back-references[^2].

References are rendered as superscript links, and definitions are collected
into a numbered list at the end of the output.

The standard model[^sm] describes three of the four fundamental forces.
Gravity is described by general relativity[^gr].

[^1]: Footnotes are rendered as a list at the end of the document.
[^2]: Each footnote includes a back-reference link to return to the text.
[^sm]: The Standard Model of particle physics classifies all known elementary particles.
[^gr]: Einstein's general theory of relativity, published in 1915.

Math Plugin (KaTeX)

Renders LaTeX math with KaTeX. Inline: $E = mc^2$. Display: $$...$$. Requires katex peer dep. Register the Math component for rendering. Import from comark/plugins/math.

Rendered Output

Inline math uses single dollar signs: is Einstein's famous equation.

The quadratic formula is .

Display math uses double dollar signs for block equations:

Mix with markdown: the Pythagorean theorem states that .

MDC Source

Inline math uses single dollar signs: $E = mc^2$ is Einstein's famous equation.

The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$.

Display math uses double dollar signs for block equations:

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

$$
\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}
$$

Mix with markdown: the **Pythagorean theorem** states that $a^2 + b^2 = c^2$.

Syntax Highlighting (Shiki)

Shiki-powered syntax highlighting with dual-theme support. Languages are loaded on demand. Requires shiki peer dep. Import from comark/plugins/highlight.

Rendered Output

Syntax highlighting uses Shiki under the hood:

interface User {
  id: string
  name: string
  email: string
}

function greet(user: User): string {
  return \`Hello, \${user.name}!\`
}

def fibonacci(n: int) -> list[int]:
    """Generate a Fibonacci sequence."""
    a, b = 0, 1
    result = []
    for _ in range(n):
        result.append(a)
        a, b = b, a + b
    return result

MDC Source

Syntax highlighting uses Shiki under the hood:

```typescript
interface User {
  id: string
  name: string
  email: string
}

function greet(user: User): string {
  return \`Hello, \${user.name}!\`
}
```

```python
def fibonacci(n: int) -> list[int]:
    """Generate a Fibonacci sequence."""
    a, b = 0, 1
    result = []
    for _ in range(n):
        result.append(a)
        a, b = b, a + b
    return result
```

Mermaid Diagrams

Renders Mermaid diagrams from ```mermaid code blocks. Requires beautiful-mermaid peer dep. Register the Mermaid component for rendering. Import from comark/plugins/mermaid.

Rendered Output

Mermaid diagrams render from ```mermaid code blocks:

MDC Source

Mermaid diagrams render from \`\`\`mermaid code blocks:

```mermaid
graph TD
    A[Parse MDC] --> B{Has components?}
    B -->|Yes| C[Resolve components]
    B -->|No| D[Render markdown]
    C --> D
    D --> E[React output]
```

JSON Render Plugin

Transforms ```json-render and ```yaml-render code blocks into live UI. The type field in the spec maps to registered component names. Supports both full specs (root + elements tree) and single-element shorthand. Import from comark/plugins/json-render.

Rendered Output

The JSON Render plugin converts ```json-render code blocks into live UI. Element type values map to registered Comark components:

Write a JSON spec

Define your UI tree as JSON with type, props, and children.

Register components

Components referenced by type must be in the components map.

Render

The plugin converts the spec into Comark AST nodes at parse time.

Single-element shorthand also works (YAML variant):

MDC Source

The JSON Render plugin converts \`\`\`json-render code blocks into live UI. Element `type` values map to registered Comark components:

```json-render
{
  "root": "wrapper",
  "elements": {
    "wrapper": {
      "type": "steps",
      "children": ["s1", "s2", "s3"]
    },
    "s1": {
      "type": "step",
      "props": { "title": "Write a JSON spec" },
      "children": ["s1-text"]
    },
    "s1-text": {
      "type": "Text",
      "props": { "content": "Define your UI tree as JSON with type, props, and children." }
    },
    "s2": {
      "type": "step",
      "props": { "title": "Register components" },
      "children": ["s2-text"]
    },
    "s2-text": {
      "type": "Text",
      "props": { "content": "Components referenced by type must be in the components map." }
    },
    "s3": {
      "type": "step",
      "props": { "title": "Render" },
      "children": ["s3-text"]
    },
    "s3-text": {
      "type": "Text",
      "props": { "content": "The plugin converts the spec into Comark AST nodes at parse time." }
    }
  }
}
```

Single-element shorthand also works (YAML variant):

```yaml-render
type: callout
props:
  emoji: "📋"
children:
  - This callout was generated entirely from a YAML spec!
```

Security Sanitization

Sanitizes the parsed AST by removing dangerous elements (script, iframe), blocking malicious protocols (javascript:, vbscript:), and stripping event handlers (onclick, onerror). Import from comark/plugins/security.

Rendered Output

The security plugin sanitizes the AST to prevent XSS:

Before (dangerous input):

<script>alert('XSS')</script> is stripped
<a href="javascript:alert('XSS')">Click</a> has href removed
<img onerror="alert('XSS')" src="x"> has event handler stripped
<iframe src="evil.com"></iframe> is removed (with blockedTags)

After (safe output): The text remains but dangerous elements are neutralized.

Configure with options:

security({
  blockedTags: ['script', 'iframe', 'object', 'embed'],
  allowedProtocols: ['https', 'mailto'],
  allowDataImages: false,
})

MDC Source

The security plugin sanitizes the AST to prevent XSS:

**Before** (dangerous input):
- `<script>alert('XSS')</script>` is stripped
- `<a href="javascript:alert('XSS')">Click</a>` has href removed
- `<img onerror="alert('XSS')" src="x">` has event handler stripped
- `<iframe src="evil.com"></iframe>` is removed (with blockedTags)

**After** (safe output):
The text remains but dangerous elements are neutralized.

Configure with options:

```typescript
security({
  blockedTags: ['script', 'iframe', 'object', 'embed'],
  allowedProtocols: ['https', 'mailto'],
  allowDataImages: false,
})
```

TOC Plugin

Generates a hierarchical table of contents from headings and stores it in tree.meta.toc. Heading IDs are auto-generated for anchor linking. Import from comark/plugins/toc.

Rendered Output

The TOC plugin extracts a table of contents from headings:

Introduction

Welcome to the docs.

Getting Started

Install the package.

Prerequisites

Make sure you have Node.js installed.

API Reference

Full API documentation.

Core Functions

The main parsing functions.

Plugins

Extend with plugins.

MDC Source

The TOC plugin extracts a table of contents from headings:

# Introduction

Welcome to the docs.

## Getting Started

Install the package.

### Prerequisites

Make sure you have Node.js installed.

## API Reference

Full API documentation.

### Core Functions

The main parsing functions.

### Plugins

Extend with plugins.

Excerpt / Summary Plugin

Splits content at the  delimiter to extract excerpts for blog post previews or meta descriptions. The excerpt is exposed via tree.meta.summary. Import from comark/plugins/summary.

Rendered Output

This is the excerpt content that appears before the delimiter. It's typically used for blog post previews, summaries, or meta descriptions.

This is the rest of the content that comes after the excerpt delimiter. In a blog, this would only be visible on the full post page, not in the listing.

The summary plugin splits content at the  delimiter and exposes the excerpt via the parsed tree's data.

MDC Source

This is the excerpt content that appears before the delimiter. It's typically used for blog post previews, summaries, or meta descriptions.

<!--more-->

This is the rest of the content that comes after the excerpt delimiter. In a blog, this would only be visible on the full post page, not in the listing.

The `summary` plugin splits content at the `<!--more-->` delimiter and exposes the excerpt via the parsed tree's data.

Styling Guide

Three layers control how Comark output looks: global CSS rules, inline element attributes, and custom component styling.

How the 3 layers work together

Layer 1

.comark-output CSS

Global rules in globals.css style native markdown elements: headings, lists, tables, code, blockquotes.

Layer 2

Element Attributes {.class}

Inline {.class #id} syntax adds Tailwind classes directly to markdown elements in your MDC content.

Layer 3

Component Styling

Custom React components own their visual design. MDC passes data via props; the component renders with Tailwind, CSS modules, or any approach.

Layer 1: Global CSS Rules

The .comark-output class in globals.css provides base styles for all native markdown elements. These rules use Tailwind's @apply for consistent theming. Override or extend them to change the look of all rendered markdown.

Rendered Output

The .comark-output CSS class controls how native markdown elements look (headings, paragraphs, lists, tables, code, etc.).

This heading is styled by CSS

Paragraphs, bold, italic, and inline code all inherit their styles from the .comark-output ruleset in globals.css.

List items get bullets and spacing
From the same CSS layer

Element	Styled By
Heading	`.comark-output h1`
Code	`.comark-output code`
Table	`.comark-output table`

Blockquotes get a left border and italic styling from CSS.

MDC Source

The `.comark-output` CSS class controls how **native markdown elements** look (headings, paragraphs, lists, tables, code, etc.).

# This heading is styled by CSS

Paragraphs, **bold**, *italic*, and `inline code` all inherit their styles from the `.comark-output` ruleset in `globals.css`.

- List items get bullets and spacing
- From the same CSS layer

| Element | Styled By          |
|---------|-------------------|
| Heading | `.comark-output h1` |
| Code    | `.comark-output code` |
| Table   | `.comark-output table` |

> Blockquotes get a left border and italic styling from CSS.

Layer 2: Inline Element Attributes

Use {.tailwind-class} after any markdown element to add Tailwind classes inline. This is Comark's attribute syntax -- it works on bold, italic, links, spans, and more. Multiple classes are space-separated.

Rendered Output

Comark lets you apply Tailwind classes directly in Markdown using attribute syntax.

Colored Text

This text is teal and this is the primary color.

Background Highlights

Here is an inline highlight within a sentence.

Combined Styles

Styled span with multiple classes.

On Native Elements

Bold with color

Italic with a class

External link(https://comark.dev)

MDC Source

Comark lets you apply **Tailwind classes directly** in Markdown using attribute syntax.

### Colored Text

[This text is teal]{.text-secondary .font-semibold} and [this is the primary color]{.text-primary}.

### Background Highlights

Here is [an inline highlight]{.bg-accent/20 .px-1.5 .py-0.5 .rounded} within a sentence.

### Combined Styles

[Styled span]{.bg-primary/10 .text-primary .font-bold .px-2 .py-1 .rounded-md .text-sm} with multiple classes.

### On Native Elements

**Bold with color**{.text-destructive}

*Italic with a class*{.text-secondary}

[External link]{.text-accent .no-underline .font-bold}(https://comark.dev)

Layer 3: Component Styling

Custom MDC components are regular React components styled however you like. Props from MDC (type, title, etc.) drive variant logic inside the component. The MDC author writes semantic markup; the component author controls the visual output.

Rendered Output

Custom React components are styled with regular Tailwind CSS inside the component file. Props from MDC become React props:

This alert's look comes from the React component, not from MDC attributes. The type prop maps to a style variant.

Styled by the Card component

Components own their own styles. MDC just passes data (props, children, slots). The React component decides how to render.

MDC Source

Custom React components are styled with regular **Tailwind CSS** inside the component file. Props from MDC become React props:

::alert{type="info"}
This alert\'s look comes from the React component, not from MDC attributes. The `type` prop maps to a style variant.
::

::card{title="Component Styling"}
#header
*Styled by the Card component*

Components own their own styles. MDC just passes **data** (props, children, slots). The React component decides how to render.
::

Streaming Mode

Comark can render content as it arrives, token by token. The streaming prop tells the renderer content is still arriving, and caret adds a blinking cursor. The parser auto-closes incomplete markdown so partial bold, lists, and components render correctly mid-stream.

Press "Start Stream" to simulate an LLM streaming response...

Live Playground

Edit the MDC source on the left and see the rendered output update in real time. All registered components (alert, card, badge, callout, steps, step, tabs, divider) are available.

Editor

Preview

Try it yourself!

Write any Markdown here and use Comark components.

Edit this text to see live rendering below.

Your Card

Cards support markdown in their body.

And named slots like this footer.

Inline components work too: Cool right in text.

LLM System Prompt

Copy this system prompt and give it to any LLM (GPT, Claude, Gemini, etc.) so it knows how to write content using your registered Comark components. It covers MDC syntax, all available components, built-in features, and best practices.

system-prompt.md200 lines

You are a content writer that outputs structured Markdown using **Comark MDC syntax** — an extension of standard Markdown that adds component directives.

## Rules

1. Write valid CommonMark Markdown for all standard formatting (headings, bold, italic, links, lists, code blocks, blockquotes, tables).
2. Use MDC component syntax to embed rich UI components. Components are case-sensitive and must match the registered names exactly.
3. Never invent component names that are not listed below.
4. Every block component must be closed with `::` (or matching colons for nested levels).

---

## MDC Syntax Reference

### Block Components

Open with `::`, close with `::`. Props go in curly braces. Content between the delimiters becomes `children`.

```
::component-name{prop="value" anotherProp="value"}
Markdown content here (rendered as children)
::
```

### Inline Components

Single colon, square brackets for visible text, curly braces for props:

```
:component-name[visible text]{prop="value"}
```

### YAML Frontmatter Props

For complex props (arrays, objects), use a YAML block between `---` fences inside the component:

```
::component-name
---
title: My Title
items:
  - one
  - two
---
Body content
::
```

### Named Slots

Use `#slotName` inside a block component to assign content to a named slot:

```
::card{title="Example"}
#header
This goes into the slotHeader prop

Default content goes into children

#footer
This goes into the slotFooter prop
::
```

### Nesting Components

Add extra colons for each nesting level:

```
::outer
:::inner
Content
:::
::
```

### Element Attributes

Add attributes to inline markdown elements:

```
**bold text**{.my-class}
[styled span]{.bg-accent .px-2}
```

---

## Available Components

### `alert` (block)
Colored alert box with icon. Types: info, warning, error, success.
```
::alert{type="info"}
This is an informational message.
::
```

### `card` (block)
Card with optional title and named slots for header/footer.
```
::card{title="Card Title"}
#header
Optional header content

Main body content

#footer
Optional footer content
::
```

### `badge` (inline)
Colored inline label. Colors: blue, green, red, yellow, default.
```
Status: :badge[Active]{color="green"} or :badge[Deprecated]{color="red"}
```

### `callout` (block)
Callout box with a leading emoji.
```
::callout{emoji="💡"}
A helpful tip for the reader.
::
```

### `steps` + `step` (block, nested)
Numbered step-by-step instructions.
```
::steps
:::step{title="Install"}
Run \`pnpm add comark\`
:::
:::step{title="Configure"}
Add your components.
:::
::
```

### `tabs` (block)
Tabbed content panel. List tab names in the `tabs` prop (comma-separated). Content goes in default slot and `#tab1`, `#tab2`, etc.
```
::tabs{tabs="React,Vue,Svelte"}
React example code here (first tab = default slot)

#tab1
Vue example code here

#tab2
Svelte example code here
::
```

### `divider` (block)
Horizontal divider with optional label.
```
::divider{label="Section Break"}::
```

---

## Built-in Features (no component needed)

### GitHub-style Alerts
```
> [!NOTE]
> Useful information.

> [!TIP]
> Helpful advice.

> [!WARNING]
> Urgent information.

> [!CAUTION]
> Negative consequences.
```

### Math (if math plugin enabled)
- Inline: `$E = mc^2$`
- Display: `$$\\int_0^1 x^2 dx$$`

### Mermaid Diagrams (if mermaid plugin enabled)
```
\`\`\`mermaid
graph TD
    A --> B --> C
\`\`\`
```

---

## Guidelines

- Prefer semantic components over raw HTML.
- Use `alert` for important callouts, not raw blockquotes.
- Use `steps` for tutorials and how-to guides.
- Use `tabs` to show alternatives (e.g., different languages or package managers).
- Use `badge` inline to highlight statuses, labels, or tags.
- Use `card` to visually group related content with a title.
- Use standard Markdown for everything else (headings, paragraphs, lists, code, links, images, tables).
- Never output raw HTML. Always use Markdown or MDC components.

Footnotes

Footnotes are rendered as a list at the end of the document. ↩
Each footnote includes a back-reference link to return to the text. ↩
The Standard Model of particle physics classifies all known elementary particles. ↩
Einstein's general theory of relativity, published in 1915. ↩

Basic Markdown

Heading 1

Heading 2

Heading 3

Block Components

Inline Components

Component Props

Prop Syntax Cheatsheet

YAML Frontmatter Props

Configuration-Heavy Component

Named Slots

Custom Header

Nested Components

Outer Card

Element Attributes

Plugins

Alerts (built-in)

Emoji Plugin

Task List Plugin

Footnotes Plugin

Footnotes

Math Plugin (KaTeX)

Syntax Highlighting (Shiki)

Mermaid Diagrams

JSON Render Plugin

Write a JSON spec

Register components

Render

Security Sanitization

TOC Plugin

Introduction

Getting Started

Prerequisites

API Reference

Core Functions

Plugins

Excerpt / Summary Plugin

Styling Guide

How the 3 layers work together

Layer 1: Global CSS Rules

This heading is styled by CSS

Layer 2: Inline Element Attributes

Colored Text

Background Highlights

Combined Styles

On Native Elements

Layer 3: Component Styling

Streaming Mode

Live Playground

Try it yourself!

Your Card

LLM System Prompt

Heading 1

Heading 2

Heading 3

Prop Syntax Cheatsheet

Configuration-Heavy Component

Custom Header

Outer Card

Footnotes

Write a JSON spec

Register components

Render

Introduction

Getting Started

Prerequisites

API Reference

Core Functions

Plugins

This heading is styled by CSS

Colored Text

Background Highlights

Combined Styles

On Native Elements

Try it yourself!

Your Card