Headers automatically get anchor links applied. Rendering of anchors can be configured using the markdown.anchor option.
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:
.
\u251C\u2500 index.md
\u251C\u2500 foo
\u2502 \u251C\u2500 index.md
\u2502 \u251C\u2500 one.md
\u2502 \u2514\u2500 two.md
\u2514\u2500 bar
\u251C\u2500 index.md
\u251C\u2500 three.md
\u2514\u2500 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 -->
Pages and internal links get generated with the .html suffix by default.
Outbound links automatically get target="_blank" rel="noopener noreferrer":
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.
Input
| 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 |
Input
:tada: :100:
Output
\u{1F389} \u{1F4AF}
A list of all emojis is available.
Input
[[toc]]
Output
Rendering of the TOC can be configured using the markdown.toc option.
Custom containers can be defined by their types, titles, and contents.
Input
::: tip
This is a tip
:::
::: info
This is an info box
:::
::: warning
This is a warning
:::
::: danger
This is a dangerous warning
:::
::: details
This is a details block, which does not work in Internet Explorer or old versions of Edge.
:::
Output
TIP
This is a tip
INFO
This is an info box
WARNING
This is a warning
WARNING
This is a dangerous warning
This is a details block, which does not work in Internet Explorer or Edge.
Input
::: 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
console.log('Hello, VitePress!')
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\u2019s site.
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:
{5-8}, {3-10}, {10-17}{4,7,9}{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',
}
}
}
You can enable line numbers for each code blocks via config:
module.exports = {
markdown: {
lineNumbers: true
}
}
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 () {
// ..
}
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 (snippet by default):
Input
<<< @/snippets/snippet-with-region.js{1}
Code file
// #region snippet
function foo() {
// ..
}
// #endregion snippet
export default foo
Output
function foo() {
// ..
}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-table-of-contents
toc: { includeLevel: [1, 2] },
config: (md) => {
// use more markdown-it plugins!
md.use(require('markdown-it-xxx'))
}
}
}