MDX components

MDX is Lisible’s default article format. It keeps all syntax presented in Extended Markdown and allows components inside prose. Every reference below shows complete copyable code, followed immediately by its actual rendering.

Imports

React and Astro components must be imported after frontmatter and before the first content. An import adds no browser JavaScript until its component is used. The github and drawio Markdown directives are provided by the processing pipeline and require no import.

Code

1
---
2
title: "My interactive post"
3
description: "An example using Lisible MDX components."
4
pubDate: 2026-07-19
5
---
6

7
import { Tabs, Tab } from "@/components/ui/tabs";
8
import { Steps, Step } from "@/components/ui/steps";
9
import { Tree } from "@shared/components/ui/file-tree";
10
import Spoiler from "@/components/Spoiler.astro";
11
import Diagram from "@shared/components/Diagram.astro";

Rendered output

Imports produce no visible element. They simply make Tree, Tabs, Tab, Steps, Step, Spoiler and Diagram available to the examples that follow.

File tree

Tree displays an interactive file hierarchy shared by all six variants. Folders can be opened independently, files can be selected and the global control expands or collapses every folder. Use it for project structures where a static text tree would hide useful detail.

Every element needs a unique id and a name. Set type to file or folder; an item with children is also inferred as a folder. isSelectable: false disables selection while preserving the item in the hierarchy.

In an MDX island, use "default" or "none" for sort because Astro serializes properties across the server/client boundary. A comparator function belongs inside a React wrapper component.

Code

1
import { Tree } from "@shared/components/ui/file-tree";
2

3
<Tree
4
  client:load
5
  initialExpandedItems={["src", "pages"]}
6
  initialSelectedId="home"
7
  elements={[
8
    {
9
      id: "src",
10
      name: "src",
11
      type: "folder",
12
      children: [
13
        {
14
          id: "pages",
15
          name: "pages",
16
          type: "folder",
17
          children: [{ id: "home", name: "HomePage.astro", type: "file" }],
18
        },
19
        { id: "styles", name: "styles.css", type: "file" },
20
      ],
21
    },
22
    { id: "config", name: "lisible.config.json", type: "file" },
23
  ]}
24
/>

Rendered output

Tabs

Tabs groups alternative content without making the page longer. Use it for equivalent commands, configuration variants or examples in several languages. Each item in tabs maps to one Tab component in the same order.

Tab accepts MDX content and an optional className property. Keep the number of Tab children equal to the number of labels: panels are matched by position.

Code

1
import { Tabs, Tab } from "@/components/ui/tabs";
2

3
<Tabs
4
  tabs={["bun", "npm", "pnpm"]}
5
  label="Package manager"
6
  defaultTab="npm"
7
  client:load
8
>
9
  <Tab>
10

11
  ```bash
12
  bun install
13
  bun run dev
14
  ```
15

16
  </Tab>
17
  <Tab>
18

19
  ```bash
20
  npm install
21
  npm run dev
22
  ```
23

24
  </Tab>
25
  <Tab>
26

27
  ```bash
28
  pnpm install
29
  pnpm dev
30
  ```
31

32
  </Tab>
33
</Tabs>

Rendered output

bun install
bun run dev

npm install
npm run dev

pnpm install
pnpm dev

The component exposes tablist, tab and tabpanel roles. Left and right arrow keys switch tabs, while Home and End reach the first and last. The label should therefore describe the available choice instead of repeating “tabs”.

Steps

Steps presents an ordered procedure with visual numbering and connectors. Each Step represents one coherent action; its title should begin with a verb, and its body can contain paragraphs, lists, links or code blocks.

This component has no interactive state: do not add a client:* directive. It renders as static HTML.

Code

1
import { Steps, Step } from "@/components/ui/steps";
2

3
<Steps>
4
  <Step title="Create the bilingual pair">
5

6
  Run `bun run new-post guide --translate` to create both `.mdx` files.
7

8
  </Step>
9
  <Step title="Import the components">
10

11
  Put imports after frontmatter and before the first paragraph.
12

13
  </Step>
14
  <Step title="Validate the result">
15

16
  - test keyboard use;
17
  - check light and dark themes;
18
  - run the static build.
19

20
  </Step>
21
</Steps>

Rendered output

1. Create the bilingual pair

   Run bun run new-post guide --translate to create both .mdx files.

2. Import the components

   Put imports after frontmatter and before the first paragraph.

3. Validate the result

   • test keyboard use;
   • check light and dark themes;
   • run the static build.

Spoiler

Spoiler blurs a short answer until a click or activation with Enter or Space. It accepts only its child content and needs no hydration directive because its behavior is owned by the Astro component.

Code

1
import Spoiler from "@/components/Spoiler.astro";
2

3
The answer is <Spoiler>islands architecture</Spoiler>.

Rendered output

The answer is islands architecture.

GitHub card

The github directive turns an owner/repository identifier into a clickable card. The link works immediately, then a client-side script enriches the card with the available description, language, stars and forks. No MDX import is required.

Code

1
::github{repo="didntchooseaname/lisible-docs"}

Rendered output

Use a single card when the repository is the primary destination. For a reference list, plain links remain faster to scan.

draw.io diagram

The drawio directive loads an SVG export created with draw.io into a viewer with zoom, pan, reset and full-screen controls. Full screen uses the same browser API and viewport-overlay fallback as Mermaid and closes with Escape. The Markdown image nested inside the directive acts as a fallback if loading or script execution fails.

The fallback image’s alternative text must describe the information in the diagram. It should not stop at “diagram” or repeat the filename.

Code

1
:::drawio{src="/images/demo-ilots.svg" title="Islands pipeline"}
2
![Pipeline showing content flowing into the six Astro variants](/images/demo-ilots.svg)
3
:::

Rendered output

Inline SVG schematics

Diagram inserts a schematic straight into the HTML rather than loading it through <img>. That is what makes it live: an inline SVG inherits the page custom properties, so its strokes follow the accent the reader picks in the header and its surfaces follow the active theme, with no JavaScript and no extra request. An SVG served through <img> stays isolated from the page and cannot do that.

Three schematics ship with the framework: islands, pipeline and tokens. Pass the locale so the labels and the caption match the article.

Code

1
import Diagram from "@shared/components/Diagram.astro";
2

3
<Diagram id="islands" locale="en" />
4
<Diagram id="pipeline" locale="en" caption="From source file to served page." />

Rendered output

A figure with a caption, sized by aspect ratio so it reserves its space before paint. Add your own by extending the copy map and the drawing branches in shared/components/Diagram.astro.

Choosing hydration

A client:* directive belongs only on a framework component that needs browser JavaScript. Astro components such as Spoiler own their scripts, while purely static components such as Steps need no hydration.

When unsure, start without a directive: add one only when the framework component contains state, an event or a browser API that must run on the client.