VuePress Markdown 语法示例

# Heading (h2)

# h3

# h4

# h5

# h6

# Heading link

# 链接

# 内部链接

网站内部的链接，将会被转换成 <router-link> 用于 SPA 导航。同时，站内的每一个文件夹下的 README.md 或者 index.md 文件都会被自动编译为 index.html，对应的链接将被视为 /。

以如下的文件结构为例：

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

1
2
3
4
5
6
7
8
9
10

假设你现在在 foo/one.md 中：

[Home](/) <!-- 跳转到根部的 README.md -->
[foo](/foo/) <!-- 跳转到 foo 文件夹的 index.html -->
[foo heading](./#heading) <!-- 跳转到 foo/index.html 的特定标题位置 -->
[bar - three](../bar/three.md) <!-- 具体文件可以使用 .md 结尾（推荐） -->
[bar - four](../bar/four.html) <!-- 也可以用 .html -->

1
2
3
4
5

# 链接的重定向

VuePress 支持重定向到干净链接。如果一个链接 /foo 找不到，VuePress 会自行寻找一个可用的 /foo/ 或 /foo.html。反过来，当 /foo/ 或 /foo.html 中的一个找不到时，VuePress 也会尝试寻找另一个。

注意

无论是否使用了 permalink 和 clean-urls 插件，你的相对路径都应该依赖于当前的文件结构来定义。在上面的例子中，即使你将 /foo/one.md 的路径设为了 /foo/one/，你依然应该通过 ./two.md 来访问 /foo/two.md。

# 外部链接

外部的链接将会被自动地设置为 target="_blank" rel="noopener noreferrer":

你可以自定义通过配置 config.markdown.externalLinks (opens new window) 来自定义外部链接的特性。

# Front Matter

Maker 提供了对 YAML front matter (opens new window) 开箱即用的支持:

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

1
2
3
4

这些数据可以在当前 markdown 的正文，或者是任意的自定义或主题组件中使用。

想了解更多，请移步官方文档 Front Matter (opens new window)。

# Task List

# Image (click to zoom in/out)

<!-- new line -->
![space](https://vuepress.vuejs.org/architecture.png)
<!-- new line -->

1
2
3

# Inline image

Not Bad.

# hr

Below is a <hr>, I guess.

Above is a <hr>, I guess.

# List

# Unordered list

list item
list item
- list item
- list item
  - list item
  - list item

# Ordered list

list item
list item
list item

# GitHub 风格的表格

输入

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

1
2
3
4
5

输出

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

# Long Table

Sun With Face	Grinning Face	Smiling Face	Grinning Face With Big Eyes	Smiling Face With Smiling Eyes	Full Moon Face	Grinning Face With Smiling Eyes	Face With Monocle	Cowboy Hat Face	Thinking Face	Face Vomiting
🌞	😀	☺️	😃	😊	🌝	😄	🧐	🤠	🤔	🤮
🌞	😀	☺️	😃	😊	🌝	😄	🧐	🤠	🤔	🤮
🌞	😀	☺️	😃	😊	🌝	😄	🧐	🤠	🤔	🤮

# Blockquote

要么是酒，要么是女人，要么是神，家族，王，梦想，子女，力量，人如果不沉醉于某些东西估计都撑不下去吧，所有人都是某些东西的奴隶，就连那家伙...

-- 凯尼?阿克曼《进击的巨人》

# Code Block

// 第 3 版规范的最终设计
try {
  doSomething();
} catch (e) {
  if (e == "thing")
    console.log("a thing")
  else if (e == 42)
    console.log("42")
  else {
    console.log(e);
    throw e; // 重新 throw
  }
} finally {
  cleanup();
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# Emoji

输入

:tada: :100:

输出

🎉 💯

你可以在这个列表 (opens new window)找到所有可用的 Emoji。

# 自定义容器默认主题

输入

::: tip
这是一个提示
:::

::: warning
这是一个警告
:::

::: danger
这是一个危险警告
:::

::: details
这是一个详情块，在 IE / Edge 中不生效
:::

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

输出

TIP

这是一个提示

WARNING

这是一个警告

WARNING

这是一个危险警告

DETAILS

这是一个详情块，在 IE / Edge 中不生效

你也可以自定义块中的标题：

::: danger STOP
危险区域，禁止通行
:::

::: details 点击查看代码
```js
console.log('你好，VuePress！')
```
:::

1
2
3
4
5
6
7
8
9

STOP

危险区域，禁止通行

点击查看代码

console.log('你好，VuePress！')

参考:

vuepress-plugin-container (opens new window)

# 代码块中的语法高亮

VuePress 使用了 Prism (opens new window) 来为 markdown 中的代码块实现语法高亮。Prism 支持大量的编程语言，你需要做的只是在代码块的开始倒勾中附加一个有效的语言别名：

输入

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

1
2
3
4
5
6

输出

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

1
2
3
4

输入

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

1
2
3
4
5
6
7
8
9
10

输出

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

1
2
3
4
5
6
7
8

在 Prism 的网站上查看合法的语言列表 (opens new window)。

# 代码块中的行高亮

输入

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

1
2
3
4
5
6
7
8
9

输出

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

1
2
3
4
5
6
7

除了单行以外，你也可指定多行，行数区间，或是两者都指定。

行数区间: 例如 {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: 'VuePress is awesome',
      lorem: 'ipsum',
    }
  }
}
```

1
2
3
4
5
6
7
8
9
10
11
12
13

Output

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

1
2
3
4
5
6
7
8
9
10
11

# 行号

你可以通过配置来为每个代码块显示行号：

// .vuepress/config.js -> markdown

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

1
2
3
4
5
6
7

# 导入代码段 beta

你可以通过下述的语法导入已经存在的文件中的代码段：

<<< @/filepath

它也支持行高亮：

<<< @/filepath{highlightLines}

输入

<<< @/blog/.vuepress/__tests__/snippet.js{2}

输出

export default function () {
  // ..
}

1
2

注意

由于代码段的导入将在 webpack 编译之前执行，因此你无法使用 webpack 中的路径别名，此处的 @ 默认值是 process.cwd()。

为了只导入对应部分的代码，你也可运用 VS Code region (opens new window)。你可以在文件路径后方的 # 紧接着提供一个自定义的区域名称（预设为 snippet ）

输入

<<< @/blog/.vuepress/__tests__/snippet-with-region.js#snippet{1}

代码文件

// #region snippet
function foo () {
  return ({
    dest: '../../vuepress',
    locales: {
      '/': {
        lang: 'en-US',
        title: 'VuePress',
        description: 'Vue-powered Static Site Generator'
      },
      '/zh/': {
        lang: 'zh-CN',
        title: 'VuePress',
        description: 'Vue 驱动的静态网站生成器'
      }
    },
    head: [
      ['link', { rel: 'icon', href: `/logo.png` }],
      ['link', { rel: 'manifest', href: '/manifest.json' }],
      ['meta', { name: 'theme-color', content: '#3eaf7c' }],
      ['meta', { name: 'apple-mobile-web-app-capable', content: 'yes' }],
      ['meta', { name: 'apple-mobile-web-app-status-bar-style', content: 'black' }],
      ['link', { rel: 'apple-touch-icon', href: `/icons/apple-touch-icon-152x152.png` }],
      ['link', { rel: 'mask-icon', href: '/icons/safari-pinned-tab.svg', color: '#3eaf7c' }],
      ['meta', { name: 'msapplication-TileImage', content: '/icons/msapplication-icon-144x144.png' }],
      ['meta', { name: 'msapplication-TileColor', content: '#000000' }]
    ]
  })
}
// #endregion snippet

export default foo

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

输出

function foo () {
  return ({
    dest: '../../vuepress',
    locales: {
      '/': {
        lang: 'en-US',
        title: 'VuePress',
        description: 'Vue-powered Static Site Generator'
      },
      '/zh/': {
        lang: 'zh-CN',
        title: 'VuePress',
        description: 'Vue 驱动的静态网站生成器'
      }
    },
    head: [
      ['link', { rel: 'icon', href: `/logo.png` }],
      ['link', { rel: 'manifest', href: '/manifest.json' }],
      ['meta', { name: 'theme-color', content: '#3eaf7c' }],
      ['meta', { name: 'apple-mobile-web-app-capable', content: 'yes' }],
      ['meta', { name: 'apple-mobile-web-app-status-bar-style', content: 'black' }],
      ['link', { rel: 'apple-touch-icon', href: `/icons/apple-touch-icon-152x152.png` }],
      ['link', { rel: 'mask-icon', href: '/icons/safari-pinned-tab.svg', color: '#3eaf7c' }],
      ['meta', { name: 'msapplication-TileImage', content: '/icons/msapplication-icon-144x144.png' }],
      ['meta', { name: 'msapplication-TileColor', content: '#000000' }]
    ]
  })
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# 进阶配置

VuePress 使用 markdown-it (opens new window) 来渲染 Markdown，上述大多数的拓展也都是通过自定义的插件实现的。想要进一步的话，你可以通过 .vuepress/config.js 的 markdown 选项，来对当前的 markdown-it 实例做一些自定义的配置：

module.exports = {
  markdown: {
    // markdown-it-anchor 的选项
    anchor: { permalink: false },
    // markdown-it-toc 的选项
    toc: { includeLevel: [1, 2] },
    extendMarkdown: md => {
      // 使用更多的 markdown-it 插件!
      md.use(require('markdown-it-xxx'))
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12

# mark

Marked text

# Footnotes

Footnote 1 link^[1].

Footnote 2 link^[2].

Inline footnote^[3] definition.

Duplicated footnote reference^[2:1].

# Abbreviations

This is HTML abbreviation example.

It converts "HTML", but keep intact partial entries like "xxxHTMLyyy" and so on.

Footnote can have markup

and multiple paragraphs. ↩︎
Footnote text. ↩︎ ↩︎
Text of inline footnote ↩︎