Builtin Markdown features

About 6 minCookbookVuePressMarkdownVuePress

Here are some enhance VuePress makes on Markdown syntax.

Syntax Extensions

The Markdown content in VuePress will be parsed by markdown-itopen in new window, which supports syntax extensionsopen in new window via markdown-it plugins.

This section will introduce built-in Markdown syntax extensions of VuePress.

You can also configure those built-in extensions, load more markdown-it plugins and implement your own extensions via markdownopen in new window option and extendsMarkdownopen in new window option.

Embedded

Embedded by markdown-it:

Header Anchors

You might have noticed that, a # anchor is displayed when you hover the mouse on the headers of each section. By clicking the # anchor, you can jump to the section directly.

Tips

This header anchors extension is supported by markdown-it-anchoropen in new window.

Config reference: markdown.anchoropen in new window

When using Markdown link syntaxopen in new window, VuePress will implement some conversions for you.

Take our documentation source files as an example:

└─ src
   ├─ cookbook
   │  └─ vuepress
   │     ├─ markdown.md <- Here we are
   │     └─ README.md
   ├─ guide
   │  └─ README.md
   ├─ contribution.md
   └─ README.md

Raw Markdown:

<!-- relative path -->

[Home](../../README.md)  
[Contribution Guide](../../contribution.md)  
[VuePress Config](./config.md)

<!-- absolute path -->

[Guide](/guide/README.md)  
[Config > I18n](/config/i18n.md)

<!-- URL -->

[GitHub](https://github.com)

Converted to:

<template>
  <RouterLink to="/v2/">Home</RouterLink>
  <RouterLink to="/v2/contribution.html">Contribution Guide</RouterLink>
  <RouterLink to="/v2/cookbook/vuepress/config.html"
    >VuePress Config</RouterLink
  >
  <RouterLink to="/v2/guide/">Guide</RouterLink>
  <RouterLink to="/v2/config/i18n.html">Config &gt; I18n</RouterLink>
  <a href="https://github.com" target="_blank" rel="noopener noreferrer"
    >GitHub</a
  >
</template>

Rendered as:

Explanation:

  • Internal links will be converted to <RouterLink> for SPA navigation.
  • Internal links to .md files will be converted to the page route path, and both absolute path and relative path are supported.
  • External links will get target="_blank" rel="noopener noreferrer" attrs.

Suggestion:

Try to use relative paths instead of absolute paths for internal links.

  • Relative paths are a valid links to the target files, and they can navigate correctly when browsing the source files in your editor or repository.
  • Relative paths are consistent in different locales, so you don’t need to change the locale path when translating your content.
  • When using absolute paths, if the baseopen in new window of your site is not "/", you will need to prepend the base manually or use base helperopen in new window.

Tips

This links extension is supported by our built-in plugin.

Config reference: markdown.linksopen in new window

Emoji

You can add emoji to your Markdown content by typing :EMOJICODE:.

For a full list of available emoji and codes, check out emoji-cheat-sheetopen in new window.

Input:

VuePress 2 is out :tada: !

Output:

VuePress 2 is out 🎉 !

Tips

This emoji extension is supported by markdown-it-emojiopen in new window.

Config reference: markdown.emojiopen in new window

Table of Contents

To put the table of contents (TOC) of your current page inside your Markdown content, you can use the [[toc]] syntax.

Input:

[[toc]]

Output:

The headers in TOC will link to the corresponding header anchors, so TOC won’t work well if you disable header anchors.

Tips

This toc extension is supported by our built-in plugin, which is forked and modified from markdown-it-toc-done-rightopen in new window.

Config reference: markdown.tocopen in new window

Code Blocks

Following code blocks extensions are implemented during Markdown parsing in Node side. That means, the code blocks won’t be processed in client-side.

Line Highlighting

You can highlight specified lines of your code blocks by adding line ranges mark in your fenced code blocks:

Input:

```ts {1,6-8}
import type { UserConfig } from "@vuepress/cli";
import { defaultTheme } from "@vuepress/theme-default";

export const config: UserConfig = {
  title: "Hello, VuePress",

  theme: defaultTheme({
    logo: "https://vuejs.org/images/logo.png",
  }),
};
```

```

```

Output:

import type { UserConfig } from "@vuepress/cli";
import { defaultTheme } from "@vuepress/theme-default";

export const config: UserConfig = {
  title: "Hello, VuePress",

  theme: defaultTheme({
    logo: "https://vuejs.org/images/logo.png",
  }),
};
 




 
 
 


Examples for line ranges mark:

  • Line ranges: {5-8}
  • Multiple single lines: {4,7,9}
  • Combined: {4,7-13,16,23-27,40}

Tips

This line highlighting extension is supported by our built-in plugin, which is forked and modified from markdown-it-highlight-linesopen in new window.

Config reference: markdown.code.highlightLinesopen in new window

Line Numbers

You must have noticed that the number of lines is displayed on the left side of code blocks. This is enabled by default and you can disable it in config.

You can add :line-numbers / :no-line-numbers mark in your fenced code blocks to override the value set in config.

Input:

```ts
// line-numbers is enabled by default
const line2 = "This is line 2";
const line3 = "This is line 3";
```

```ts:no-line-numbers
// line-numbers is disabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

Output:

// line-numbers is enabled by default
const line2 = "This is line 2";
const line3 = "This is line 3";
// line-numbers is disabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'

Tips

This line numbers extension is supported by our built-in plugin.

Config reference: markdown.code.lineNumbersopen in new window

Wrap with v-pre

As template syntax is allowed in Markdown, it would also work in code blocks, too.

To avoid your code blocks being compiled by Vue, VuePress will add v-preopen in new window directive to your code blocks by default, which can be disabled in config.

You can add :v-pre / :no-v-pre mark in your fenced code blocks to override the value set in config.

Note

The template syntax characters, for example, the "Mustache" syntax (double curly braces) might be parsed by the syntax highlighter. Thus, as the following example, :no-v-pre might not work well in some languages.

To make Vue syntax work in those languages anyway, try to disable the default syntax highlighting and implement your own syntax highlighting in client-side.

Input:

```md
<!-- This will be kept as is by default -->

1 + 2 + 3 = {{ 1 + 2 + 3 }}
```

```md:no-v-pre
<!-- This will be compiled by Vue -->
1 + 2 + 3 = {{ 1 + 2 + 3 }}
```

```js:no-v-pre
// This won’t be compiled correctly because of js syntax highlighting
const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}
```

Output:

<!-- This will be kept as is -->

1 + 2 + 3 = {{ 1 + 2 + 3 }}
<!-- This will be compiled by Vue -->
1 + 2 + 3 = 6
// This won’t be compiled correctly because of js syntax highlighting
const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}

Tips

This v-pre extension is supported by our built-in plugin.

Config reference: markdown.code.vPreopen in new window

Import Code Blocks

You can import code blocks from files with following syntax:

<!-- minimal syntax -->

@[code](../foo.js)

To partially import the file:

<!-- partial import, from line 1 to line 10 -->

@[code{1-10}](../foo.js)

The code language is inferred from the file extension, while it is recommended to specify it explicitly:

<!-- specify the code language -->

@[code js](../foo.js)

In fact, the second part inside the [] will be treated as the mark of the code fence, so it supports all the syntax mentioned in the above Code Blocks section:

<!-- line highlighting -->

@[code js{2,4-5}](../foo.js)

Here is a complex example:

  • import line 3 to line 10 of the "../foo.js" file
  • specify the language as "js"
  • highlight line 3 of the imported code, i.e. line 5 of the "../foo.js" file
  • disable line numbers
@[code{3-10} js{3}:no-line-numbers](../foo.js)

Notice that path aliases are not available in import code syntax. You can use following config to handle path alias yourself:

import { getDirname, path } from "@vuepress/utils";

const __dirname = getDirname(import.meta.url);

export default {
  markdown: {
    importCode: {
      handleImportPath: (str) =>
        str.replace(/^@src/, path.resolve(__dirname, "path/to/src")),
    },
  },
};
<!-- it will be resolved to 'path/to/src/foo.js' -->

@[code](@src/foo.js)

Tips

This import code extension is supported by our built-in plugin.

Config reference: markdown.importCodeopen in new window

Using Vue in Markdown

This section will introduce some basic usage of Vue in Markdown.

Check out Cookbook > Markdown and Vue SFCopen in new window for more details.

Template Syntax

As we know:

  • HTML is allowed in Markdown.
  • Vue template syntax is compatible with HTML.

That means, Vue template syntaxopen in new window is allowed in Markdown.

Input:

One plus one equals: {{ 1 + 1 }}

<span v-for="i in 3"> span: {{ i }} </span>

Output:

One plus one equals: 2

span: 1 span: 2 span: 3

Components

You can use Vue components directly in Markdown.

Input:

This is default theme built-in `<Badge />` component <Badge text="demo" />

Output:

This is default theme built-in <Badge /> component demo

Tips

Check out the Built-in Componentsopen in new window for a full list of built-in components.

Cautions

Deprecated HTML Tags

Deprecated HTML tags such as <center>open in new window and <font>open in new window are not allowed in VuePress Markdown by default.

Those tags would not be recognized as native HTML tags by Vue template compiler. Instead, Vue will try to resolve those tags as Vue components, and obviously these components usually don’t exist.

You should try to avoid using deprecated HTML tags. However, to use those tags anyway, try either of the following workarounds: