Markdown 拓展

Header Anchors

所有的标题将会自动地应用 anchor 链接，anchor 的渲染可以通过 markdown.anchor 来配置。

链接

内部链接

内部的、并以 .md or .html 结尾的链接，将会被转换成 <router-link> 用于 SPA 导航。

站内的每一个子文件夹都应当有一个 README.md 文件，它会被自动编译为 index.html。

::: tip
在链接到一个文件夹的 index.html 时，确保你的链接以 / 结尾，否则该链接将导致 404。比如，用 /config/ 而不是 /config。
:::

如果你想要链接到另一个 markdown 文件：

  1. 确保链接以 .html 或 .md 结尾；
  2. 确保路径大小写正确，因为路径的匹配是大小写敏感的。

示例

以如下的文件结构为例：

  1. .
  2. ├─ README.md
  3. ├─ foo
  4. │  ├─ README.md
  5. │  ├─ one.md
  6. │  └─ two.md
  7. └─ bar
  8.    ├─ README.md
  9.    ├─ three.md
  10.    └─ four.md
  1. [Home](/) <!-- 跳转到根部的 README.md -->
  2. [foo](/foo/) <!-- 跳转到 foo 文件夹的 index.html -->
  3. [foo heading anchor](/foo/#heading) <!-- 跳转到 foo/index.html 的特定 anchor 位置 -->
  4. [foo - one](/foo/one.html) <!-- 具体文件可以使用 .html 结尾 -->
  5. [foo - two](/foo/two.md) <!-- 也可以用 .md -->

外部链接

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

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

Front Matter

VuePress 提供了对 YAML front matter 开箱即用的支持:

  1. ---
  2. title: Blogging Like a Hacker
  3. lang: en-US
  4. ---

这些数据可以在当前页的正文中使用，在任意的自定义或主题组件中，它可以通过 $page 来访问。

title 和 lang 的 meta 将会被自动地注入到当前的页面中，当然你也可以指定一些额外需要注入的 meta：

  1. ---
  2. meta:
  3.   - name: description
  4.     content: hello
  5.   - name: keywords
  6.     content: super duper SEO
  7. ---

其他格式的 Front Matter

除了 YAML 之外，VuePress 也支持 JSON 或者 TOML 格式的 front matter。

JSON front matter 需要以花括号开头和结尾：

  1. ---
  2. {
  3.   "title": "Blogging Like a Hacker",
  4.   "lang": "en-US"
  5. }
  6. ---

TOML front matter 需要显式地标注为 TOML：

  1. ---toml
  2. title = "Blogging Like a Hacker"
  3. lang = "en-US"
  4. ---

GitHub 风格的表格

Input

  1. | Tables        | Are           | Cool  |
  2. | ------------- |:-------------:| -----:|
  3. | col 3 is      | right-aligned | $1600 |
  4. | col 2 is      | centered      |   $12 |
  5. | 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

Input

  1. :tada: :100:

Output

:tada: :100:

目录

Input

  1. [[toc]]

Output

[[toc]]

目录（Table of Contents）的渲染可以通过 markdown.toc 选项来配置。

自定义容器

Input

  1. ::: tip
  2. This is a tip
  3. :::
  5. ::: warning
  6. This is a warning
  7. :::
  9. ::: danger
  10. This is a dangerous warning
  11. :::

Output

::: tip
This is a tip
:::

::: warning
This is a warning
:::

::: danger
This is a dangerous thing
:::

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

  1. ::: danger STOP
  2. Danger zone, do not proceed
  3. :::

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

代码块中的行高亮

Input

  1. ``` js{4}
  2. export default {
  3.   data () {
  4.     return {
  5.       msg: 'Highlighted!'
  6.     }
  7.   }
  8. }
  9. ```

Output

  1. export default {
  2.   data () {
  3.     return {
  4.       msg: 'Highlighted!'
  5.     }
  6.   }
  7. }

行号

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

  1. module.exports = {
  2.   markdown: {
  3.     lineNumbers: true
  4.   }
  5. }
  • 示例:


Image

Image

" class="reference-link">导入代码段

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

  1. <<< @/filepath

它也支持 行高亮：

  1. <<< @/filepath{highlightLines}

Input

  1. <<< @/test/markdown/fragments/snippet.js{2}

Output

<<< @/test/markdown/fragments/snippet.js{2}

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

进阶配置

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

  1. module.exports = {
  2.   markdown: {
  3.     // markdown-it-anchor 的选项
  4.     anchor: { permalink: false },
  5.     // markdown-it-toc 的选项
  6.     toc: { includeLevel: [1, 2] },
  7.     config: md => {
  8.       // 使用更多的 markdown-it 插件!
  9.       md.use(require('markdown-it-xxx'))
  10.     }
  11.   }
  12. }