VuePress 入门教程之一快速入门篇
前言
VuePress 站点
静态网站生成器比较
Hexo
Hexo 是一个快速、简洁且高效的博客框架。Hexo 使用 Markdown(或其它渲染引擎)解析文章,在几秒内,即可利用靓丽的主题生成静态网页。Hexo 配合它的主题模块,比如 NexT 主题,可以作为非常简洁方便的静态博客系统。
GitBook
GitBook 是一个现代的文档平台,团队或个人可以在其上编写产品、API 接口文档以及团队内部知识库。GitBook 改版之后,感觉团队更专注于商业产品而不是开源工具,同时 CLI 工具不再提供了,所以无法实现个性化部署。
Nuxt
Nuxt.js 是一个基于 Vue.js 的通用应用框架。通过对客户端 / 服务端基础架构的抽象组织,Nuxt.js 主要关注的是应用的 UI 渲染。Nuxt.js 的目标是创建一个灵活的应用框架,你可以基于它初始化新项目的基础结构代码,或者在已有 Node.js 项目中使用 Nuxt.js。简而言之,Nuxt.js 更像是为构建应用程序而生的,而不是独立的内容静态网站。
Docsify
Docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 .md
转成 .html
文件,所有转换工作都是在运行时进。Docsify 是基于 Vue,完全的运行时驱动,不需要渲染 HTML,所以对 SEO 不够友好。如果不关注 SEO,安装简单化不想有大量依赖,它是比较好的选择,比如公司或这团队内部的文档系统。
Docute
Docute 本质上就是一个 JavaScript 文件,它可以获取 Markdown 文件并将它们呈现为单页面应用。它完全由运行时驱动,因此并不涉及服务端组件,这就意味着没有构建过程。你只需创建一个 HTML 文件和一堆 Markdown 文档,你的网站就差不多完成了!Docute 与 Docsify 基本一样,只是在文件大小和 UI 及不同的使用方式,Docute 官网有其差异的介绍。
VuePress
VuePress 实际上是由 Vue、Vue Router 和 Webpack 驱动的单页面应用程序,实现了 GitBook 的功能。VuePress 展示页面与 Docsify 类似,但是与 Docsify 不同的是会预先渲染 HTML。每个 Markdown 文件都使用 markdown-it 编译为 HTML,然后作为 Vue 组件的模板进行处理;这允许你直接在 Markdown 文件中使用 Vue,在需要嵌入动态内容时,这种使用方式非常有用。
Other
Jekyll、Typecho、Hugo、Ghost
VuePress 介绍
VuePress 由两部分组成:第一部分是一个极简静态网站生成器,它包含由 Vue 驱动的主题系统和插件 API,另一个部分是为书写技术文档而优化的默认主题,它的诞生初衷是为了支持 Vue 及其子项目的文档需求。每一个由 VuePress 生成的页面都带有预渲染好的 HTML,也因此具有非常好的加载性能和搜索引擎优化(SEO)。同时,一旦页面被加载,Vue 将接管这些静态内容,并将其转换成一个完整的单页应用(SPA),其他的页面则会只在用户浏览到的时候才按需加载。
工作原理
事实上,一个 VuePress 网站是一个由 Vue、Vue Router 和 Webpack 驱动的单页应用。如果你以前使用过 Vue 的话,当你在开发一个自定义主题的时候,你会感受到非常熟悉的开发体验,你甚至可以使用 Vue DevTools 去调试你的自定义主题。在构建时,我们会为应用创建一个服务端渲染(SSR)的版本,然后通过虚拟访问每一条路径来渲染对应的 HTML。这种做法的灵感来源于 Nuxt 的 nuxt generate
命令,以及其他的一些项目,比如 Gatsby。
功能说明
内置的 Markdown 拓展
在 Markdown 中 使用 Vue
Vue 驱动的自定义主题系统
默认主题
- Responsive layout
- 首页
- 内置的搜索
- Algolia 搜索
- 可定制的 navbar and sidebar
- 自动生成的 GitHub 链接和页面编辑链接
- PWA: 刷新内容的 Popup
- 最后更新时间
- 多语言支持
博客主题
Plugin
VuePress 快速入门
Warning 前提条件:VuePress 需要 Node.js >= 8.6
下述内容会帮助你从头搭建一个简单的 VuePress 文档,如果你想在一个现有的项目中使用 VuePress 来管理文档,从步骤 3 开始。
- 创建并进入一个新目录
1 | $ mkdir vuepress-starter && cd vuepress-starter |
- 使用你喜欢的包管理器进行初始化
1 | $ yarn init |
- 将 VuePress 安装为本地依赖
1 | $ yarn add -D vuepress |
Warning 注意:官方已经不再推荐全局安装 VuePress,如果你的现有项目依赖了 Webpack 3.x,则推荐使用 Yarn 而不是 NPM 来安装 VuePress。因为在这种情形下,NPM 会生成错误的依赖树
- 创建第一篇文档
1 | $ mkdir docs && echo '# Hello VuePress' > docs/README.md |
- 在
package.json
中添加一些 scripts
这一步骤是可选的,但推荐你完成它。在下文中,会默认这些 scripts 已经被添加。
1 | { |
- 在本地启动服务器
1 | $ yarn docs:dev |
VuePress 会在 http://127.0.0.1:8080
启动一个热重载的开发服务器,此时你就拥有了一个简单可用的 VuePress 文档。当你的文档逐渐成型的时候,不要忘记 VuePress 的 多语言支持 ,并了解一下如何将你的文档 部署 到任意静态文件服务器上。
- 目录结构说明
如果 docs
目录做为顶级目录(非 vuepress-starter
的子目录),如下所示:
1 | . |
那么 package.json
的配置内容需要更改为:
1 | { |
Shell 脚本的内容则更改为:
1 | $ yarn dev |
VuePress 基础概念
目录结构
VuePress 遵循 “约定优于配置” 的原则,推荐的目录结构如下:
1 | . |
Warning 注意:请留意目录名的大写
docs/.vuepress
: 用于存放全局的配置、组件、静态资源等。docs/.vuepress/components
: 该目录中的 Vue 组件将会被自动注册为全局组件。docs/.vuepress/theme
: 用于存放本地主题。docs/.vuepress/styles
: 用于存放样式相关的文件。docs/.vuepress/styles/index.styl
: 将会被自动应用的全局样式文件,会生成在最终的 CSS 文件结尾,具有比默认样式更高的优先级。docs/.vuepress/styles/palette.styl
: 用于重写默认颜色常量,或者设置新的 stylus 颜色常量。docs/.vuepress/public
: 静态资源目录。docs/.vuepress/templates
: 存储 HTML 模板文件。docs/.vuepress/templates/dev.html
: 用于开发环境的 HTML 模板文件。docs/.vuepress/templates/ssr.html
: 构建时基于 Vue SSR 的 HTML 模板文件。docs/.vuepress/config.js
: 配置文件的入口文件,也可以是YML
或toml
。docs/.vuepress/enhanceApp.js
: 客户端应用的增强。
Warning 注意:当你想要去自定义
templates/ssr.html
或templates/dev.html
时,最好基于 默认的模板文件 来修改,否则可能会导致构建出错
页面路由
此处一般把 docs
目录作为 targetDir
(参考 命令行接口),下面所有的 “文件的相对路径” 都是相对于 docs
目录的。在项目根目录下的 package.json
中添加如下 scripts
:
1 | { |
对于上述的目录结构,Vuepress 的默认页面路由地址如下:
文件的相对路径 | 页面路由地址 |
---|---|
/README.md | / |
/guide/README.md | /guide/ |
/config.md | /config.html |
基本配置
配置文件
如果没有任何配置,这个网站将会是非常局限的,用户也无法在你的网站上自由导航。为了更好地自定义你的网站,首先需要在你的文档目录下创建一个 .vuepress
目录,所有 VuePress 相关的文件都将会被放在这里,项目结构示例如下:
1 | . |
一个 VuePress 网站最必要的配置文件是 .vuepress/config.js
,它应该导出一个 JavaScript 对象:
1 | module.exports = { |
对于上述的配置,如果你运行起 dev server
,你应该能看到一个页面,它包含一个页头,里面包含一个标题和一个搜索框。VuePress 内置了基于 headers
的搜索 —— 它会自动为所有页面的标题、h2
和 h3
构建起一个简单的搜索索引。可参见 配置 来查看所有可配置的选项。
Tip 其他配置格式:你也可以使用 YAML (
.vuepress/config.yml
) 或是 TOML (.vuepress/config.toml
) 格式的配置文件
主题配置
一个 VuePress 主题应该负责整个网站的布局和交互细节。在 VuePress 中,目前自带了一个默认的主题(正是你现在所看到的),它是为技术文档而设计的。同时,默认主题提供了一些选项,让你可以去自定义导航栏(navbar)、 侧边栏(sidebar)和 首页(homepage) 等,详情请参见 默认主题配置 ,如果你想开发一个自定义主题,可以参考 自定义主题。
应用级别的配置
由于 VuePress 是一个标准的 Vue 应用,你可以通过创建一个 .vuepress/enhanceApp.js
文件来做一些应用级别的配置,当该文件存在的时候,会被导入到应用内部。enhanceApp.js
应该 export default
一个钩子函数,并接受一个包含了一些应用级别属性的对象作为参数。你可以使用这个钩子来安装一些附加的 Vue 插件、注册全局组件,或者增加额外的路由钩子等:
1 | // 使用异步函数也是可以的 |
静态资源
相对路径
所有的 Markdown 文件都会被 Webpack 编译成 Vue 组件,因此你可以,并且应该更倾向于使用相对路径(Relative URLs)来引用所有的静态资源:
1 |  |
同样地,这在 *.vue
文件的模板中一样可以工作,图片将会被 url-loader
和 file-loader
处理,在运行生成静态文件的构建任务时,文件会被复制到正确的位置。
除此之外,你也使用 ~
前缀来明确地指出这是一个 Webpack 的模块请求,这将允许你通过 Webpack 别名来引用文件或者 NPM 的依赖:
1 |  |
Webpack 的别名可以通过 .vuepress/config.js
中 configureWebpack 来配置,如:
1 | module.exports = { |
公共文件
有时,你可能需要提供一个静态资源,但是它们并不直接被你的任何一个 Markdown 文件或者主题组件引用 —— 举例来说,favicons 和 PWA 的图标,在这种情形下,你可以将它们放在 .vuepress/public
中, 它们最终会被复制到生成的静态文件夹中。
基础路径
如果你的网站会被部署到一个非根路径,你将需要在 .vuepress/config.js
中设置 base
,举例来说,如果你打算将你的网站部署到 https://foo.github.io/bar/
,那么 base
的值就应该被设置为 "/bar/"
(应当总是以斜杠开始,并以斜杠结束)。有了基础路径(Base URL),如果你希望引用一张放在 .vuepress/public
中的图片,你需要使用这样路径:/bar/image.png
,然而,一旦某一天你决定去修改 base
,这样的路径引用将会显得异常脆弱。为了解决这个问题,VuePress 提供了内置的一个 helper $withBase
(它被注入到了 Vue 的原型上),可以帮助你生成正确的路径:
1 | <img :src="$withBase('/foo.png')" alt="foo"> |
值得一提的是,你不仅可以在你的 Vue 组件中使用上述的语法,在 Markdown 文件中亦是如此。最后补充一句,一个 base
路径一旦被设置,它将会自动地作为前缀插入到 .vuepress/config.js
中所有以 /
开始的资源路径中。
多语言支持
站点多语言配置
要启用 VuePress 的多语言支持,首先需要使用如下的文件结构:
1 | docs |
然后,在 .vuepress/config.js
中提供 locales
选项:
1 | module.exports = { |
如果一个语言没有声明 title
或者 description
,VuePress 将会尝试使用配置顶层的对应值。如果每个语言都声明了 title
和 description
,则顶层的这两个值可以被省略。
默认主题多语言配置
默认主题也内置了多语言支持,可以通过 themeConfig.locales
来配置。该选项接受同样的 { path: config }
格式的值。每个语言除了可以配置一些站点中用到的文字之外,还可以拥有自己的 导航栏 和 侧边栏 配置:
1 | module.exports = { |
编译构建
- 在
config.js
中指定构建的目标目录:
1 | module.exports = { |
- 通过以下命令编译构建,生成 VuePress 网站所需的静态文件,这样就可以很方便地将 VuePress 文档部署到任意的 Web 服务器
1 | # 编译构建 |
- 目录结构说明
如果 docs
目录做为顶级目录,如下所示:
1 | . |
那么 config.js
的配置内容需要更改为:
1 | module.exports = { |
编译构建的命令则更改为:
1 | $ yarn build |
部署方式
GitHub Pages
- 在
docs/.vuepress/config.js
中设置正确的base
- 如果你打算发布到
https://<USERNAME>.github.io/
,则可以省略这一步,因为base
默认即是"/"
。 - 如果你打算发布到
https://<USERNAME>.github.io/<REPO>/
(也就是说你的仓库在https://github.com/<USERNAME>/<REPO>
),则将base
设置为"/<REPO>/"
。
- 在你的项目中,创建一个如下的
deploy.sh
文件(请自行判断去掉对应的注释)
1 | #!/usr/bin/env sh |
你可以在你的持续集成的设置中,设置在每次 Push 代码时自动运行上述 Shell 脚本
GitHub Pages and Travis CI
- 在
docs/.vuepress/config.js
中设置正确的base
- 如果你打算发布到
https://<USERNAME or GROUP>.github.io/
,则可以省略这一步,因为base
默认即是"/"
。 - 如果你打算发布到
https://<USERNAME or GROUP>.github.io/<REPO>/
(也就是说你的仓库在https://github.com/<USERNAME>/<REPO>
),则将base
设置为"/<REPO>/"
。
在项目的根目录创建一个名为
.travis.yml
的文件在本地执行
yarn
或npm install
并且提交生成的lock
文件(即yarn.lock
或package-lock.json
)使用 GitHub Pages 部署提供程序模板,并遵循 Travis 文档规范 来编写
.travis.yml
文件
1 | language: node_js |