# 在 MarkDown 中使用 Vue

# 浏览器的 API 访问限制

当你在开发一个 VuePress 应用时，由于所有的页面在生成静态 HTML 时都需要通过 Node.js 服务端渲染，因此所有的 Vue 相关代码都应当遵循编写通用代码的要求。简而言之，请确保只在 beforeMount 或者 mounted 访问浏览器 / DOM 的 API。

如果你正在使用，或者需要展示一个对于 SSR 不怎么友好的组件（比如包含了自定义指令），你可以将它们包裹在内置的 <ClientOnly> 组件中：

<ClientOnly>
  <NonSSRFriendlyComponent/>
</ClientOnly>

1
2
3

请注意，这并不能解决一些组件或库在导入时就试图访问浏览器 API 的问题 —— 如果需要使用这样的组件或库，你需要在合适的生命周期钩子中动态导入它们：

<script>
export default {
  mounted () {
    import('./lib-that-access-window-on-import').then(module => {
      // use code
    })
  }
}
</script>

1
2
3
4
5
6
7
8
9

# 模板语法

# 插值

每一个 Markdown 文件将首先被编译成 HTML，接着作为一个 Vue 组件传入 vue-loader，这意味着你可以在文本中使用 Vue 风格的插值：

Input

{{ 1 + 1 }}

Output

# 指令

同样地，也可以使用指令:

Input

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

Output

1 2 3

# 访问网站以及页面的数据

编译后的组件没有私有数据，但可以访问网站的元数据，举例来说：

Input

{{ $page }}

Output

{
  "title": "在 MarkDown 中使用 Vue",
  "frontmatter": {},
  "regularPath": "/home/MarkDown-Vue.html",
  "relativePath": "home/MarkDown-Vue.md",
  "key": "v-0efa5d90",
  "path": "/home/MarkDown-Vue.html",
  "headers": [
    {
      "level": 2,
      "title": "浏览器的 API 访问限制",
      "slug": "浏览器的-api-访问限制"
    },
    {
      "level": 2,
      "title": "模板语法",
      "slug": "模板语法"
    },
    {
      "level": 3,
      "title": "插值",
      "slug": "插值"
    },
    {
      "level": 3,
      "title": "指令",
      "slug": "指令"
    },
    {
      "level": 3,
      "title": "访问网站以及页面的数据",
      "slug": "访问网站以及页面的数据"
    },
    {
      "level": 2,
      "title": "Escaping",
      "slug": "escaping"
    },
    {
      "level": 2,
      "title": "使用组件",
      "slug": "使用组件"
    },
    {
      "level": 3,
      "title": "在标题中使用组件",
      "slug": "在标题中使用组件"
    },
    {
      "level": 2,
      "title": "使用预处理器",
      "slug": "使用预处理器"
    },
    {
      "level": 2,
      "title": "脚本和样式提升",
      "slug": "脚本和样式提升"
    },
    {
      "level": 2,
      "title": "内置的组件",
      "slug": "内置的组件"
    },
    {
      "level": 3,
      "title": "OutboundLink",
      "slug": "outboundlink"
    },
    {
      "level": 3,
      "title": "ClientOnly",
      "slug": "clientonly"
    },
    {
      "level": 3,
      "title": "Content",
      "slug": "content"
    },
    {
      "level": 3,
      "title": "Badge",
      "slug": "badge"
    }
  ]
}

# Escaping

默认情况下，块级 (block) 的代码块将会被自动包裹在 v-pre 中。如果你想要在内联 (inline) 的代码块或者普通文本中显示原始的大括号，或者一些 Vue 特定的语法，你需要使用自定义容器 v-pre 来包裹：

Input

::: v-pre
`{{ This will be displayed as-is }}`
:::

1
2
3

Output

{{ This will be displayed as-is }}

# 使用组件

所有在 .vuepress/components 中找到的 *.vue 文件将会自动地被注册为全局的异步组件，如：

.
└─ .vuepress
└─ components
	├─ demo-1.vue
	├─ OtherComponent.vue
	└─ Foo
		└─ Bar.vue

你可以直接使用这些组件在任意的 Markdown 文件中（组件名是通过文件名取到的）：

<demo-1/>
<OtherComponent/>
<Foo-Bar/>

Hello this is <demo-1>

This is another component

Hello this is <Foo-Bar>

重要！

请确保一个自定义组件的名字包含连接符或者是 PascalCase，否则，它将会被视为一个内联元素，并被包裹在一个 <p> 标签中，这将会导致 HTML 渲染紊乱，因为 HTML 标准规定， <p> 标签中不允许放置任何块级元素。

# 在标题中使用组件

你可以在标题中使用 Vue 组件，但是请留意以下两种方式的不同：

Markdown	输出的 HTML	解析后的标题
`# text <Tag/>`	`<h1>text <Tag/></h1>`	`text`
# text `<Tag/>`	`<h1>text <code><Tag/></code></h1>`	`text <Tag/>`

被 <code> 包装的 HTML 将按原样显示，只有未被包装的 HTML 才会被 Vue 解析。

TIP

输出的 HTML 由 markdown-it 完成。而解析后的标题由 VuePress 完成，用于侧边栏以及文档的标题。

# 使用预处理器

VuePress 对以下预处理器已经内置相关的 webpack 配置：sass、scss、less、stylus 和 pug。要使用它们你只需要在项目中安装对应的依赖即可。例如，要使用 sass，需要安装：

yarn add -D sass-loader node-sass

然后你就可以在 Markdown 或是组件中使用如下代码：

<style lang="sass">
  .title
    font-size: 20px
</style>

1
2
3
4

要在组件中使用 <template lang="pug">，则需要安装 pug 和 pug-plain-loader:

yarn add -D pug pug-plain-loader

TIP

需要指出的是，如果你是一个 stylus 用户，你并不需要在你的项目中安装 stylus 和 stylus-loader，因为 VuePress 已经内置了它们。

对于那些没有内置的预处理器，除了安装对应的依赖，你还需要拓展内部的 Webpack 配置。

# 脚本和样式提升

有时，你可以只想在当前页面应用一些 JavaScript 或者 CSS，在这种情况下，你可以直接在 Markdown 文件中使用原生的 <script> 或者 <style> 标签，它们将会从编译后的 HTML 文件中提取出来，并作为生成的 Vue 单文件组件的 <script> 和 <style> 标签。

这个块是被内联的脚本渲染的，样式也采用了内联样式。

# 内置的组件

# OutboundLink stable

() 用来表明当前是一个外部链接。在 VuePress 中这个组件会紧跟在每一个外部链接后面。

# ClientOnly stable

参考浏览器的 API 访问限制。

# Content beta

Props:
- custom - boolean
用法：

当前的 .md 文件渲染的内容，当你在使用自定义布局时，它将非常有用。

<Content/>

参考:

自定义主题 > 获取渲染内容

# Badge beta 0.10.1+

Props:
- text - string
- type - string, 可选值： "tip"|"warn"|"error"，默认值是： "tip"
- vertical - string, 可选值： "top"|"middle"，默认值是： "top"
Usage:

你可以在标题中，使用这个组件来为某些 API 添加一些状态：

### Badge <Badge text="beta" type="warn"/> <Badge text="0.10.1+"/>

参考:

在标题中使用组件

← 在 VuePress 中扩展在 VS Code 中编写快捷键 →