1 安装gitbook
npm i gitbook-cli -g
2 初始化gitbook项目
新建一个项目目录,终端执行以下命令
gitbook init
初始化过程遇到以下问题。
问题1:
xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance
检查了一下,本地没有安装Xcode,可以在appstore中,搜索xcode安装。
问题2:
TypeError: cb.apply is not a function
详细错误如下:
/data/soft/nodejs/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287 if (cb) cb.apply(this, arguments) TypeError: cb.apply is not a function at /data/soft/nodejs/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287:18 at FSReqCallback.oncomplete (fs.js:169:5)
打开polyfills.js文件,找到这个函数
function statFix (orig) { if (!orig) return orig // Older versions of Node erroneously returned signed integers for // uid + gid. return function (target, cb) { return orig.call(fs, target, function (er, stats) { if (!stats) return cb.apply(this, arguments) if (stats.uid < 0) stats.uid += 0x100000000 if (stats.gid < 0) stats.gid += 0x100000000 if (cb) cb.apply(this, arguments) }) } }
在第62-64行调用了这个函数
// fs.stat = statFix(fs.stat) // fs.fstat = statFix(fs.fstat) // fs.lstat = statFix(fs.lstat)
把这三行代码注释掉就解决报错了。
注释掉之后,重新执行初始化,成功创建项目。
初始化完成后,在执行目录中生成README.md 和 SUMMARY.md 两个文件。
3 打包GitBook项目
gitbook build
本地构建不运行服务。
打包完成后,打包文件默认输出到 _book/目录,在项目根目录中。
4 运行GitBook服务
gitbook serve
本地构建运行服务。
执行后,可通过浏览器访问 http://localhost:4000 实时预览。
5 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
6 GitBook目录结构
- GitBook _book - README.md - SUMMARY.md - book.json - GLOSSARY.md - LANGS.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 一样是手动创建但是可选的.
7 book.json配置文件说明
title:网站标题
author:网站作者
description:网站功能描述
language:网站使用语言
styles:网站额外配置的样式表
plugins:网站使用的插件
pluginsConfig:网站使用的插件的额外配
示例:
{ "title": "这里是标题", "author": "这里是作者", "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": "username", "repo": "blog", "type": "star", "count": true, "size": "small" }, { "user": "username", "width": "160", "type": "follow", "count": true, "size": "small" } ] }, "donate": { "button": "打赏", "wechatText": "微信打赏", "wechat": "***.jpg" }, "tbfed-pagefooter": { "copyright":"Copyright Description", "modify_label": "该文件修订时间:", "modify_format": "YYYY-MM-DD HH:mm:ss" }, "baidu-tongji": { "token": "XXXXX" }, "anchor-navigation-ex": { "showLevel": false } } }
待续:
GitBook支持构建多语言文档,实现站点国际化
GitBook安装评论插件,实现可留言的文档系统