# Markdown Extensions

# Header Anchors

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

# Links

# 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

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

# Page Suffix

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

# External Links

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

• vuejs.org
• VitePress on GitHub

# Frontmatter

YAML frontmatter is supported out of the box:

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

For more details, see Frontmatter.

# GitHub-Style Tables

Input

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

Output

# Emoji 🎉

Input

:tada: :100:

Output

🎉 💯

A list of all emojis is available.

# Table of Contents

Input

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

::: tip
This is a tip
:::

::: warning
This is a warning
:::

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

Output

# Custom Title

Input

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

Output

# Syntax Highlighting in Code Blocks

VitePress uses Prism to highlight language syntax in Markdown code blocks, using coloured text. Prism 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',
  // ...
}
```

Output

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

Input

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

Output

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

A list of valid languages is available on Prism’s site.

# Line Highlighting in Code Blocks

Input

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

Output

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-7}
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',
    }
  }
}

# Line Numbers

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

module.exports = {
  markdown: {
    lineNumbers: true
  }
}

• Demo:

# Import Code Snippets

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

<<< @/filepath

It also supports line highlighting:

<<< @/filepath{highlightLines}

Input

<<< @/snippets/snippet.js{2}

Code file

export default function () {
  // ..
}

Output

export default function () {
  // ..
}

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 (snippet by default):

Input

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

Code file

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

export default foo

Output

function foo() {
  // ..
}

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

module.exports = {
  markdown: {
    // options for markdown-it-anchor
    anchor: { permalink: false },

    // options for markdown-it-toc
    toc: { includeLevel: [1, 2] },

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