关于markdown

VitePress comes with built in Markdown Extensions.

Header Anchors

Headers automatically get anchor links applied. Rendering of anchors can be configured using the markdown.anchor option.

Links

Both internal and external links gets special treatments.

Internal Links

Internal links are converted to router link for SPA navigation. Also, every index.md contained in each sub-directory will automatically be converted to index.html, with corresponding URL /.

For example, given the following directory structure:

.
├─ index.md
├─ foo
│  ├─ index.md
│  ├─ one.md
│  └─ two.md
└─ bar
   ├─ index.md
   ├─ three.md
   └─ four.md

.
├─ index.md
├─ foo
│  ├─ index.md
│  ├─ one.md
│  └─ two.md
└─ bar
   ├─ index.md
   ├─ three.md
   └─ four.md

And providing you are in foo/one.md:

[Home](/) <!-- sends the user to the root index.md -->
[foo](/foo/) <!-- sends the user to index.html of directory foo -->
[foo heading](./#heading) <!-- anchors user to a heading in the foo index file -->
[bar - three](../bar/three) <!-- you can omit extention -->
[bar - three](../bar/three.md) <!-- you can append .md -->
[bar - four](../bar/four.html) <!-- or you can append .html -->

[Home](/) <!-- sends the user to the root index.md -->
[foo](/foo/) <!-- sends the user to index.html of directory foo -->
[foo heading](./#heading) <!-- anchors user to a heading in the foo index file -->
[bar - three](../bar/three) <!-- you can omit extention -->
[bar - three](../bar/three.md) <!-- you can append .md -->
[bar - four](../bar/four.html) <!-- or you can append .html -->

Page Suffix

Pages and internal links get generated with the .html suffix by default.

External Links

Outbound links automatically get target="_blank" rel="noreferrer":

Frontmatter

YAML frontmatter is supported out of the box:

yaml

---
title: Blogging Like a Hacker
lang: en-US
---

---
title: Blogging Like a Hacker
lang: en-US
---

This data will be available to the rest of the page, along with all custom and theming components.

GitHub-Style Tables

Input

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

Output

Tables	Are	Cool
col 3 is	right-aligned	$1600
col 2 is	centered	$12
zebra stripes	are neat	$1

Emoji :tada

Input

:tada: :100:

:tada: :100:

Output

🎉 💯

A list of all emojis is available.

Input

[[toc]]

[[toc]]

Output

Rendering of the TOC can be configured using the markdown.toc option.

Custom Containers

Custom containers can be defined by their types, titles, and contents.

Default Title

Input

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

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

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

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

::: details
This is a details block.
:::

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

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

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

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

::: details
This is a details block.
:::

Output

INFO

This is an info box.

TIP

This is a tip.

WARNING

This is a dangerous warning.

DANGER

This is a dangerous warning.

Details

This is a details block.

Custom Title

You may set custom title by appending the text right after the "type" of the container.

Input

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

::: details Click me to view the code
```js
console.log('Hello, VitePress!')
```
:::

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

::: details Click me to view the code
```js
console.log('Hello, VitePress!')
```
:::

Output

STOP

Danger zone, do not proceed

Click me to view the code

console.log('Hello, VitePress!')

console.log('Hello, VitePress!')

Syntax Highlighting in Code Blocks

VitePress uses Shiki to highlight language syntax in Markdown code blocks, using coloured text. Shiki supports a wide variety of programming languages. All you need to do is append a valid language alias to the beginning backticks for the code block:

Input

```js
export default {
  name: 'MyComponent',
  // ...
}
```

```js
export default {
  name: 'MyComponent',
  // ...
}
```

```html
<ul>
  <li v-for="todo in todos" :key="todo.id">
    {{ todo.text }}
  </li>
</ul>
```

```html
<ul>
  <li v-for="todo in todos" :key="todo.id">
    {{ todo.text }}
  </li>
</ul>
```

Output

export default {
  name: 'MyComponent'
  // ...
}

export default {
  name: 'MyComponent'
  // ...
}

html

<ul>
  <li v-for="todo in todos" :key="todo.id">
    {{ todo.text }}
  </li>
</ul>

<ul>
  <li v-for="todo in todos" :key="todo.id">
    {{ todo.text }}
  </li>
</ul>

A list of valid languages is available on Shiki’s repository.

Line Highlighting in Code Blocks

Input

```js{4}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

```js{4}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

Output

export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}

export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}

In addition to a single line, you can also specify multiple single lines, ranges, or both:

Line ranges: for example {5-8}, {3-10}, {10-17}
Multiple single lines: for example {4,7,9}
Line ranges and single lines: for example {4,7-13,16,23-27,40}

Input

```js{1,4,6-8}
export default { // Highlighted
  data () {
    return {
      msg: `Highlighted!
      This line isn't highlighted,
      but this and the next 2 are.`,
      motd: 'VitePress is awesome',
      lorem: 'ipsum'
    }
  }
}
```

```js{1,4,6-8}
export default { // Highlighted
  data () {
    return {
      msg: `Highlighted!
      This line isn't highlighted,
      but this and the next 2 are.`,
      motd: 'VitePress is awesome',
      lorem: 'ipsum'
    }
  }
}
```

Output

export default { // Highlighted
  data () {
    return {
      msg: `Highlighted!
      This line isn't highlighted,
      but this and the next 2 are.`,
      motd: 'VitePress is awesome',
      lorem: 'ipsum',
    }
  }
}

export default { // Highlighted
  data () {
    return {
      msg: `Highlighted!
      This line isn't highlighted,
      but this and the next 2 are.`,
      motd: 'VitePress is awesome',
      lorem: 'ipsum',
    }
  }
}

Line Numbers

You can enable line numbers for each code blocks via config:

export default {
  markdown: {
    lineNumbers: true
  }
}

export default {
  markdown: {
    lineNumbers: true
  }
}

Import Code Snippets

You can import code snippets from existing files via following syntax:

<<< @/filepath

<<< @/filepath

It also supports line highlighting:

<<< @/filepath{highlightLines}

<<< @/filepath{highlightLines}

Input

<<< @/snippets/snip.ts{2}

<<< @/snippets/snip.ts{2}

Code file

import { defineConfig } from "vitepress";
import { navbar } from "./nav";
import { sidebar } from "./sidebar";
export default defineConfig({
    base: "/vitepress-starter/",

    // site-level locales config
    outDir: "../dist",
    head: [
        // ['link', { rel: 'shortcut icon', type: 'image/png', href: '/hero.png' }],
        // ['link', { rel: 'shortcut icon', type: 'image/png', href: '/hero.png' }],
        ["link", { rel: "icon", type: "image/svg+xml", href: "/vue.svg" }],
    ],
    lang: "zh-CN",
    title: "VitePress",
    description: "Vue 驱动的静态网站生成器",
    vue: {
        reactivityTransform: true,
    },
    themeConfig: {
        logo: "/vue.svg",

        // theme-level locales config

        // navbar
        nav: navbar,

        sidebar: sidebar,
        socialLinks: [{ icon: "github", link: "https://github.com/yzqtpl/vitepress-starter" }],
        editLink: {
            pattern: "https://github.com/yzqtpl/vitepress-starter/edit/main/docs/:path",
            text: "Edit this page on GitHub",
        },
        footer: {
            message: "Released under the MIT License.",
            copyright: "Copyright © 2019-present yzqdev",
        },
    },
});

import { defineConfig } from "vitepress";
import { navbar } from "./nav";
import { sidebar } from "./sidebar";
export default defineConfig({
    base: "/vitepress-starter/",

    // site-level locales config
    outDir: "../dist",
    head: [
        // ['link', { rel: 'shortcut icon', type: 'image/png', href: '/hero.png' }],
        // ['link', { rel: 'shortcut icon', type: 'image/png', href: '/hero.png' }],
        ["link", { rel: "icon", type: "image/svg+xml", href: "/vue.svg" }],
    ],
    lang: "zh-CN",
    title: "VitePress",
    description: "Vue 驱动的静态网站生成器",
    vue: {
        reactivityTransform: true,
    },
    themeConfig: {
        logo: "/vue.svg",

        // theme-level locales config

        // navbar
        nav: navbar,

        sidebar: sidebar,
        socialLinks: [{ icon: "github", link: "https://github.com/yzqtpl/vitepress-starter" }],
        editLink: {
            pattern: "https://github.com/yzqtpl/vitepress-starter/edit/main/docs/:path",
            text: "Edit this page on GitHub",
        },
        footer: {
            message: "Released under the MIT License.",
            copyright: "Copyright © 2019-present yzqdev",
        },
    },
});

Output

import { defineConfig } from "vitepress";
import { navbar } from "./nav";
import { sidebar } from "./sidebar";
export default defineConfig({
    base: "/vitepress-starter/",

    // site-level locales config
    outDir: "../dist",
    head: [
        // ['link', { rel: 'shortcut icon', type: 'image/png', href: '/hero.png' }],
        // ['link', { rel: 'shortcut icon', type: 'image/png', href: '/hero.png' }],
        ["link", { rel: "icon", type: "image/svg+xml", href: "/vue.svg" }],
    ],
    lang: "zh-CN",
    title: "VitePress",
    description: "Vue 驱动的静态网站生成器",
    vue: {
        reactivityTransform: true,
    },
    themeConfig: {
        logo: "/vue.svg",

        // theme-level locales config

        // navbar
        nav: navbar,

        sidebar: sidebar,
        socialLinks: [{ icon: "github", link: "https://github.com/yzqtpl/vitepress-starter" }],
        editLink: {
            pattern: "https://github.com/yzqtpl/vitepress-starter/edit/main/docs/:path",
            text: "Edit this page on GitHub",
        },
        footer: {
            message: "Released under the MIT License.",
            copyright: "Copyright © 2019-present yzqdev",
        },
    },
});

import { defineConfig } from "vitepress";
import { navbar } from "./nav";
import { sidebar } from "./sidebar";
export default defineConfig({
    base: "/vitepress-starter/",

    // site-level locales config
    outDir: "../dist",
    head: [
        // ['link', { rel: 'shortcut icon', type: 'image/png', href: '/hero.png' }],
        // ['link', { rel: 'shortcut icon', type: 'image/png', href: '/hero.png' }],
        ["link", { rel: "icon", type: "image/svg+xml", href: "/vue.svg" }],
    ],
    lang: "zh-CN",
    title: "VitePress",
    description: "Vue 驱动的静态网站生成器",
    vue: {
        reactivityTransform: true,
    },
    themeConfig: {
        logo: "/vue.svg",

        // theme-level locales config

        // navbar
        nav: navbar,

        sidebar: sidebar,
        socialLinks: [{ icon: "github", link: "https://github.com/yzqtpl/vitepress-starter" }],
        editLink: {
            pattern: "https://github.com/yzqtpl/vitepress-starter/edit/main/docs/:path",
            text: "Edit this page on GitHub",
        },
        footer: {
            message: "Released under the MIT License.",
            copyright: "Copyright © 2019-present yzqdev",
        },
    },
});

TIP

The value of @ corresponds to the source root. By default it's the VitePress project root, unless srcDir is configured.

You can also use a VS Code region to only include the corresponding part of the code file. You can provide a custom region name after a # following the filepath:

Input

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

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

Code file

// #region snippet
function foo() {
    // ..
}
// #endregion snippet

export default foo;

// #region snippet
function foo() {
    // ..
}
// #endregion snippet

export default foo;

Output

function foo() {
    // ..
}

function foo() {
    // ..
}

You can also specify the language inside the braces ({}) like this:

<<< @/snippets/snippet.cs{c#}

<!-- with line highlighting: -->
<<< @/snippets/snippet.cs{1,2,4-6 c#}

<<< @/snippets/snippet.cs{c#}

<!-- with line highlighting: -->
<<< @/snippets/snippet.cs{1,2,4-6 c#}

This is helpful if source language cannot be inferred from your file extension.

Markdown File Inclusion

You can include a markdown file in another markdown file like this:

Input

# Docs

## Basics

<!--@include: ./parts/basics.md-->

# Docs

## Basics

<!--@include: ./parts/basics.md-->

Part file (parts/basics.md)

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

Equivalent code

# Docs

## Basics

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

# Docs

## Basics

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

WARNING

Note that this does not throw errors if your file is not present. Hence, when using this feature make sure that the contents are being rendered as expected.

Advanced Configuration

VitePress uses markdown-it as the Markdown renderer. A lot of the extensions above are implemented via custom plugins. You can further customize the markdown-it instance using the markdown option in .vitepress/config.js:

const anchor = require('markdown-it-anchor')

module.exports = {
  markdown: {
    // options for markdown-it-anchor
    // https://github.com/valeriangalliat/markdown-it-anchor#permalinks
    anchor: {
      permalink: anchor.permalink.headerLink()
    },

    // options for markdown-it-toc-done-right
    toc: { level: [1, 2] },

    config: (md) => {
      // use more markdown-it plugins!
      md.use(require('markdown-it-xxx'))
    }
  }
}

const anchor = require('markdown-it-anchor')

module.exports = {
  markdown: {
    // options for markdown-it-anchor
    // https://github.com/valeriangalliat/markdown-it-anchor#permalinks
    anchor: {
      permalink: anchor.permalink.headerLink()
    },

    // options for markdown-it-toc-done-right
    toc: { level: [1, 2] },

    config: (md) => {
      // use more markdown-it plugins!
      md.use(require('markdown-it-xxx'))
    }
  }
}

关于markdown ​

Header Anchors ​

Links ​

Internal Links ​

Page Suffix ​

External Links ​

Frontmatter ​

GitHub-Style Tables ​

Emoji :tada ​

Table of Contents ​

Custom Containers ​

Default Title ​

Custom Title ​

Syntax Highlighting in Code Blocks ​

Line Highlighting in Code Blocks ​

Line Numbers ​

Import Code Snippets ​

Markdown File Inclusion ​

Advanced Configuration ​

关于markdown

Header Anchors

Links

Internal Links

Page Suffix

External Links

Frontmatter

GitHub-Style Tables

Emoji :tada

Table of Contents

Custom Containers

Default Title

Custom Title

Syntax Highlighting in Code Blocks

Line Highlighting in Code Blocks

Line Numbers

Import Code Snippets

Markdown File Inclusion

Advanced Configuration