初探 VuePress

3,045 阅读3分钟
原文链接: zhuanlan.zhihu.com

前言

文档内容不多,就花半天时间翻译了一下,比较匆忙,有一些不是很理解的地方翻译的不是很通顺甚至有错误,欢迎大家指正。VuePress 中文

个人觉得最大的亮点就是:

  1. VuePress 文档是用 VuePress 写的
  2. markdown 文件可以内嵌 Vue 组件
  3. 借助 YAML 来作为驱动和配置文档
    ...

自己写自己的文档

今天一友人逛掘金的时候发现了这个好东西,遂推荐给我。

抱着玩一玩的心态,我就装了一个,反正不要钱,哈哈~

可是谁知道不玩不要紧,一玩就吃了闭门羹:

这我就不服气了,所以赶紧去 github 上提了个 issue,结果这破问题占据了 issue 榜上一整天,评论数还最多,最后的原因也找到了:Win10 的 Powershell 的锅。

不过当时我不知道啊,看这报错像是库本身有个地方出错了。出于猎奇的心,我 clone 了一份源码正准备调试...

咦,它这个 docs 文件夹?貌似就是一份 VuePress 的例子:

要不?在这文件下跑一个 vuepress dev 命令试试?诶!还真跑起来了!

不过新的问题又随之而来:

这真是让人头大,不过幸好现在也被尤大修复了:issue34

所以,我就抛弃了全局从 npm 拉下的包,转而用项目本身最新的代码来跑这份文档。

一切皆组件

文档里隐藏着一个惊天大秘密:

目前 VuePress 支持的三种格式 html、md、vue 实际上最后都会转成 vue 组件!

也就是说形成了一个 markdown->html->vue 的管道。

小试牛刀

基于这个我最感兴趣的点,我做了一个小组件来体验一下:代码编辑组件。

很多时候,我们为了那么一两个功能或者 API 不得不重新拉个项目、装 npm 包,然后漫长的时光渡过了,环境配好,却已忘记自己要干啥。

所以,简单点,像 echarts 或者 G2 那样,在线调试,所见即所得,多好~

不过最终还是搞出个 demo:

大家也看到了,还有很明显的 bug:不知道为啥被替换成繁字体聽的空格君,所以丢人的代码就先不放出来了...

YAML

就拿我刚刚实现的那个在线调试小组件来说,用的时候 markdown 文件里只需要这样写:

<CodeEditor :code="$page.frontmatter.code"/>

这个 $page.frontmatter.code 自然就是 markdown 里面定义的变量了,它使用的是 YAML 语法

JSON 原来是 YAML 的子集呢!

其他功能

VuePress 还有很多很棒的功能,比如一键部署(集成 git)、Algolia DocSearch 集成(借助 SSR 对 SEO 友好)等也是可圈可点的。只不过今天来不及玩了。

展望

今天的翻译也引起了我对文档国际化的思考,Vue 官方其实也在考虑这件事情,只不过要任重道远~