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.
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.
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 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
```
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
```
:::
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.
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>
:::
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.
