团队技术文档构建利器vuepress上手实践

团队技术文档构建利器vuepress上手实践

Write By CS逍遥剑仙
我的主页: www.csxiaoyao.com
GitHub: github.com/csxiaoyaojianxian
Email: [email protected]

最近在尝试一些项目技术文档搭建的工具，看到网上很多人推荐 gitbook，使用后总体感觉良好。无意中发现一款 Vue 驱动的静态站点生成工具 vuepress，看到官网和demo后立即被它的简约灵活所吸引。一个 vuepress 网站是一个由 Vue、Vue Router 和 Webpack 驱动的单页应用。在构建时，创建一个服务端渲染（SSR）的版本，然后通过虚拟访问每一条路径来渲染对应的HTML。

本文做一个上手实践总结。如果正有搭建技术文档的需求，而且熟悉 vue 生态，相信我，选择 vuepress 一定不会后悔。官方文档地址：https://vuepress.vuejs.org，vue 生态一大优势在于中文文档，vuepress 也不例外，中文文档一样靠谱：https://www.vuepress.cn，官方文档十分详细，本文也不再过多搬运，主要讲下自己的实践。

1. 环境搭建

跟随 vuepress 文档操作一遍，非常顺畅，轻轻松松搭好。

# 全局安装
> yarn global add vuepress
# 创建一个 markdown 文件，仅包含一个标题
> echo '# Hello VuePress' > README.md

编写文档，类似 webpack 中的 devServer，在本地启动一个服务器，浏览器访问 localhost:8080 进行访问。

# 开始编写文档
> vuepress dev

编写完文档需要打包构建后才能部署，文件在 ./vuepress/dist 目录下，可以通过配置 .vuepress/config.js 中的 dest 字段修改。

# 构建
vuepress build

如果是已经有项目，只是想在该项目中管理文档，则应该将 vuepress 安装为本地依赖，具体可以参考官方文档。

2. 目录结构

项目创建完后，最简的目录结构如下：

├─ docs
│  ├─ README.md
│  └─ .vuepress
│     └─ config.js
└─ package.json

官方推荐的完整目录结构如下：

├── docs
│   ├── .vuepress (可选的) 用于存放全局的配置、组件、静态资源等
│   │   ├── components (可选的) Vue组件将会被自动注册为全局组件
│   │   ├── theme (可选的) 用于存放本地主题
│   │   │   └── Layout.vue
│   │   ├── public (可选的) 静态资源目录
│   │   ├── styles (可选的) 用户存放样式相关文件
│   │   │   ├── index.styl 将会被自动应用的全局样式文件，会生成在最终的css文件结尾，具有比默认样更高级的优先级
│   │   │   └── palette.styl 用于重写默认样式常量，或者设置新的stylus颜色常量
│   │   ├── templates (可选的, 谨慎配置) 存储HTML模板文件
│   │   │   ├── dev.html
│   │   │   └── ssr.html
│   │   ├── config.js (可选的) 配置文件的入口文件
│   │   └── enhanceApp.js (可选的) 客户端应用的增强
│   │
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│
└── package.json

其中，docs 是项目根目录，名称可以自定义，.vuepress/config.js 是使用频率最高的配置文件，一般来说，实际的文档文件会放在根目录下，通过路由获取。

3. 参数配置

vuepress 提供了两类配置：

• 配置文件，如 .vuepress/config.js，需要导出一个js对象，一般用于进行全局配置
• YAML front matter，配置在 md 文件头部，其后的内容才作为文档内容被渲染，一般用于针对当前文档的配置

3.1 主题配置

新建完后用户默认看到的页面是非常简陋的，只有一个包含搜索框的 head，vuepress 的强大之处在于可以灵活地进行主题配置，完成配置后一个丰富的技术文档页就构建好了，下面罗列常用的配置项及其功能，具体配置内容参考官方文档。

3.1.1 主页(homepage)

默认主题提供了一个首页（Homepage）布局，用于网站的主页 docs/README.md，使用 YAML front matter 配置。

3.1.2 导航栏(navbar)

themeConfig.nav 导航栏包括 左侧页面标题、搜索框、导航栏链接、多语言支持、仓库链接，支持下拉分组菜单，还支持在全局或单页面中禁用。

3.1.3 侧边栏(sidebar)

themeConfig.sidebar 侧边栏一般用于文档的目录索引，可以直接在 config.js 中配置链接数组，也在页面中配置 sidebar:auto 自动生成侧边栏目录，但是自动生成只能生成当前页。侧边栏还支持以下更加细节的设置：

• 设置嵌套层数
• 是否展开所有
• 标题链接是否激活(禁用可以懒加载提升性能)
• 分组
• 侧边栏分页面定制
• 禁用

3.1.4 搜索框(search box)

themeConfig.search 支持禁用、修改搜索提示数量、启用 Algolia Search。

3.1.5 最近更新

themeConfig.lastUpdated 选项允许获取每个文件的最后一次 git 提交的 UNIX 时间戳（ms），并以合适的格式显示在每个页面的底部。

3.1.6 Service Worker

themeConfig.serviceWorker 选项允许进行 service worker 相关的配置。

3.1.7 上一页 / 下一页链接(prev / next links)

可以在每个页面设置上下页链接。

3.1.8 Git 仓库和编辑链接

themeConfig.repo 会在导航中生成 github 链接。

3.2 样式编辑

3.2.1 默认样式覆盖

如果希望修改默认样式，可以创建两个文件 .vuepress/styles/index.styl、 .vuepress/styles/palette.styl，index.styl 作为全局样式文件生成在最终的css文件结尾，具有比默认样式更高的优先级，palette.styl 用于重写默认样式常量，或者设置新的 stylus 颜色常量，如：

$accentColor = #3eaf7c
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34

3.2.2 自定义页面类

若需要为特定页面添加一个 CSS 类名，可以在该页面的 YAML front matter 中声明一个 pageClass：

---
pageClass: custom-page-class
---

index.styl 中可以使用对应的类名：

.theme-container.custom-page-class {
  /* 页面特定的规则 */
}

4. markdown 扩展操作

4.1 Emoji

:tada: :100:

4.2 目录

[[toc]]

4.3 自定义容器

::: tip 注意：
This is a tip
:::

::: warning
This is a warning
:::

::: danger STOP
This is a dangerous warning
:::

4.4 在代码块中高亮显示行

​```js{4}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
​```

4.5 导入代码片段

<<< @/public/test.js{2}

5. 在 Markdown 中使用 Vue

.vuepress/components 中的所有 *.vue 文件都会自动注册为全局异步组件，如：

.
└─ .vuepress
   └─ components
      ├─ demo.vue
      └─ Foo
         └─ Bar.vue

可以直接在所有 markdown 文件中使用这些组件。

6. 自定义主题

创建 .vuepress/theme 目录和 Layout.vue 文件，详见文档。

7. GitHub Pages 部署

发布 GitHub Pages 需要在 .vuepress/config.js 中设置正确的 base。例如发布到 https://.github.io/，base 默认即是"/"，如果打算发布到 https://.github.io//（即仓库在 https://github.com//），需要设置 base 为 "//"。

module.exports = {
  base: '/test/'
}

可以在项目中创建 deploy.sh 文件，方便在持续集成的设置中在每次 push 代码时自动运行脚本。

#!/usr/bin/env sh
# 确保脚本抛出遇到的错误
set -e
# 生成静态文件
npm run docs:build
# 进入生成的文件夹
cd docs/.vuepress/dist

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果发布到 https://.github.io
# git push -f [email protected]:/.github.io.git master

# 如果发布到 https://.github.io/
# git push -f [email protected]:/.git master:gh-pages

cd -

设置package.json

{
  "script":{
    "deploy": "bash deploy.sh",
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

运行脚本推送更新到 github 上

> npm run deploy

8. 附录：config.js 详细配置 demo

module.exports = {
     
    base: '/', // 用于部署时的子路径
    title: 'csxiaoyao.com', // 网站的标题
    description: 'luban document, created by victorsun', // 网站描述，HTML中表现为一个  标签
    head: [ // head 中额外标签
        // ['link', { rel: 'icon', href: '/logo.png' }]
    ],
    host: '0.0.0.0', // dev 服务器的主机
    port: 2048, // dev 服务器的端口
    dest: './dist', // 指定 vuepress build 的输出目录
    evergreen: false, // 忽略浏览器兼容性
    markdown: {
     
        lineNumbers: true, // 代码块的左侧显示行号
        externalLinks: {
      target: '_blank', rel: 'noopener noreferrer' }, // 键和值对将被添加到指向外部链接的  标签，默认选项将在新窗口中打开外部链接
        anchor: {
      permalink: true, permalinkBefore: true, permalinkSymbol: '#' }, // 锚点配置
        toc: {
      includeLevel: [1, 2, 3] }, // [[toc]]目录
        config: md => {
      // 插件
            // md.set({ breaks: true })
            // md.use(require('markdown-it-xxx'))
        }
    },
    themeConfig: {
     
        nav: [ // 导航栏
            {
     
                text: '主页',
                link: '/'
            }, {
     
                text: '菜单',
                items: [{
     
                    text: '普通菜单',
                    link: '/'
                }, {
     
                    text: '分组菜单',
                    items: [{
     
                        text: 'test1',
                        link: '/test1'
                    }, {
     
                        text: 'test2',
                        link: '/test2'
                    }]
                }]
            }, {
     
                text: '访问主页',
                link: 'http://www.csxiaoyao.com'
            }
        ],
        // 侧边栏
        sidebar: [
            '/test1',
            ['/test1', '链接到test1'],
            {
     
                title: '链接到test2',
                collapsable: false,
                children: [
                    '/test1',
                    '/test2',
                ]
            }
        ],
        // 展开所有标题层级
        displayAllHeaders: false,
        // 激活标题链接
        activeHeaderLinks: true, // false 可以提高性能
        // 搜索
        search: true,
        searchMaxSuggestions: 10,
        // 更新时间戳 git
        lastUpdated: 'Last Updated', // string | boolean
        // serviceWorker
        serviceWorker: {
     
            updatePopup: true, // 弹窗提示更新 Boolean | Object, 默认值是 undefined
            // 如果设置为 true, 默认的文本配置将是: 
            updatePopup: {
      
               message: "有内容更新", 
               buttonText: "更新" 
            }
        },
        // 假定 GitHub，也可以是一个完整的 GitLab URL
        repo: 'csxiaoyaojianxian/JavaScriptStudy',
        // 自定义项目仓库链接文字，默认根据 `themeConfig.repo` 中的 URL 来自动匹配是 "GitHub"/"GitLab"/"Bitbucket" 中的哪个，如果不设置时是 "Source"
        repoLabel: '访问仓库',
        // 以下为可选的 "Edit this page" 链接选项，如果你的文档和项目位于不同仓库：
        docsRepo: 'vuejs/vuepress',
        // 如果你的文档不在仓库的根目录下：
        docsDir: 'docs',
        // 如果你的文档在某个特定的分支（默认是 'master' 分支）：
        docsBranch: 'master',
        // 默认为 false，设置为 true 来启用
        editLinks: true,
        // 自定义编辑链接的文本。默认是 "Edit this page"
        editLinkText: '修改此页'
    }
}