Markdown Extensions

Standard Markdown is enough to write a page, but not enough to write good documentation. Callouts, side-by-side code samples, highlighted code, and snippets pulled straight from the source repository all have to live somewhere, and VitePress provides a coherent set of extensions for them. This page walks through those extensions with the syntax you would actually type.

Frontmatter and anchors

Every page can start with a YAML frontmatter block. The generator reads it and makes the values available to the theme and to your own components:

---
title: Installing the CLI
description: Install the CLI and verify that it runs.
lang: en-US
layout: doc
---

Headings get anchor links automatically, and you can override the generated anchor by appending an explicit one:

# Using custom anchors {#my-anchor}

which lets you link to #my-anchor instead of the auto-generated #using-custom-anchors. A table of contents can be placed anywhere in the page with the [[toc]] directive.

Callouts and containers

VitePress provides five built-in container types — info, tip, warning, danger, and details — and you can give any of them a custom title by putting text after the type:

::: info
This is an information box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger STOP
Danger zone, do not proceed.
:::

::: details Click me to toggle the code
Collapsed by default.
:::

The details container renders as a disclosure element and suits optional or long content. Extra attributes can be attached to any container, which is how you make a details block start expanded:

::: details Click me to toggle the code {open}
Rendered open by default.
:::

The labels used for the container titles can be changed globally, which matters if your documentation is not in English:

export default defineConfig({
  markdown: {
    container: {
      tipLabel: 'Tip',
      warningLabel: 'Warning',
      dangerLabel: 'Danger',
      infoLabel: 'Info',
      detailsLabel: 'Details'
    }
  }
})

GitHub-flavored alerts are supported as well, and are rendered in the same style as the containers above:

> [!NOTE]
> Useful information that users should take into account.

> [!CAUTION]
> Negative consequences of an action.

Code blocks and highlighting

Code fences are highlighted by Shiki, so any language with a TextMate grammar is available, and the light and dark themes are configured independently. A language identifier on the fence is all that is needed:

```ts
export function greet(name: string): string {
  return `Hello, ${name}!`
}
```

Individual lines can be highlighted in the fence itself. A single line, a range, a list of lines, or a mix of the two are all accepted:

```ts{2,5-7}
const config = {
  // this line is highlighted
  title: 'My Docs',
  description: 'A short summary.',
  author: 'Team'
}
```

The same effect can be produced from inside the code with a comment, which is useful when the highlighted line is hard to spot in a long fence:

```ts
const config = {
  title: 'My Docs' // [!code highlight]
}
```

The comment annotations cover more than highlighting. A line can be marked as a diff addition or removal, as an error, as a warning, or as the focus of the example:

```ts
const before = 1 // [!code --]
const after = 2 // [!code ++]

throw new Error('boom') // [!code error]
console.warn('careful') // [!code warning]

const focus = 'this line' // [!code focus]
```

Line numbers are off by default and can be turned on globally, per fence, or from a specific starting number:

export default defineConfig({
  markdown: {
    lineNumbers: true
  }
})
```ts:line-numbers
// numbered from 1
```

```ts:line-numbers=2
// numbered from 2
```

Code groups

When a reader has to choose between variants, tabs are better than a stack. The code-group container takes several fences and renders them as a tabbed panel, with the label in square brackets after the language:

::: code-group

```js [config.js]
export default {
  title: 'My Docs'
}
```

```ts [config.ts]
import type { UserConfig } from 'vitepress'

const config: UserConfig = {
  title: 'My Docs'
}

export default config
```

:::

Importing snippets from your source code

Documentation that shows code should show the code that exists. The snippet import syntax pulls a file — or a region of one — directly into the page, so an example can never drift from the implementation:

<<< @/snippets/snippet.js

The @ prefix means the source root, which is the project root unless srcDir is configured. A relative path works as well. Line highlighting is supported inside the braces, and a VS Code region can be selected with a hash after the path:

<<< @/snippets/snippet.js{2}
<<< @/snippets/snippet-with-region.js#snippet{1}

The referenced file is expected to mark the region with region comments:

// #region snippet
export function createClient(options) {
  return { options }
}
// #endregion snippet

The language can be stated explicitly when it cannot be inferred from the file extension, and line numbers can be requested in the same place:

<<< @/snippets/snippet.cs{c#}
<<< @/snippets/snippet.cs{1,2,4-6 c#:line-numbers}

Imported snippets can also be used inside a code group, in which case the file name becomes the tab title unless you provide one:

::: code-group

<<< @/snippets/snippet.js

<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]

:::

The same idea works for prose. A Markdown file can be included inside another one, optionally restricted to a line range or a region:

<!--@include: ./parts/basics.md-->
<!--@include: ./parts/basics.md{3,}-->
<!--@include: ./parts/basics.md#basic-usage{5,}-->

One caveat is worth knowing: an include of a missing file does not raise an error, so a typo silently produces an empty section. If you rely on includes, check the rendered output.

Mathematics, diagrams, and raw blocks

Mathematical notation is opt-in. Install the math plugin and turn the option on:

npm add -D markdown-it-mathjax3
export default defineConfig({
  markdown: {
    math: true
  }
})

With that enabled, inline and display math are written with the usual dollar-sign delimiters. Diagram support is enabled in the same way, with markdown.mermaid turned on and the mermaid package installed, and the diagram source is written in a fenced block tagged mermaid.

For component libraries, a special raw container wraps its contents in an element with the vp-raw class, which stops the documentation theme’s styles from bleeding into the markup you are demonstrating:

::: raw
<div class="my-component">Rendered without the theme's styles.</div>
:::

Configuring markdown-it

Every extension above is a markdown-it plugin, so the parser can be extended directly. The markdown.config option receives the parser instance:

import { defineConfig } from 'vitepress'
import markdownItFootnote from 'markdown-it-footnote'

export default defineConfig({
  markdown: {
    // options for the anchor plugin
    anchor: {
      permalink: false
    },

    // options for the table of contents plugin
    toc: { level: [2, 3] },

    // use any additional markdown-it plugin
    config: (md) => {
      md.use(markdownItFootnote)
    }
  }
})

Taken together, these extensions are what separate documentation that is merely correct from documentation that is pleasant to read. Each one removes a category of error a hand-written page would carry: a callout that is bold text instead of a callout, a sample that has drifted from the source, an anchor that points at a renamed heading. The next page publishes the finished site.

Found an issue with this content?

Tell us what could be improved.