Using Markdown

Pages are written in Markdown. Every example on this page renders live.

Syntax-highlighted code blocks ​

Highlighting uses grammar-based tokenization¹ for about 65 bundled languages:

public sealed record Order(string Id, decimal Total)
{
    public bool IsLarge => Total > 1000m;
}

def fibonacci(n: int) -> int:
    if n < 2:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

public class Greeter {
    public String greet(String name) {
        return "Hello, " + name + "!";
    }
}

fn main() {
    let nums = vec![1, 2, 3];
    println!("{:?}", nums.iter().sum::<i32>());
}

SELECT id, title FROM pages WHERE published = true ORDER BY title;

Aliases resolve to full grammar IDs: c#, cs and dotnet for C#, f# for F#, c++ for C++. Unknown languages render without highlighting.

Title bars ​

[filename] in the fence info string renders a title bar instead of the language badge:

```json [src/appsettings.json]
{
    "Hello": "world"
}
```

Renders as:

{
    "Hello": "world"
}

Line highlighting ​

{n,m-o} in the fence info string highlights lines:

function add(a: number, b: number) {
  return a + b; // this line is highlighted
}

A trailing // [!code highlight] comment also highlights a line; the comment is removed from output:

const cache = new Map();
const ttlMs = 60_000;

Diff notation ​

const port = 3000;
const port = process.env.PORT ?? 3000;

Focus ​

function setup() {
  loadConfig();
  startServer();
}

Line numbers ​

const a = 1;
const b = 2;
const c = a + b;

Code groups ​

This example:

::: code-group
```sh [npm]
npm install
```
```sh [pnpm]
pnpm install
```
```sh [c# icon:sharp]
dotnet restore
```
:::

Renders as:

npm install

pnpm install

dotnet restore

[label] sets the tab title. Labels matching a Simple Icons name display that icon. [label icon:slug] sets the icon explicitly, for example [csharp icon:dotnet].

Alerts ​

GitHub-style alerts use > [!TYPE]:

Custom containers ​

Blocks delimited by ::: with a type: note, tip, info, warning, danger or details. details takes an optional summary text and renders as a disclosure.

Containers render as <div class="TYPE custom-block">. Raw HTML (HyperText Markup Language) passes through, so the div can be written directly, for example to add an inline style:

<div class="tip custom-block">

Quick setup: [Getting Started](/guide/getting-started).

</div>

Renders as:

A blank line is required after the opening <div> and before the closing </div>; otherwise the content is treated as raw HTML (HyperText Markup Language) and Markdown inside is not rendered.

Cards ​

::: cards renders a Markdown list as a grid of bordered cards. Each list item is one card.

The optional argument sets the column count: ::: cards 3. Accepted values: 1 to 6. Other values are ignored.

• If no argument is set: the content width sets the column count. Minimum card width: 260px.
• If the viewport is narrower than 640px: the grid has one column.

::: cards 2
- [🙋 How to ask for help](/guide/getting-started)
  Read this guide to learn how to ask for help.
- [🧩 Configuration](/guide/configuration)
  Every `config.json` option.
- **📖 No link**
  A card without a target.
:::

Renders as:

Badges ​

Inline labels written as HTML (HyperText Markup Language); <badge> is styled by the Bark stylesheet. See Badge.

Hello world <Badge type="tip">3.0+</Badge>

Renders as:

Hello world 3.0+

Types match the alert colors: info (blue), tip (green, default), warning (amber), danger (red).

info tip warning danger

Definition lists ​

Terms followed by lines starting with : and a space produce a definition list.

Term 1

Definition of term 1.

Term 2

Definition of term 2.

Another definition of term 2.

Math ​

Inline: $E = mc^2$

Block:

Abbreviations ​

Abbreviation definitions at the end of a document wrap matching terms in <abbr>:

The spec is written by the WHATWG and served here over HTTP.

*[WHATWG]: Web Hypertext Application Technology Working Group
*[HTTP]: HyperText Transfer Protocol

Renders as:

The spec is written by the WHATWG (Web Hypertext Application Technology Working Group) and served here over HTTP (HyperText Transfer Protocol).

A definition applies to every occurrence on the page. Terms render with a dotted underline; the expansion appears on hover, and on tap on touch devices.

Citations ​

Text wrapped in doubled quotes ("") renders as a <cite> element:

The Art of Computer Programming

Standard Markdown ​

Tables, task lists and footnotes are supported:

• Done
• Not done yet

A sentence with a footnote.²

Link attributes ​

{target="_blank" rel="noopener"} after a link sets its attributes:

[Bark on GitHub](https://github.com/org/bark){target="_blank" rel="noopener"}

Video and media ​

Image syntax pointing at a video, audio or embed URL renders a native player. Media files are stored in docs/assets/:

![Demo clip](/assets/video.mp4)