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

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.

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     | ✅     |

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-->

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}

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: {
      lazyLoading: true,
    },
  },
};

Raw Container

Prevent VitePress style conflicts:

::: raw
<CustomComponent />
:::

Key Points

• Frontmatter supports YAML or JSON format
• Custom containers support info, tip, warning, danger, details
• [[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

Contributors

XiSenao

Changelog

Last edited 10 days ago

View full history

2f55cfe-feat(ai-instructions): add skill definitions package