Extended Markdown

Lisible supports standard Markdown, GFM and several extensions designed for technical writing. Every example below first shows the code to write, followed by its actual rendering. Behavior matches across all six variants even when their styling changes. For real interactions, continue with MDX components.

Headings and paragraphs

Use a single level-one title in frontmatter through title. Start the article body at ## for main sections, then move down without skipping a level. Level-two through level-four headings automatically receive a copyable anchor.

Code

1
#### An example heading
2

3
A paragraph remains one sequence of lines without a blank line.
4
A blank line starts a new paragraph.

Rendered output

An example heading

A paragraph remains one sequence of lines without a blank line. A blank line starts a new paragraph.

Inline formatting

Use emphasis to structure a sentence, not as a replacement for headings. GFM adds strikethrough text. Inline code suits short commands, filenames and identifiers. The HTML mark and kbd elements are accepted in MDX for highlighting and keyboard keys.

Code

1
Text can be **important**, *nuanced*, ~~obsolete~~ or contain `const value = 1`.
2

3
Press <kbd>Ctrl</kbd> + <kbd>K</kbd> to open <mark>search</mark>.

Rendered output

Text can be important, nuanced, obsolete or contain const value = 1.

Press Ctrl + K to open search.

Links

Link text should describe its destination. Use a route starting with / for an internal page and an absolute URL for an external website. An optional title can add hover context but does not replace descriptive link text.

Code

1
Read the [content model](/en/docs/authoring/content/) or the [Astro documentation](https://docs.astro.build/ "Official Astro documentation").

Rendered output

Read the content model or the Astro documentation.

Images

Put shared files in public/images, then reference them from the site root. Alternative text describes the information carried by the image; leave it empty only for a strictly decorative image. The quoted title is optional.

Dimensions are not your responsibility: at build time Lisible reads the intrinsic size of every local image (SVG, PNG, JPEG, GIF) and sets width, height, loading="lazy" and decoding="async" on the emitted tag. Space is reserved before the image loads, so it never shifts the layout.

Code

1
![Astro islands pipeline](/images/demo-ilots.svg "Rendering pipeline")

Rendered output

Lists

Markdown supports unordered, ordered and nested lists. GFM adds tasks through - [ ] and - [x]; rendered checkboxes are informational and do not modify the source file.

Code

1
- Write the draft
2
  - Add examples
3
- Review the content
4

5
1. Build the site
6
2. Check the links
7

8
- [x] Documentation written
9
- [ ] Review complete

Rendered output

• Write the draft
  • Add examples
• Review the content

1. Build the site
2. Check the links

• Documentation written
• Review complete

Blockquotes

Prefix every quoted paragraph with >. A nested quote uses >>. Add the source in the prose or through a link: Markdown cannot infer it.

Code

1
> Performance is an editorial feature.
2
>
3
> Lisible team

Rendered output

Performance is an editorial feature.

Lisible team

Tables

The second line defines each column’s alignment: :--- for left, :---: for center and ---: for right. Wide tables become horizontally scrollable on small screens.

Code

1
| Variant | Use | Posts |
2
| :--- | :---: | ---: |
3
| Organique | Editorial | 12 |
4
| Terminal | Technical | 8 |

Rendered output

Footnotes

A [^id] reference points to a definition with the same identifier. Definitions can stay near their source paragraph; the renderer gathers them at the end of the page and adds return links automatically.

Code

1
Islands reduce the JavaScript sent to the browser.[^islands]
2

3
[^islands]: Astro hydrates only components marked with a client directive.

Rendered output

Islands reduce the JavaScript sent to the browser.¹

Collapsible details

The native HTML details element hides non-essential supporting content. Its summary should clearly announce what will be revealed. Add open to display the content on initial load.

Code

1
<details>
2
  <summary>Show the complete command</summary>
3

4
  Run `bun run check:all` before deployment.
5
</details>

Rendered output

Horizontal rule

Three hyphens on their own line create a thematic break. Reserve it for significant topic changes; headings are sufficient in most sections.

Code

1
End of the first part.
2

3
---
4

5
Start of the next part.

Rendered output

End of the first part.

Start of the next part.

Callouts

A callout highlights information that deserves a specific level of attention. Available variants are note, tip, important, warning and caution. Text in brackets replaces the translated default title.

Code

1
:::note[Context]
2
Drafts remain visible during development.
3
:::
4

5
:::tip[Save time]
6
Run checks before pushing.
7
:::
8

9
:::important[Required configuration]
10
Set the public URL before building.
11
:::
12

13
:::warning[Before deploying]
14
Check internal links.
15
:::
16

17
:::caution[Destructive action]
18
Back up data before a migration.
19
:::

Rendered output

Collapsible callout

Add the {collapse} attribute after the title to turn the callout into a native collapsible region. Its content remains in the page and must therefore never contain a secret.

Code

1
:::note[Optional details]{collapse}
2
This explanation can be opened on demand.
3
:::

Rendered output

Expressive Code blocks

Expressive Code provides Shiki highlighting, copy controls, a language badge, file and terminal frames, line numbers, word wrapping, text and line markers, and collapsible code sections. Always place the language immediately after the opening three backticks.

Lines, ranges and labels

A block can combine neutral highlights, additions and deletions. Selectors accept one line, comma-separated lines and inclusive ranges. Text before : adds a visible label.

Code

1
```ts title="src/users.ts" {2,8-9} ins={"Added":4-5} del={"Removed":7}
2
interface User {
3
  id: string;
4
  name: string;
5
  plan: "free" | "pro";
6
  lastLogin: Date;
7
}
8
const legacyUser = loadLegacyUser();
9
export function displayName(user: User) {
10
  return user.name.trim();
11
}
12
```

Rendered output

1
interface User {
2
  id: string;
3
  name: string;
4
  plan: "free" | "pro";
5
  lastLogin: Date;
6
}
7
const legacyUser = loadLegacyUser();
8
export function displayName(user: User) {
9
  return user.name.trim();
10
}

Inline markers

A quoted string highlights all its occurrences. Prefix it with ins= or del= to give it inserted or deleted meaning. A /.../ expression accepts regular expressions; when it contains a capture group, only the captured part is marked.

Code

1
```ts "user.name" ins="cache.get" del="legacyToken" /user(Id|Name)/
2
const userId = request.params.id;
3
const legacyToken = request.headers.token;
4
const cached = cache.get(userId);
5
return user.name ?? cached;
6
```

Rendered output

1
const userId = request.params.id;
2
const legacyToken = request.headers.token;
3
const cached = cache.get(userId);
4
return user.name ?? cached;

Diff with language highlighting

The diff language interprets + and - as additions and deletions. Add lang="ts" to keep TypeScript highlighting; alignment whitespace before unchanged lines is removed in the rendered block.

Code

1
```diff lang="ts" title="src/config.ts"
2
  export const config = {
3
-   locale: "fr",
4
+   locale: "en",
5
    trailingSlash: true,
6
  };
7
```

Rendered output

1
export const config = {
2
  locale: "fr",
3
  locale: "en",
4
  trailingSlash: true,
5
};

Collapsible code sections

collapse accepts multiple ranges. The project uses collapseStyle=collapsible-auto by default: the summary remains available after expansion and is placed on the most logical side of the range. Other values are github (one-way expansion), collapsible-start (summary first) and collapsible-end (summary last). Add collapsePreserveIndent=false to align the summary to the left.

Code

1
```ts title="src/server.ts" collapse={1-4,8-10} collapseStyle=collapsible-auto
2
import { logger } from "./logger";
3
import { metrics } from "./metrics";
4
const app = createApp();
5
app.use(logger, metrics);
6
app.get("/health", () => {
7
  return new Response("ok");
8
});
9
app.listen(4321);
10
console.log("ready");
11
process.on("SIGTERM", shutdown);
12
```

Rendered output

4 collapsed lines
1
import { logger } from "./logger";
2
import { metrics } from "./metrics";
3
const app = createApp();
4
app.use(logger, metrics);
5
app.get("/health", () => {
6
  return new Response("ok");
7
});
3 collapsed lines
8
app.listen(4321);
9
console.log("ready");
10
process.on("SIGTERM", shutdown);

Frames, numbering and wrapping

title automatically creates an editor frame for a file. Shell languages use a terminal; frame="none" suits isolated commands. startLineNumber changes displayed numbers only: markers still count from the first source line.

Code

1
```ts title="src/config.ts" startLineNumber=40 wrap=true preserveIndent=true hangingIndent=2 {2}
2
export const description =
3
  "A deliberately long line that preserves its indentation when it wraps inside a narrow content column.";
4
```
5

6
```bash frame="none" showLineNumbers=false
7
bun run check:all
8
```

Rendered output

40
export const description =
41
  "A deliberately long line that preserves its indentation when it wraps inside a narrow content column.";

bun run check:all

References: text and line markers, frames, line numbers, word wrap and collapsible sections.

Mathematics

KaTeX renders LaTeX expressions. A formula between two $ delimiters stays inline; a block wrapped in $$ is centered and separated from the paragraph. Use LaTeX commands supported by KaTeX.

Code

1
The relation $E = mc^2$ is rendered inside the sentence.
2

3
$$
4
L = -\sum_{i=1}^{n} y_i \log(\hat{y}_i)
5
$$

Rendered output

The relation $E = mc^2$ is rendered inside the sentence.

Mermaid

A mermaid fence becomes an interactive diagram. Its toolbar provides zoom, pan, reset, source copy and full-screen controls; colors synchronize with the light or dark theme. Full screen uses the browser API when available and a viewport overlay fallback otherwise. Exit with the toolbar button or Escape. The content itself follows Mermaid syntax.

Code

1
```mermaid
2
flowchart TD
3
  MD[Markdown] --> R[remark]
4
  R --> H[rehype]
5
  H --> HTML[Static HTML]
6
  HTML --> M[Interactive Mermaid]
7
```

Rendered output

Diagram
100%
Rendering diagram...
Scroll to zoom, drag to pan