/vitepress

Markdown Extensions

VitePress extends standard markdown with additional features for documentation.

Frontmatter

YAML metadata at the top of markdown files:

---
title: Page Title
description: Page description for SEO
layout: doc
outline: [2, 3]
---

# Content starts here

Access frontmatter in templates:

# {{ $frontmatter.title }}

Or in script:

<script setup>
import { useData } from 'vitepress'
const { frontmatter } = useData()
</script>

Custom Containers

Styled callout blocks:

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

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

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

::: danger
This is a dangerous warning.
:::

::: details Click to expand
Hidden content here.
:::

Custom titles:

::: danger STOP
Do not proceed!
:::

::: details Click me {open}
Open by default with {open} attribute.
:::

The no-title attribute renders a container without a title element (no effect on details):

::: tip {no-title}
Just want to try it out? Skip to the Quickstart.
:::

Registering New Containers (v2)

Map new container names to their default titles in config; they behave like the built-in ones (custom titles, attributes, GitHub-alert syntax):

// config.ts
export default {
  markdown: {
    container: {
      customContainers: { success: 'SUCCESS' }
    }
  }
}

New containers ship unstyled — add CSS using the container name as the class:

.custom-block.success {
  border-color: transparent;
  color: var(--vp-c-text-1);
  background-color: var(--vp-c-success-soft);
}

Nesting Containers

::: markers follow the same rule as code fences: a fence is closed only by a matching fence at least as long. Make the outer fence longer to nest:

:::: info Outer container
This box contains another container.

::: details Inner container
Nested content
:::
::::

GitHub-flavored Alerts

Alternative syntax using blockquotes:

> [!NOTE]
> Highlights information users should know.

> [!TIP]
> Optional information for success.

> [!WARNING]
> Critical content requiring attention.

> [!CAUTION]
> Negative potential consequences.

Text after the marker becomes the alert title: > [!NOTE] Custom Title. Containers you registered yourself work here too. [!DANGER] is a VitePress extension (renders as a plain blockquote on GitHub). By default alert colors match GitHub's (caution and danger both red); enable themeConfig.gradedContainers for a graded scale (danger red, warning orange, caution yellow).

Header Anchors

Headers get automatic anchor links. Custom anchors:

# My Heading {#custom-anchor}

[Link to heading](#custom-anchor)

Table of Contents

Generate a TOC with:

[[toc]]

GitHub-Style Tables

| Feature | Status |
|---------|--------|
| SSR     | ✅     |
| HMR     | ✅     |

Task Lists

- [ ] Write the press release
- [x] Update the website

Footnotes

Footnotes are supported[^1], including inline ones^[This is an inline footnote.].

[^1]: Definitions can contain **markdown** and render at the end of the page.

Emoji

Use shortcodes:

:tada: :rocket: :100:

File Includes

Include content from other files:

<!--@include: ./shared/header.md-->

With line ranges:

<!--@include: ./code.md{3,10}-->  <!-- Lines 3-10 -->
<!--@include: ./code.md{3,}-->   <!-- From line 3 -->
<!--@include: ./code.md{,10}-->  <!-- Up to line 10 -->

With regions:

<!-- In parts/basics.md -->
<!-- #region usage -->
Usage content here
<!-- #endregion usage -->

<!-- Include just that region -->
<!--@include: ./parts/basics.md#usage-->

Header anchors work too: <!--@include: ./parts/basics.md#my-heading-->. Including a missing file/region/anchor or out-of-range lines throws a build error; set markdown.include.silent: true to warn and skip. Relative links/images in an included file resolve from the included file's location (disable via markdown.include.rebaseRelativeUrls: false). To show the directive literally in docs (e.g. inside a fence), escape it as @@include.

Code Snippet Import

Import code from files:

<<< @/snippets/example.js

With line highlighting:

<<< @/snippets/example.js{2,4-6}

With language override:

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

Import specific region:

<<< @/snippets/example.js#regionName{1,2}

Multiple regions with the same name are concatenated (across comment styles too). Importing a missing file/region throws a build error — set markdown.snippet.silent: true to render nothing instead. Extra tokens after the language are passed as attributes, e.g. {ts twoslash} enables twoslash.

Code Groups

Tab groups for code variants:

::: code-group

```js [config.js]
export default { /* ... */ }
```

```ts [config.ts]
export default defineConfig({ /* ... */ })
```

:::

Import files in code groups:

::: code-group

<<< @/snippets/config.js
<<< @/snippets/config.ts

:::

Math Equations

Requires setup:

npm add -D markdown-it-mathjax3@^4

// .vitepress/config.ts
export default {
  markdown: {
    math: true
  }
}

Then use LaTeX:

Inline: $E = mc^2$

Block:
$$
\frac{-b \pm \sqrt{b^2-4ac}}{2a}
$$

Image Lazy Loading

export default {
  markdown: {
    image: {
      lazyLoad: true // Renamed from `lazyLoading` in v2
    }
  }
}

Raw Container

Prevent VitePress style conflicts:

::: raw
<CustomComponent />
:::

Key Points

• Frontmatter supports YAML or JSON format
• Custom containers support info, tip, warning, danger, details; register more via markdown.container.customContainers (v2)
• Task lists and footnotes are supported
• [[toc]] generates table of contents
• @ in imports refers to source root (or srcDir if configured)
• Code groups create tabbed code blocks
• Math support requires markdown-it-mathjax3 package
• v2: image.lazyLoading renamed to image.lazyLoad; anchor uses @mdit/plugin-anchor, attrs uses @mdit/plugin-attrs
• Include/snippet failures throw build errors by default (markdown.include.silent / markdown.snippet.silent to soften)