Custom Components (Directives)

zudo-text supports a set of custom Markdown components called directives that you can use in your notes and archives. They are rendered live in the preview pane and can be inserted quickly via the Insert Component picker (Mod+Shift+I).

Directives use the remark-directive syntax, which is a deliberate CommonMark extension. Container directives use :::name fences, text/inline directives use :name[text].

Admonitions

Admonitions are colored callout boxes for notes, tips, warnings, and similar content.

note

:::note
A general remark without a title.
:::

:::note[Custom Title]
A note with an explicit title.
:::

tip

:::tip
A helpful tip or best practice.
:::

:::tip[Pro Tip]
Always prefer semantic tokens over raw pixel values.
:::

info

:::info
Informational content relevant to the surrounding context.
:::

:::info[Did you know?]
React Server Components can render on the server.
:::

warning

:::warning
Something might go wrong. Proceed with caution.
:::

:::warning[Deprecation Warning]
This API will be removed in the next major version.
:::

danger

:::danger
Critical issue — data loss may occur.
:::

:::danger[Stop!]
Do not delete this file. It is required for the system to function.
:::

Steps

The steps directive renders a numbered step list. Each paragraph inside the fence becomes one step.

:::steps
Install the dependencies.

Configure the settings file.

Run the development server.
:::

Card and Card Grid

card renders an info card with a title, optional icon, optional link, and a variant style. card-grid arranges cards in columns.

card

:::card{title="My Card"}
Card body content.
:::

:::card{title="Highlighted" variant=highlight}
This card stands out.
:::

:::card{title="Outline" variant=outline}
A card with an outline style.
:::

:::card{title="Linked Card" href="https://example.com"}
Click this card to open the link.
:::

Attributes:

Attribute	Type	Required	Default
`title`	string	yes	—
`icon`	string	no	—
`href`	string	no	—
`variant`	`default` \| `highlight` \| `outline`	no	`default`

card-grid

Wrap multiple card directives in a card-grid to arrange them in columns.

::::card-grid{cols=2}
:::card{title="Card A"}
Body A.
:::

:::card{title="Card B"}
Body B.
:::
::::

Attributes:

Attribute	Type	Required	Default
`cols`	`2` \| `3` \| `4`	no	`2`

Figure

The figure directive wraps content in an HTML <figure> element with an optional caption and alignment.

:::figure{caption="A code example" align=center}
```js

console.log("hello")

:::


**Attributes:**

| Attribute | Type | Required | Default |
| --- | --- | --- | --- |
| `caption` | string | no | — |
| `align` | `left` \| `center` \| `right` | no | — |

---

## Badge (inline)

The `badge` directive is an inline text directive that renders a small colored label. Use it inside a paragraph.

```md
This feature is :badge[NEW]{variant=success}.

This API is :badge[DEPRECATED]{variant=danger}.

Attributes:

Attribute	Type	Required	Default
`variant`	`default` \| `success` \| `warning` \| `danger`	no	`default`

Image Attributes

Image attributes are a deliberate CommonMark extension that let you control the width, alignment, and caption of images using curly-brace syntax appended to the image markup.

![Alt text](./image.png){w=1/2}

![Alt text](./image.png){w=1/3 align=right}

![Alt text](./image.png){w=2/3 align=center caption="A beautiful landscape photo"}

Attributes:

Attribute	Values	Description
`w`	`1/4`, `1/3`, `1/2`, `2/3`, `3/4`, `full`	Image width as a fraction of the container
`align`	`left`, `center`, `right`	Horizontal alignment of the image
`caption`	string	Wraps the image in a `<figure>` with a `<figcaption>`

Inserting Directives

Press Mod+Shift+I (or use the Insert Component command in the command palette) to open the directive picker. Select a directive from the visual tile grid and it is inserted at the cursor with placeholder content ready to edit.

Directive autocomplete can be enabled or disabled in Settings → Editor → Enable Directive Autocomplete.