vuepress 系列一：基础与环境搭建

littleLane
400 阅读6分钟

前言

众所周知，近几年 Vue 项目已经大火。作为一个渐进式的 Web 前端应用的构建框架，Vue 凭着学习曲线平缓、社区活跃赢得了广大开发者的喜爱和投产使用。相应的，社区中关于 Vue 的衍生产物也是层出不穷，比如各个公司出的 UI 框架、基于 Vue 的丰富开发的构建工具等等。其中 Vuepress 就是基于 Vue + Vue Router + Webpack 的自动生成静态文档、支持 MarkDown 的项目。

关于这个项目，笔者早些时候也琢磨过，但是一直没有用武之地或者说没有实际的使用，所以捣鼓捣鼓就放弃了。最近，公司项目组开始利用 Vue 技术栈重构一些项目，希望在项目中维护相应的需求和技术实现的文档，所以考虑集成 Vuepress ，故有了这一系列关于 Vuepress 的文章。

话不多说，咱们赶紧开始吧！

基础

Vuepress 是基于 Vue 技术栈的一个静态网站生成器，内置一个经过优化过的专注写文档的主题。开发者只需要做简单的配置和专注于写文档，而不用关心其他的任何东西。Vuepress 会将每个 MarkDown 文件对应的生成预渲染静态 HTML，并可以出色的完成加载，最最重要的是对 SEO 非常优化。在页面加载完成之后，Vue 会将这些静态内容接管为完整的单页面应用程序(SPA)。当用户在浏览站点时，可以按需加载其他页面。

除了上面说到的 Vuepress 相关的内容外，Vuepress 支持了非常多优秀的特性：

  • 通过内置 markdown 扩展，针对技术文档进行优化
  • 可以在 MarkDown 文件中内嵌 Vue 代码
  • 以 Vue 驱动的自定义主题系统
  • PWA 支持
  • Google Analytics 集成
  • 集成一个默认主题：
    • 响应式布局
    • 可选的主页
    • 简单、开箱即用、基于标题的搜索功能
    • 可定制的导航栏和侧边栏
    • 自动生成的 GitHub 链接和页面编辑链接

关于 Vuepress 的详细资料，大家可以转到 Vuepress 的官网。

环境搭建

全局的安装

当全局安装使用时，只需要简单的三步就可以开始写文档了，具体步骤如下：

# 全局安装
# ⚠️ 注意：这里或许你根本不需要全局安装 vuepress 包，如果你对 npx 了解的话
npm install -g vuepress

# 创建一个 markdown 文件
echo '# Hello VuePress' > README.md

# ⚠️ 注意：如果你使用的是 npx，下面的两个步骤略有不同
# 开始编写文档
vuepress dev

# 构建文档
vuepress build

在已有项目中集成

其实在实际的应用过程中，全局安装可能是比较少的（当然也不排除），因为我们的文档一般是跟着项目走的，所以我们这里详细的介绍一下如何在已有的项目中集成 Vuepress。

# 安装为本地依赖项
npm install -D vuepress

# 在项目中创建一个 docs 目录
mkdir docs

# 创建一个 markdown 文件
echo '# Hello VuePress' > docs/README.md

# 开始编写文档
npx vuepress dev docs

# 当然这里我们为了项目的统一化管理，可以在 package.json 文件中添加如下的命令
"scripts": {
	# 启动文档的编写环境
	"docs:dev": "vuepress dev docs",
  
  # 构建最终的静态资源文件
	"docs:build": "vuepress build docs"
}

目录介绍

├─.vuepress
│ ├─components // 自定义样式布局组件文件目录
│ └─public	// 静态资源文件目录
│		└─icons
│ └─config.js // 主配置文件
├─ foo/		// 具体的文档目录
│  ├─ README.md
│  ├─ one.md
│  └─ two.md
└─ bar/		// 具体的文档目录
   ├─ README.md
   ├─ three.md
   └─ four.md
└─README.md // 首页配置文件

⚠️注意：以上展示的目录结构都是位于 docs 文件目录下的！

接下来，大致介绍一下各个目录的作用：

  • Vuepress 所有的配置文件都在 .vuepress 目录下，其中包括文档样式的主要配置文件 config.js，文档自定义的布局样式组件 components，在这里是通过编写 Vue 组件来实现基础布局的。public 目录下存放的是文档所有相关的图片等静态文件，在 MarkDown 文件中通过绝对路径引用就可以了。
  • 与 .vuepress 目录同级的目录就是具体的文档目录了，每个具体的文档目录下必须最好有一个 README.md 文件，作为部分文档的首页存在。具体目录下的其他文件就是各部分的文档文件了。
  • 与 .vuepress 目录同级的 README.md 就是整个文档项目的终极首页文档文件了，相当于我们平时项目中的 index.html 文件，当然最终通过 build 生成的静态也就是对应的 index.html 了。

### 部署

文档写好了，肯定是要部署的，这里我们重点说一下！

谈到部署，那我们就捋一下实际部署的一个思路吧：

  • 1、首先我们编写文档时，主要写的是 MarkDown 文件，Vuepress 可以通过构建的方式将所有的 MarkDown 文件转换成浏览器可以识别的 HTML 文件
  • 2、然后就像我们平时部署静态应用一下将生成的静态资源文件丢到服务器的相应的目录就可以了。

GitHub 部署

# 构建静态资源
vuepress build docs

# 导航到构建输出目录
cd docs/.vuepress/dist

# 执行 git 命令
git init
git add -A
git commit -m 'deploy'

# 推到你仓库的的 gh-page 分支
# 将 <USERNAME>/<REPO> 替换为你的信息
git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

github 静态资源部署是很简单的：首先是构建静态资源，然后将静态资源通过 git 工具 push 到自己事先建立好的 github 仓库对应的 gh-pages 分支就可以了，后续的操作都是 github 集成、自动完成的了。

⚠️ 这里有几个需要非常注意的点：

  • 1、Vuepress 默认构建生成的静态资源是放在 docs/.vuepress/dist 目录下的，如果你不喜欢这个目录，可以在 docs/.vuepress/config.js 通过 dest 参数进行配置。如果你是自己配置的目录，在部署命令中，你应该注意正确处理目录。
  • 2、将 .vuepress/config.js 中的 base 设置为你的仓库名称。例如，如果你的仓库是 https://github.com/foo/bar ，则已部署的页面将在 https://foo.github.io/bar 上可用。在这种情况下，你应该将base设置为 "/bar/" 。
  • 3、当你通过这个部署命令向远端仓库 push 代码可能会遇到 git ssh 权限的问题，你可以点击跳到这里，参考解决方案。

当然，你也可以在 CI 设置中运行此脚本以启用每次推送时的自动部署！

总结

以上内容简单介绍了 Vuepress 相关的基础和实际环境的搭建，通过各种细节展示了 Vuepress 实际的使用和操作，最后还讲到了 github 部署。Vuepress 整体是一个很强大的自动化文档工具，大家一起学习吧！

avatar
文章
阅读
粉丝