最近在重构项目,需要调研一下帮助文档。之前项目里面用的是 gitbook 也好多年了,觉得有点丑,想找个现代化一点的哈哈哈。但是时间有限,也是一顿百度,借鉴了许多,在这里就是稍微整理一下吧! 上来就找到了这个文章,看了下时间还不算太旧,里面说调研了 vuePress 和 gitbook ,我基本上也是按照这两个方向来的。
这片文章先说说 GitBook.
Base Demo
全局安装 gitbook cli 工具.
npm install gitbook-cli -g
然后检查 gitbook 有没有安装成功
gitbook -V
出现下面这样子就安装成功了
初始化书籍目录
gitbook init
README.md 是项目起来之后默认地址(/)指向的文件
SUMMARY.md 是目录
写文档
这里只粘出来目录结构和SUMMARY.md
# Summary
* [首页](README.md)
* [介绍](docs/introduct.md)
* [第一章](docs/chapter1/README.md)
* [第一节](docs/chapter1/section1.md)
运行
gitbook serve
打开浏览器 http://localhost:4000
基本 Demo 就完事了~
其他
多语言。
gitbook 支持多语言,在根目录下加一个 LANGS.md 文件加上支持的语言就行了,可以参考Learn Git这个地址。 然后这个时候进来之后就是这个页面,有点丑哈,这个插件gitbook-plugin-multilingual-index说是可以自定义多语言主页。
我没有尝试。也没有尝试能不能在页面上弄个下拉修改语言的方案,我现在就搁在左侧菜单里面了。
关于 GitBook 全文检索。
本来是因为 gitbook 画风不好看,所以才调研的帮助文档,结果在最后定好用 vuepress 之前,产品忽然间发现 vuepress 不能满足他们全文搜索的功能,所以最终方案用的还是 gitbook.然后我就下去看了一下gitbook 全文检索是怎么做的。
不管是 gitbook 默认的搜索还是增强的搜索,他们原理都一样。把这些文件整成一个大 json,然后用 jQuery
的 getJSON
去读文件,搜索,就拿上面的 demo 为例。打包之后生成了一个 search_index.json,里面的内容是这样的。
{"index":{"version":"0.5.12","fields":[{"name":"title","boost":10},{"name":"keywords","boost":15},{"name":"body","boost":1}],"ref":"url","documentStore":{"store":{"./":["首页"],"docs/introduct.html":["介绍"],"docs/chapter1/":["第一章"],"docs/chapter1/section1.html":["1","第一节"]},"length":4},"tokenStore":{"root":{"1":{"docs":{"docs/chapter1/section1.html":{"ref":"docs/chapter1/section1.html","tf":1}}},"docs":{},"首":{"docs":{},"页":{"docs":{"./":{"ref":"./","tf":11}}}},"介":{"docs":{},"绍":{"docs":{"docs/introduct.html":{"ref":"docs/introduct.html","tf":11}}}},"第":{"docs":{},"一":{"docs":{},"章":{"docs":{"docs/chapter1/":{"ref":"docs/chapter1/","tf":11}}},"节":{"docs":{"docs/chapter1/section1.html":{"ref":"docs/chapter1/section1.html","tf":10}}}}}},"length":5},"corpusTokens":["1","介绍","第一章","第一节","首页"],"pipeline":["stopWordFilter","stemmer"]},"store":{"./":{"url":"./","title":"首页","keywords":"","body":"首页\n"},"docs/introduct.html":{"url":"docs/introduct.html","title":"介绍","keywords":"","body":"介绍\n"},"docs/chapter1/":{"url":"docs/chapter1/","title":"第一章","keywords":"","body":"第一章\n"},"docs/chapter1/section1.html":{"url":"docs/chapter1/section1.html","title":"第一节","keywords":"","body":"1-1\n"}}}
然后我看了一下我们重构前项目里面这个大 json 文件有 15M 那么大
自定义配置
上面就是一个基础款,但是他基础款的东西直接拿过来好像不是很好用,比如说
- 搜索: 默认搜索是没有关键词高亮的,所以你可以禁用掉默认的搜索,改成
search-pro
- 分享: 默认的分享都是国外的一些网站,在国内不是很适用
还可以增强一下你写的文档,比如说
- 代码复制
- 回到顶部
- 目录展开收起
- 隐藏指定元素
我们可以通过配置文件实现一些自定义的配置,在根目录下新建book.json,就可以自定义配置了。
我的配置是这样滴
{
"title": "test",
"author": "test",
"description": "description",
"language": "zh-hans",
"plugins": [
"-highlight",
"copy-code-button",
"search-pro",
"-search",
"-lunr",
"splitter",
"-sharing",
"anchor-navigation-ex",
"expandable-chapters",
"back-to-top-button",
"splitter",
"hide-element"
],
"pluginsConfig": {
"anchor-navigation-ex": {
"showLevel": false,
"mode": "float",
"float": {
"floatIcon": "fa fa-navicon",
"showLevelIcon": false,
"level1Icon": "fa fa-hand-o-right",
"level2Icon": "fa fa-hand-o-right",
"level3Icon": "fa fa-hand-o-right"
},
"showGoTop": false
},
"hide-element": {
"elements": [".gitbook-link"]
}
}
}
更多配置可以参考这里
一般 gitbook 的插件都是叫 'gitbook-plugin',所以可以自行去 NPM 上找。
配置上加上插件要 重新的 gitbook install.这个命令贼拉慢,所以这个时候你直接用 npm 安装即可。忘记在哪里看到说是gitbook install 是把用到的插件全都安装一遍,所以慢什么的,但是这个我装的时候没留意。
部署优化
叫这个标题不是很准确,我就是给他加了一个 package.json 方便上到服务器打包部署。我把 gitbook 依赖放到了 package.json 里面,就不用全局安装 gitbook 了。
上 package.json
{
"name": "Test",
"version": "1.0.0",
"description": "description",
"main": "index.js",
"dependencies": {
"gitbook-cli": "^2.3.2",
"gitbook-plugin-anchor-navigation-ex": "^1.0.14",
"gitbook-plugin-back-to-top-button": "^0.1.4",
"gitbook-plugin-baidu-tongji": "^1.0.4",
"gitbook-plugin-collapsible-menu": "^1.0.3",
"gitbook-plugin-copy-code-button": "^0.0.2",
"gitbook-plugin-donate": "^1.0.2",
"gitbook-plugin-expandable-chapters": "^0.2.0",
"gitbook-plugin-github-buttons": "^3.0.0",
"gitbook-plugin-hide-element": "^0.0.4",
"gitbook-plugin-page-toc-button": "^0.1.1",
"gitbook-plugin-search-pro": "^2.0.2",
"gitbook-plugin-splitter": "^0.0.8",
"gitbook-plugin-tbfed-pagefooter": "^0.0.1"
},
"devDependencies": {},
"scripts": {
"start": "gitbook serve",
"build": "gitbook build"
},
"repository": {
"type": "git",
"url": "xxxxxx"
},
"keywords": [
"help"
],
"author": "Xu",
"license": "ISC"
}
参考链接:
- Leader 让我做 CMS 帮助中心的技术选型,我撸了 VuePress 和 GitBook,然后选择...
- ChengWei's Blogs
- gitbook使用及book.json详细配置
常见问题FAQ
- 免费下载或者VIP会员专享资源能否直接商用?
- 本站所有资源版权均属于原作者所有,这里所提供资源均只能用于参考学习用,请勿直接商用。若由于商用引起版权纠纷,一切责任均由使用者承担。更多说明请参考 VIP介绍。
- 提示下载完但解压或打开不了?
- 找不到素材资源介绍文章里的示例图片?
- 模板不会安装或需要功能定制以及二次开发?
发表评论
还没有评论,快来抢沙发吧!