在 Markdown 中使用 Vue

浏览器 API 访问限制

由于 VuePress 应用程序在生成静态构建文件时,会通过 Node.js 进行服务器端渲染,所以任何 Vue 用法都必须符合 编写通用代码 的要求。简而言之,确保只在 beforeMountedmounted 钩子函数中访问 浏览器特定 API / DOM API。

如果你正在使用或展示一个对于 SSR 不友好的组件(比如说包含了自定义指令),则可以将它们包装在内置的 <ClientOnly> 组件中:

<ClientOnly>
  <NonSSRFriendlyComponent/>
</ClientOnly>

请注意,这无法解决一些组件或库在**静态导入(import)**时就试图访问浏览器 API 的问题 - 为了使用在导入时使用浏览器环境的代码,你需要在合适的生命周期钩子函数中,动态导入(dynamically import)它们:

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

模板(templating)

插值

每个 markdown 文件首先被编译成 HTML,然后作为 Vue 组件传递给 vue-loader。这意味着你可以在文本中使用 Vue 风格的插值表达式:

输入

{{ 1 + 1 }}

输出

2

指令

也可以运行指令:

输入

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

输出

1 2 3 

访问网站和页面数据

编译后的组件没有任何私有数据,但是我们可以访问到 网站元数据。例如:

输入

{{ $page }}

输出

{
  "path": "/using-vue.html",
  "title": "Using Vue in Markdown",
  "frontmatter": {}
}

转义(escaping)

默认情况下,花括号代码块(fenced code blocks)会自动用 v-pre 包装。如果要在内联代码片段或纯文本内显示原始插值或特定于 Vue 的语法,则需要把段落包裹在 v-pre 自定义容器中:

输入

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

输出

{{ This will be displayed as-is }}

使用组件(Using Components)

.vuepress/components 中的所有 *.vue 文件都会自动注册为 全局(global)异步(async) 组件。例如:

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

在所有 markdown 文件中,你都可以直接使用这些组件(其名称(name)是从文件名推断出的):

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

Hello this is <demo-1>

This is another component

Hello this is <Foo-Bar>

重要

确保自定义组件的名称,是由连字符(hyphen)拼接,或者遵循帕斯卡命名(PascalCase)。否则,它将被视为内联元素,然后被包裹在一个 <p> 标签内,这将导致 hydration 无法匹配,这是因为 <p> 中不允许放置块元素。(译注:查看 SSR 客户端激活(client-side hydration)

在标题中使用 Vue 组件

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

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

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

TIP

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

使用预处理器

VuePress 已经为如下预处理器内置了相关的 webpack 配置:sass, scss, less, styluspug。要使用它们,你只需要在项目中安装对应的依赖即可。例如,要使用 sass,直接在项目中安装:

yarn add -D sass-loader node-sass

接着,你就可以在 markdown 或者主题组件中使用如下代码:

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

使用 <template lang="pug"> 需要安装 pugpug-plain-loader

yarn add -D pug pug-plain-loader

TIP

如果你是 Stylus 用户,那么不需要在项目中安装 stylusstylus-loader,因为 VuePress 内部已经使用了 Stylus。

对于没有内置 webpack 配置支持的预处理器,除了安装必要的依赖外,还需要 扩展内部 webpack 配置

脚本和样式提升

有时候,你可能只需要当前页面应用一些 JavaScript 或 CSS。在这些情况下,你可以在 markdown 文件中,直接编写根级别的 <script><style> 标签,它们会从编译后的 HTML 中提取出来,并作为生成的 Vue 单文件组件的 <script><style> 标签。

内置组件

() 用于表示这是一个外部链接。在 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".
  • 用法

这个组件可以用在标题文本的末尾,用来为某些 API 添加一些状态:

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

也可以参考:

上次更新: 2018-8-12 15:16:51