Leader 让我作 CMS 帮助中心的技术选型，我撸了 VuePress 和 GitBook，而后选择...

时间 2019-12-16

标签 leader cms 帮助中心技术选型 vuepress gitbook 而后选择栏目 CMS 繁體版

原文原文链接

前言

由于本身平时常常写博客，也有博客网站，因此 Leader 叫我作一个 CMS 的帮助中心的技术选型，CMS 的帮助中心的功能：是经过文章来教用户如何使用咱们的项目。css

因此笔者要作一个静态网站的技术选型，笔者把网上流行的 VuePress 和 GitBook 两种方式都尝试了一下，并作了对比，这里写篇文章总结一下，顺便把本身的博客网站重做一便，哈哈。html

优惠消息。前端

笔者以为每一个开发者都应该拥有本身的网站和服务器，这但是很酷的事情，学习 Linux、跑跑脚本、建站、搭博客啥的都行。vue

1. VuePress

1.1 简介

VuePress 是 Vue 驱动的静态网站生成器。node

简洁至上webpack

以 Markdown 为中心的项目结构，以最少的配置帮助你专一于写做。git

Vue 驱动github

享受 Vue + webpack 的开发体验，能够在 Markdown 中使用 Vue 组件，又可使用 Vue 来开发自定义主题。web

高性能npm

VuePress 会为每一个页面预渲染生成静态的 HTML，同时，每一个页面被加载的时候，将做为 SPA 运行。

1.2 效果

首页：

评论：

效果详情请看：biaochenxuying.github.io/blog/ 。

1.3 简单使用

像数 1, 2, 3 同样容易

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

# 建立项目目录
mkdir vuepress-starter && cd vuepress-starter

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

# 开始写做
vuepress dev .

# 构建静态文件
vuepress build .
复制代码

1.4 目录结构

VuePress 遵循 “约定优于配置” 的原则，推荐的目录结构以下：

├── docs
│   ├── .vuepress (可选的)
│   │   ├── components (可选的)
│   │   ├── theme (可选的)
│   │   │   └── Layout.vue
│   │   ├── public (可选的)
│   │   ├── styles (可选的)
│   │   │   ├── index.styl
│   │   │   └── palette.styl
│   │   ├── templates (可选的, 谨慎配置)
│   │   │   ├── dev.html
│   │   │   └── ssr.html
│   │   ├── config.js (可选的)
│   │   └── enhanceApp.js (可选的)
│   │ 
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json
复制代码

注意：请留意目录名的大写。

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: 客户端应用的加强。

注意：

当你想要去自定义 templates/ssr.html 或 templates/dev.html 时，最好基于默认的模板文件来修改，不然可能会致使构建出错。
还有就是笔者的 templates/ssr.html 和 templates/dev.html 是有添加以下这一行代码的：

<meta id="referrer" name="referrer" content="never" />
复制代码

由于笔者的图片都是存在简书上的，因此为了能够访问第三方图床的图片，才添加了这句代码，若是你的图片是存在本地的，去掉这句代码便可，至于具体缘由请看笔者写的文章：前端解决第三方图片防盗链的办法 - html referrer 访问图片资源403问题。

1.5 评论

评论功能用了 GitTalk。

1.5.1 申请一个 OAuth App

具体实践以下：

首先登陆你的 GitHub 帐号，而后点击进入Settings。

点击 OAuth Apps , Register a new application 或者 New OAuth App 。

输入信息。

应用信息说明：Client ID && Client Secret

建立成功有 Client ID 和 Client Secret ，保存下来，后面咱们会用到。

建立评论组件

Vuepress 默认 .vuepress / components 文件夹下的组件会全局注册，所以咱们建立一个 comment 组件。

gittalk.css 请点击这里

<template>
  <div class="gitalk-container">
    <div id="gitalk-container"></div>
  </div>
</template>
<script>
export default {
  name: 'comment',
  data() {
    return {};
  },
  mounted() {
    let body = document.querySelector('.gitalk-container');
    let script = document.createElement('script');
    script.src = 'https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.min.js';
    body.appendChild(script);
    script.onload = () => {
      const commentConfig = {
        clientID: '你的clientID',
        clientSecret: '你的clientSecret',
        repo: '你的仓库名称',
        owner: '你的用户名',
        // 这里接受一个数组，能够添加多个管理员，能够是你本身
        admin: ['管理用户名'],
        // id 用于当前页面的惟一标识，通常来说 pathname 足够了，
        // 可是若是你的 pathname 超过 50 个字符，GitHub 将不会成功建立 issue，此状况能够考虑给每一个页面生成 hash 值的方法.
        id: location.pathname,
        distractionFreeMode: false,
      };
      const gitalk = new Gitalk(commentConfig);
      gitalk.render('gitalk-container');
    };
  },
};
</script>
<style>
@import '../css/gittalk.css';
</style>
复制代码

使用评论组件

理论上，咱们在每一个 markdown 文件里直接加入这个组件便可，可是每次都添加有点麻烦，仍是让 node 来帮咱们吧

根目录建立 build 文件夹, 建立三个文件 addComponents.js, delComponents.js, findMarkdown.js, 分别代码以下：

// addComponents.js
const fs = require("fs");
const findMarkdown = require("./findMarkdown");
const rootDir = "./docs";

findMarkdown(rootDir, writeComponents);

function writeComponents(dir) {
    if (!/README/.test(dir)) {
        fs.appendFile(dir, `\n \n <comment/> \n `, err => {
            if (err) throw err;
            console.log(`add components to ${dir}`);
        });
    }
}
复制代码

// delComponents.js
const fs = require("fs");
const findMarkdown = require("./findMarkdown");
const rootDir = "./docs";

findMarkdown(rootDir, delComponents);

function delComponents(dir) {
    fs.readFile(dir, "utf-8", (err, content) => {
        if (err) throw err;

        fs.writeFile(
            dir,
            content.replace(/\n \n <comment\/> \n /g, ""),
            err => {
                if (err) throw err;
                console.log(`del components from ${dir}`);
            }
        );
    });
}
复制代码

// findMarkdown.js
const fs = require("fs");

function findMarkdown(dir, callback) {
    fs.readdir(dir, function(err, files) {
        if (err) throw err;
        files.forEach(fileName => {
            let innerDir = `${dir}/${fileName}`;
            if (fileName.indexOf(".") !== 0) {
                fs.stat(innerDir, function(err, stat) {
                    if (stat.isDirectory()) {
                        findMarkdown(innerDir, callback);
                    } else {
                        // 跳过readme 文件，固然你也能够自行修改
                        if (/\.md$/.test(fileName) && !/README/.test(fileName))
                            callback(innerDir);
                    }
                });
            }
        });
    });
}
module.exports = findMarkdown;
复制代码

修改 package.json 的 scripts, 先为每一个 md 文件添加组件，而后打包，最后再一一删除 markdown 中的 comment 组件。

"build": "node ./builds/addComponents.js && vuepress build docs && node ./builds/delComponents.js",
复制代码

笔者的项目里面是把添加了二条命令的，好比 npm run dev:md 和 npm run build:md 才是有评论组件的。

"scripts": {
    "dev": "vuepress dev docs",
    "dev:md": "node ./builds/addComponents.js && vuepress dev docs && node ./builds/delComponents.js",
    "docs:dev": "vuepress dev docs",
    "build": "vuepress build docs",
    "build:md": "node ./builds/addComponents.js && vuepress build docs && node ./builds/delComponents.js",
    "docs:build": "vuepress build docs",
    "delay": "bash delay.sh",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
复制代码

想要怎样的打包命令，本身修改就行。

注意：若是你的文章的评论要和 github 的 issues 的同步的话，还要在 issues 的 label 里添加相应的 pathname 和 gitalk，其中 pathname 就是评论组件里面的 location.pathname 。

好比个人：

1.6 部署到 Github pages

当咱们将文档写好后就到了咱们最关心的地方了，怎么将打包后的代码推送到远程仓库的 gh-pages 分支上。

建立一个deploy.sh

touch deploy.sh
复制代码

编写脚本

#!/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://<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 -

复制代码

设置 package.json

{
    "scripts": {
        "deploy": "bash deploy.sh"
      },
}
复制代码

发布

npm run deploy   // 便可自动构建部署到 github 上。
复制代码

访问本身的域名，好比笔者的：biaochenxuying.github.io/blog/ 。

详情移步 vuepress 官网 vuepress.vuejs.org。

2. GitBook

效果：

效果详情请看：biaochenxuying.cn:2021。

2.1 GitBook 经常使用指令

安装 GitBook：npm i gitbook-cli -g
初始化 GitBook 项目：gitbook init
安装 GitBook 依赖：gitbook install
开启 GitBook 服务：gitbook serve
打包 GitBook 项目：gitbook build
GitBook 命令行查看：gitbook -help
GitBook 版本查看：gitbook -V

2.2 简单上手

而后，咱们找个空文件夹，初始化一个 GitBook 项目。

gitbook init 初始化 README.md 和 SUMMARY.md 两个文件.
gitbook build 本地构建但不运行服务，默认输出到 _book/ 目录.
gitbook serve 本地构建并运行服务，默认访问 http://localhost:4000 实时预览.

- GitBook
 - README.md
 - SUMMARY.md
复制代码

README.md 是默认首页文件，至关于网站的首页 index.html ,通常是介绍文字或相关导航连接.
SUMMARY.md 是默认归纳文件，主要是根据该文件内容生成相应的目录结构，同 README.md 同样都是被 gitbook init 初始化默认建立的重要文件.
_book 是默认的输出目录，存放着原始 markdown 渲染完毕后的 html 文件，能够直接打包到服务器充当静态网站使用。通常是执行 gitbook build 或 gitbook serve 自动生成的.
book.json 是配置文件，用于个性化调整 gitbook 的相关配置，如定义电子书的标题、封面、做者等信息。虽然是手动建立但通常是必选的.
GLOSSARY.md 是默认的词汇表，主要说明专业词汇的详细解释，这样阅读到专业词汇时就会有相应提示信息，也是手动建立可是可选的.
LANGS.md 是默认的语言文件，用于国际化版本翻译和 GLOSSARY.md 同样是手动建立可是可选的.

book.json 的意思：

title：网站标题
author：网站做者
description：网站功能描述
language：网站使用语言
styles：网站额外配置的样式表
plugins：网站使用的插件
pluginsConfig：网站使用的插件的额外配

笔者的 book.json:

{
  "title": "夜尽天明的博客",
  "author": "biaochenxuying",
  "description": "大前端技术为主，读书笔记、随笔、理财为辅，作个终身学习者。",
  "language": "zh-hans",
  "plugins": [
    "-highlight",
    "copy-code-button",
    "search-pro",
    "-search",
    "-lunr",
    "expandable-chapters",
    "splitter",
    "-sharing",
    "github-buttons",
    "donate",
    "tbfed-pagefooter",
    "baidu-tongji",
    "anchor-navigation-ex"
  ],
  "pluginsConfig": {
    "github-buttons": {
      "buttons": [
        {
          "user": "biaochenxuying",
          "repo": "blog", 
          "type": "star",
          "count": true,
          "size": "small"
        }, 
        {
          "user": "biaochenxuying",
          "width": "160", 
          "type": "follow", 
          "count": true,
          "size": "small"
        }
      ]
    },
    "donate": {
      "button": "打赏",
      "wechatText": "微信打赏",
      "wechat": "https://camo.githubusercontent.com/ee094d402f957e5d656a399b9dc50ff8c010114e/68747470733a2f2f75706c6f61642d696d616765732e6a69616e7368752e696f2f75706c6f61645f696d616765732f31323839303831392d666661623762643234643038633030642e6a7065673f696d6167654d6f6772322f6175746f2d6f7269656e742f7374726970253743696d61676556696577322f322f772f31323430"
    },
    "tbfed-pagefooter": {
      "copyright":"Copyright &copy biaochenxuying.cn 2019",
      "modify_label": "该文件修订时间：",
      "modify_format": "YYYY-MM-DD HH:mm:ss"
    },
    "baidu-tongji": {
      "token": "XXXXX"
    },
    "anchor-navigation-ex": {
      "showLevel": false
    }
  }
}
复制代码

2.3 插件

插件的配置能够说是 GitBook 的核心。

详情能够看 GitBook - 快速打造可留言的博客，这里就不展开讲了。

3. VuePress VS GitBook

相同点

目前只支持 markdown 格式，图片、视频等静态资源能够保存在本地，或者保存到容许访问的第三方服务商（如七牛云）；
若是是 world 文档或者 html 格式，要转换成 md 格式才行。
找了几个 world 文档转换成 md 格式的工具，都很差用，特别是有原文档有图片的时候。

不一样点

GitBook 的配置成本很小，能够本地编辑，而后直接部署；GitBook 官方还有个在线编辑器，不过内容要存在 GitBook 的服务器上。
VuePress 的配置成本稍稍大一点，不过可使用 Vue 的语法与组件，定制化更自由一点，并且 VuePress 中编写 Vue 和平时同样，学习成本几乎为零，能够本地用 VsCode 编辑，而后直接命令行部署。

结论

都要用 markdown 语法来写文章，markdown 也就几个经常使用语法而已，很是简单上手。
非技术人员推荐用 GitBook，技术人员推荐用 VuePress，特别是前端技术人员。
我的更喜欢 VuePress 。

4. 项目源码

本文中使用 VuePress 和 GitBook 的搭建的完整示例代码都已经上传到 GitHub 上了，能够自行下载来用。

只要把其中的一些配置信息换成本身的就行，好比 仓库、Client ID && Client Secret、做者等。

源码地址： github.com/biaochenxuy… 。

其中 VuePress 和 GitBook 的示例代码都在 blog-gitbook 和 blog-vuepress 里面了。

此次需求的结果

令笔者吐血的是：花了 3 天搞的调研，最后 leader 没有采用 😭，仍是用回了功能很重的 wordpress。

由于非技术人员要用起来的话，学习成本是比较大的 😂，好比要学 markdown 语法、ide 编辑器、基本的打包命令、可能还要学 git ，而非技术人员编辑文档时，通常是用 wps 的 😂。

比较欣慰的是：笔者作完调研后，本身的博客网站也能用上了，哈哈。

最后

推荐阅读：GitHub 上能挖矿的神仙技巧 - 如何发现优秀开源项目，估计不少人都不知道的技巧，甚至不少高级工程师都不知道。

参考文章：为你的 VuePress 博客添加 GitTalk 评论