之前一直使用 Hexo 撰写博客文章体验感非常好，参考 https://dreamhomes.top/，但是如果作为技术文档或者书籍由于个人选择的 Hexo 主题过于花哨不太符合学术作风 😢 ，因此想选择一个风格偏向于简单的文档 📚 或者书籍 📖 撰写工具。

vuepress 选择理由

之前略微使用过 Gitbook 体验感不错，因此第一想法是使用 gitbook 来撰写学术性文档，但是现在已经商业化了，遂需寻找其它替代品。

目前市面上主要的静态文档撰写工具包括：

当然还有其它的就不再列举，Hexo 已经用来写日常博客因此也不选择。

由于没有亲身体验总结下其它博主使用感受。下面列出每个工具的优缺点进行比较：

  • 配置 docsify >> gitbook = vuepress

    由于docsify不需要编译，他的配置比另外两个简单很多，而另外两个从文档而言配置也不复杂。

  • 阅读体验 gitbook > docsify = vuepress

    这里不讨论UI，只说阅读体验，gitbook可以调节背景字体大小等，阅读体验上更佳。

  • 界面 vuepress = docsify > gitbook

    主观感受，个人感觉 docsify 的界面有点小难看。

  • 性能 vuepress > docsify = gitbook

    单页预编译明显效率最高，多页与运行时编译相差不大。

  • 灵活性 vuepress > docsify >> gitbook

    由于vue的特点，灵活性方面十分优秀

  • 导出 gitbook

    只有gitbook带有导出PDF的功能，如果需要使用PDF做个备份的情况可以使用。

  • 搜索 gitbook > docsify > vuepress

    对于文档来说搜索虽说是一个功能模块，但却很重要，gitbook插件最多最佳，docsify默认的全文搜索挺不错的，vuepress默认只能搜索标题，全文需要引用第三方的工具

  • seo gitbook = vuepress >> docsify

综合以上信息我选择 vuepress ，理由是 gitbook 收费而且docsify 不支持搜索引擎 😂，当然还有 vuepress 支持很多特性。

vuepress 配置流程

安装

VuePress 需要 Node.js>= 8.6 和 yarn 包管理工具。

可以选择 npm 作为包管理工具。

  1. 创建目录并初始化

    1
    2
    3
    mkdir aiops-algorithms-book
    cd aiops-algorithms-book
    yarn init

  2. 安装 vuepress 本地依赖

    1
    yarn add -D vuepress

  3. 创建第一篇文档

    1
    mkdir docs && echo '# Hello VuePress' > docs/README.md

  4. package.json 中增加脚本配置

    1
    2
    3
    4
    "scripts": {
      "docs:dev": "vuepress dev docs",
      "docs:build": "vuepress build docs"
    }

  5. 本地启动服务

    1
    yarn docs:dev

接下来就可以在 http://localhost:8080/ 中查看文档效果了。

以上流程就完成了简单的 vuepress 配置过程，但这远远是不够的，例如需要添加目录结构、公式支持、部署等等。

基本配置

  1. 在 docs 下新建基础配置文件

    1
    mkdir .vuepress && cd .vuepress && touch config.js

    在 config.js 中配置站点信息：

    1
    2
    3
    4
    module.exports = {
        title: 'AIOps 智能运维算法手册',
        description: '专注于智能运维领域的算法分享和实践',
    }

  2. 设置首页、导航栏和侧边栏

    首页

    在 docs/README.md 中添加首页信息

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    ---
    home: true
    heroImage: https://cdn.jsdelivr.net/gh/dreamhomes/blog-image-bed@master/top/dreamhomes/butterflyblog/imgs/20210404130758.png
    heroText: AIOps 智能运维算法手册
    tagline: 专注于 AIOps 算法研究及其在工程实践中的应用
    actionText: 快速上手 →
    actionLink: /zh/guide/
    features:
    - title: 简洁至上
      details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
    - title: Vue驱动
      details: 享受 Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。
    - title: 高性能
      details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
    footer: MIT Licensed | Copyright © 2021-2021 沈梦家
    ---

    导航栏

    在 docs/.vuepress/config.js 中添加导航

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    // navbar: false, // 是否启用导航栏
    nav: [
        { text: '主页', link: '/' },
        { text: '关于', link: 'https://dreamhomes.top/' },
        {
            text: '语言',
            ariaLabel: 'Language',
            items: [
                { text: '中文', link: '/language/chinese/' },
                { text: '英文', link: '/language/japanese/' }
            ]
        }
    ]

    侧边栏

    在 docs/.vuepress/config.js 中添加侧边栏

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    sidebar: 'auto',
    // sidebar: {
    //     '/foo/': [
    //         '',     /* /foo/ */
    //         'one',  /* /foo/one.html */
    //         'two'   /* /foo/two.html */
    //     ],

    //     '/bar/': [
    //         '',      /* /bar/ */
    //         'three', /* /bar/three.html */
    //         'four'   /* /bar/four.html */
    //     ],

    //     // fallback
    //     '/': [
    //         '',        /* / */
    //         'contact', /* /contact.html */
    //         'about'    /* /about.html */
    //     ]
    // },

    其它配置参考：https://vuepress.vuejs.org/zh/theme/default-theme-config.html#%E9%A6%96%E9%A1%B5

    📢 注意：相对路径下最后需添加 /，否则跳转出现错误。

  3. 插件使用

    参考： vuepress 插件列表

    添加公式支持：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    // 安装 katex
    $ yarn add markdown-it-katex -D

    // 修改 config.js 配置
        markdown: {
            extendMarkdown: md => {
                md.set({
                    html: true
                })
                md.use(require('markdown-it-katex'))
            }
        },
        head: [
            ['link', {
                rel: 'stylesheet',
                href: 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.7.1/katex.min.css'
            }],
            ['link', {
                rel: "stylesheet",
                href: "https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/2.10.0/github-markdown.min.css"
            }]
        ]

部署 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run docs:build

# 进入生成的文件夹
cd docs/.vuepress/dist

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

# 添加 README.md 
touch README.md && echo "book address: [https://dreamhomes.top/aiops/](https://dreamhomes.top/aiops/)" > README.md

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

# 注意 📢 修改仓库地址
# 如果发布到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# 如果发布到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

cd -

执行脚本即可部署到对应仓库 github pages。

后续 CI/CD 参考：https://vuepress.vuejs.org/zh/guide/deploy.html#github-pages

目前的案例，后续补充：https://dreamhomes.top/aiops/