Components in Markdown: Block and Inline Syntax

Embed custom components directly in your Markdown with block and inline syntax, props, slots, and nested children.

Comark extends Markdown with component syntax so you can embed custom UI in plain text. The built-in components plugin parses this syntax and is enabled by default.

Comark also supports declarative UI specs in json-render code blocks. See the json-render plugin.

Block

Block components use the ::component-name syntax and occupy their own line:

::component-name{prop1="value1" prop2="value2"}
Content inside the component

Can have **Markdown** and other elements
::

Examples of block components:

::alert{type="info"}
This is an important message!
::

Inline

Inline components use the :component-name syntax and can be placed within text:

Check out this :icon-star component in the middle of text.

Click the :button[Submit]{type="primary"} to continue.

The status is :badge[Active]{color="green"} right now.
SyntaxDescription
:icon-checkStandalone inline component
:badge[New]Inline component with content
:badge[New]{color="blue"}Inline component with content and properties
:tooltip{text="Hover text"}Inline component with properties only

Properties

Components support two property syntaxes: inline attributes and YAML frontmatter.

Inline attributes

Use the {...} syntax for scalar properties:

::component{prop="value"}
<!-- Standard key-value pair -->
::

::component{bool}
<!-- Boolean property (becomes :bool="true" in AST) -->
::

::component{#custom-id}
<!-- ID attribute -->
::

::component{.class-name}
<!-- CSS class -->
::

::component{.class-one .class-two}
<!-- Multiple CSS classes -->
::

::component{:obj='{"key": "value"}'}
<!-- Object/JSON value -->
::

::component{multiple="props" bool #id .class}
<!-- Multiple properties combined -->
::

Block props

For components with many properties, use YAML block syntax inside the component. Two styles are supported:

::component
```yaml [props]
title: My Component
type: info
count: 42
enabled: true
items:
  - First item
  - Second item
config:
  theme: dark
  mode: auto
```
Component content goes here

With **Markdown** support
::
Objects stay objects, arrays stay arrays, and numbers and booleans keep their types instead of becoming strings. Your components receive typed props.

Key rules

  • Must be at the very beginning of the component content
  • Enclosed by --- delimiters (frontmatter style) or ```yaml [props] fences (code block style)
  • Merged with inline attributes (YAML props take precedence, and class values are merged)
  • Supports nested objects and arrays
The default style can be configured with the blockAttributesStyle option.

Combine both syntaxes

Inline attributes and YAML props can be combined. YAML props take precedence, except class values which are merged:

::card{.featured}
```yaml [props]
title: Featured Article
author: Jane Doe
tags:
  - markdown
  - documentation
```
This combines inline class `.featured` with YAML props
::

Use cases

Configuration-heavy components:

::data-table
```yaml [props]
columns:
  - name: Name
    field: name
    sortable: true
  - name: Email
    field: email
    sortable: true
options:
  striped: true
  pageSize: 10
```
::

API documentation:

::api-endpoint
```yaml [props]
method: POST
path: /api/users
parameters:
  - name: username
    type: string
    required: true
  - name: email
    type: string
    required: true
response:
  status: 201
  body:
    id: string
    username: string
```
::

Data binding

Props prefixed with : are parsed as JSON at render time. When the value isn't valid JSON, the renderer resolves it as a dot-path against an ambient render context, so you can reference runtime data, frontmatter, plugin metadata, or the enclosing component's props without hardcoding them.

Scope

The render context exposes four namespaces:

NamespaceSource
frontmatterThe document's YAML frontmatter
metaPlugin-populated metadata on the parsed tree
dataRuntime values passed via the renderer's data prop
propsThe enclosing component's own props

Frontmatter

Reference any value declared in the document's frontmatter:

---
theAnswer: 42
user:
  name: Ada
---

::question{:answer="frontmatter.theAnswer"}
::

Hello, :badge{:label="frontmatter.user.name"}

Runtime data

Pass values from your app via the renderer's data prop and reference them under the data. namespace:

<Markdown :value="content" :data="{ user: { name: 'Ada' } }" />
Welcome, :badge{:label="data.user.name"}!

Parent component props

Nested components can read the enclosing component's resolved props through the props. namespace. This is useful when a child needs a value declared once on its parent:

::card{title="Hello" variant="primary"}
  :::badge{:color="props.variant" :text="props.title"}
  :::
::

Resolution rules

  • If the :prefixed value is a valid JSON literal (for example 5, true, "foo", {"a":1}), it's used as-is.
  • Otherwise, the value is treated as a dot-path and resolved against { frontmatter, meta, data, props }.
  • Unknown paths resolve to undefined, so the prop receives undefined rather than the raw string.
  • Only props authored with the : prefix participate in data binding. Plain prop="value" attributes are always passed as literal strings.
Need to interpolate a value directly into text rather than a prop? The binding plugin adds a {{ path || default }} inline shorthand that resolves against the same render context.

Slots

Block components support slots for passing structured content to components.

Default slot

Content placed directly inside a component goes to the default slot, no prefix needed:

::alert{type="info"}
This content goes to the default slot.
::

You can also write #default explicitly, which is useful when mixing it with named slots:

::card
#default
This is the **default** slot content.

#footer
Footer content here.
::

Named slots

::card
#header
## Card Title

#content
This is the main content of the card

#footer
Footer text here
::

Combine with props

You can use both YAML block props and named slots in the same component:

::card{.featured}
```yaml [props]
variant: elevated
color: primary
actions:
  - label: Read More
    url: /article
  - label: Share
    icon: share
```
#header
## Article Title
*By Jane Doe*

#content
This is the main article content with **Markdown** support.

#footer
Published on January 15, 2024
::
YAML block props must come immediately after the opening ::component line, before any slot definitions.

Correct order:

::component{inline-attrs}
```yaml [props]
yaml: props
```
#slot-name
Slot content
::

Incorrect order:

::component
#slot-name
Slot content
```yaml [props]
yaml: props  <!-- This won't work -->
```
::

Nested

Components can be nested within each other using additional colons:

::outer-component
Content in outer

:::inner-component{variant="compact"}
Content in inner
:::

More content in outer
::

Deep nesting:

::level-1
  :::level-2
    ::::level-3
    Content
    ::::
  :::
::
Extra colons on nested components are optional, since the parser matches opening and closing tags directly. Adding one colon per nesting level keeps deeply nested blocks readable at a glance.

This also works:

::level-1
  ::level-2
    ::level-3
    Content
    ::
  ::
::
© 2026 Vercel, Inc.