使用vuepress快速生成网站

背景 ​

在前端工程化的过程中，有一个符合团队甚至公司的前端编码规范是非常重要的一个环节，对于这个规范，不同的公司对应不同的方案，我所在的团队希望能放在页面上，让开发人员可以随时查阅，并且维护人员也要方便维护，vuepress 就发着光静静地躺在那里等着我去发现。

简介 ​

vuepress官网

特点 ​

vuepress 的三大特点：简洁至上、Vue 驱动和高性能。这个在首页一进去就能看到。

为什么不选其他 ​

作者也想到了这个最基本的问题，为什么要选我，而不选其他静态网站生成器？

Nuxt VuePress 能做的事情，Nuxt 理论上确实能够胜任，但 Nuxt 是为构建应用程序而生的，而 VuePress 则专注在以内容为中心的静态网站上，同时提供了一些为技术文档定制的开箱即用的特性。

Docsify / Docute 这两个项目同样都是基于 Vue，然而它们都是完全的运行时驱动，因此对 SEO 不够友好。如果你并不关注 SEO，同时也不想安装大量依赖，它们仍然是非常好的选择！

Hexo Hexo 一直驱动着 Vue 的文档 —— 事实上，在把我们的主站从 Hexo 迁移到 VuePress 之前，我们可能还有很长的路要走。Hexo 最大的问题在于他的主题系统太过于静态以及过度地依赖纯字符串，而我们十分希望能够好好地利用 Vue 来处理我们的布局和交互，同时，Hexo 的 Markdown 渲染的配置也不是最灵活的。

GitBook 我们的子项目文档一直都在使用 GitBook。GitBook 最大的问题在于当文件很多时，每次编辑后的重新加载时间长得令人无法忍受。它的默认主题导航结构也比较有限制性，并且，主题系统也不是 Vue 驱动的。GitBook 背后的团队如今也更专注于将其打造为一个商业产品而不是开源工具。

原理 ​

一个 VuePress 网站是一个由 Vue、Vue Router 和 webpack 驱动的单页应用。如果你以前使用过 Vue 的话，当你在开发一个自定义主题的时候，你会感受到非常熟悉的开发体验，你甚至可以使用 Vue DevTools 去调试你的自定义主题。

在构建时，会为应用创建一个服务端渲染（SSR）的版本，然后通过虚拟访问每一条路径来渲染对应的HTML。这种做法的灵感来源于 Nuxt 的 nuxt generate 命令，以及其他的一些项目，比如 Gatsby。

开始 ​

安装 ​

新建项目

npm init -y

安装vuepress

yarn global add vuepress 
# 或者：yarn add -D vuepress
# 或者：npm install -g vuepress
# 或者：npm install -D vuepress

如果你的现有项目依赖了 webpack 3.x，推荐使用 Yarn 而不是 npm 来安装 VuePress。因为在这种情形下，npm 会生成错误的依赖树。

项目结构 ​

项目结构可根据自己情况来，标准的是：

┌─ docs - 文档主目录
│  ├─ .vuepress - vuepress配置
│  │   ├─ public - 项目中用到的静态资源
│  │   ├─ styles - 覆盖vuepress主题的文件
│  │   └─ config.js - vuepress配置文件
│  ├─ page - 页面1
│  ├─ page2 - 页面2
│  ├─ ... - 其他页面
│  └─ README.md - 首页
└─ REAMDE.md - 项目说明文件

新增脚本 ​

在 package.json 里加一些脚本:

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

开始写文档 ​

启动项目

yarn docs:dev # 或者：npm run docs:dev

编译成html

yarn docs:build # 或者：npm run docs:build

默认情况下，文件将会被生成在 .vuepress/dist，也可以通过 .vuepress/config.js 中的 dest 字段来修改，生成的文件可以部署到任意的静态文件服务器上。

配置 ​

// todo