Leader 让我做 CMS 帮助中心的技术选型,我撸了 VuePress 和 GitBook,然后选择...
天明夜尽 人气:6前言
因为自己平时经常写博客,也有博客网站,所以 Leader 叫我做一个 CMS
的帮助中心的技术选型,CMS
的帮助中心的功能:是通过文章来教用户如何使用我们的项目。
所以笔者要做一个静态网站的技术选型,笔者把网上流行的 VuePress
和 GitBook
两种方式都尝试了一下,并做了对比,这里写篇文章总结一下,顺便把自己的博客网站重作一便,哈哈。
1. VuePress
1.1 简介
VuePress 是 Vue
驱动的静态网站生成器。
简洁至上
以 Markdown
为中心的项目结构,以最少的配置帮助你专注于写作。
Vue 驱动
享受 Vue + webpack
的开发体验,可以在 Markdown
中使用 Vue
组件,又可以使用 Vue
来开发自定义主题。
高性能
VuePress
会为每个页面预渲染生成静态的 HTML
,同时,每个页面被加载的时候,将作为 SPA
运行。
1.2 效果
首页:
评论:
效果详情请看:https://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/templateshttps://img.qb5200.com/download-x/dev.html
: 用于开发环境的HTML
模板文件。docs/.vuepress/templates/ssr.html
: 构建时基于Vue SSR
的HTML
模板文件。docs/.vuepress/config.js
: 配置文件的入口文件,也可以是YML
或toml
。docs/.vuepress/enhanceApp.js
: 客户端应用的增强。
注意:
当你想要去自定义
templates/ssr.html
或templateshttps://img.qb5200.com/download-x/dev.html
时,最好基于 默认的模板文件 来修改,否则可能会导致构建出错。还有就是笔者的
templates/ssr.html
和templateshttps://img.qb5200.com/download-x/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@1https://img.qb5200.com/download-x/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 = ".https://img.qb5200.com/download-x/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 = ".https://img.qb5200.com/download-x/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 ./buildshttps://img.qb5200.com/download-x/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 ./buildshttps://img.qb5200.com/download-x/delComponents.js",
"docs:dev": "vuepress dev docs",
"build": "vuepress build docs",
"build:md": "node ./builds/addComponents.js && vuepress build docs && node ./buildshttps://img.qb5200.com/download-x/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/.vuepresshttps://img.qb5200.com/download-x/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 上。
- 访问自己的域名,比如笔者的:https://biaochenxuying.github.io/blog/ 。
详情移步 vuepress 官网 vuepress.vuejs.org。
2. GitBook
效果:
效果详情请看:http://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 © 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
、作者等。
源码地址: https://github.com/biaochenxuying/blog 。
其中 VuePress
和 GitBook
的示例代码都在 blog-gitbook
和 blog-vuepress
里面了。
这次需求的结果
令笔者吐血的是:花了 3 天搞的调研,最后 leader 没有采用
加载全部内容
- 猜你喜欢
- 用户评论