GitBook教程指南

版权声明:本文为博主原创文章,未经博主允许不得转载的哦=。= https://blog.csdn.net/qq_15602635/article/details/82156630

工欲善其事必先利其器

前言

在V2EX上看到有讨论markdown工具的帖子,许多人推荐了Typora,简约美观。而我一直比较喜欢Gitbook。Gitbook有几个优点:

  • 使用Git,方便存储、回退、协作等
  • 轻松导出多种格式,如html、pdf等
  • 有书籍列表,方便管理
  • 有众多插件

安装

npm install -g gitbook-cli

检查是否安装成功 gitbook -V

  • 安装gitbook editor
    进入官网下载安装,Mac也可以直接使用命令brew cask install gitbook-editor

创建书籍

安装完环境以后,先试着创建一本书。先进入准备写书的目录,然后输入命令。

$ gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished

这样就在当前目录创建了一本书。SUMMARY.md是书籍目录,README.md是书籍简介。 也可以指定目录创建书籍,如下。

gitbook init bookname

bookname是书籍名,这样会先创建一个bookname的目录,然后再生成SUMMARY.mdREADME.md

预览书籍

创建完书籍以后,一起来预览一下。在终端输入命令:

gitbook serve

在浏览器中查看http://localhost:4000进行预览。

在书籍目录下,可以看到多了一个_book目录,里面就是网页的内容。

$ ls
README.md   SUMMARY.md  _book
$ ls _book
gitbook index.html  search_index.json

_book推送到服务器,就是一个静态网站。

Github部署

  • 先在Github创建一个书籍的工程
  • 将本地工程推送到Github的工程,在书籍目录下输入命令:
git init
git add .
git commit -m "first commit"
git remote add origin https://github.com/PortgasAce/book.git
git push -u origin master

将上面的url换成自己工程仓库即可,执行完后刷新Github可以看到本地的书籍被推送到远程。

  • 使用Git Pages服务

GitPages是一个将github仓库作为网页展示的服务。使用它可以将书籍变为在线浏览。
启用GitPages服务有两个选项,一个是将master分支作为展示分支,另一个是将master分支的docs目录作为展示目录。

由于我们将书籍的markdown源文件推送到了master分支,所以选择docs目录作为GitPages服务的展示目录会更好。接下来,我们将之前产生在_book目录的文件生成到docs目录。进入书籍目录,输入命令

gitbook build . ./docs

如果出现Error: ENOENT: no such file or directory, stat '/Users/portgas/Desktop/test/docs/gitbook/gitbook-plugin-sharing/buttons.js' 可以忽略。

然后推送到远程仓库,打开GitPages服务。

book.json的配置与个性化

模板

{
"author": "Portgas <portgas.ly@foxmail.com>",
"description": "This is a sample book created by gitbook",
"extension": null,
"generator": "site",
"links": {
"sharing": {
"all": null,
"facebook": null,
"google": null,
"twitter": null,
"weibo": null
},
"sidebar": {
"100斤的博客": "http://blog.fiftykg.com"
}
},
"output": null,
"plugins": [],
"title": "Sample GitBook",
"variables": {}
}

设置默认夜间模式

{
"pluginsConfig": {
"fontsettings": {
"theme": "night"
}
}
}

插件

添加插件

book.json plugins数据中添加即可,例如

"plugins": [
"sitemap"
]

添加完成后,需要在书籍目录执行命令gitbook install .

删除自带插件

GitBook有插件官网,默认带有 5 个插件,highlight、search、sharing、font-settings、livereload,如果要去除自带的插件, 可以在插件名称前面加-,如:

"plugins": [
"-search"
]

推荐插件

如果有好用的插件请推荐给我!

SEO

  • sitemap
  • 待补充

常用命令汇总

  • gitbook init bookname 创建书名为bookname的书
  • gitbook serve 本地预览
  • gitbook build src dest 编译src目录,生成到dest目录
  • gitbook help 查看命令帮助
阅读更多
换一批

没有更多推荐了,返回首页