GitBook简明教程
[toc]
安装
安装gitbook命令行工具
npm install gitbook-cli -g
使用
gitbook init初始化目录- 生成两个必要的文件
README.md(介绍)和SUMMARY.md(结构) - 编辑
SUMMARY.md后可以再次执行该命令生成文件结构(2级)
- 生成两个必要的文件
gitbook build编译为HTML- 生成一个
_book文件夹,包含静态HTML文件 - 文件名不能包含括号不然无法识别解析
- 生成一个
gitbook serve启动本地web服务器- http://localhost:4000 预览电子书效果
SUMMARY.md可以通过使用 标题 或者 水平分割线 将 GitBook 分为几个不同的部分,如下所示：
# Summary
### Part I
* [Introduction](README.md)
* [Writing is nice](part1/writing.md)
* [GitBook is nice](part1/gitbook.md)
### Part II
* [We love feedback](part2/feedback_please.md)
* [Better tools for authors](part2/better_tools.md)
---
* [Last part without title](part3/title.md)
编辑器建议
vscode 中安装插件Markdown Preview Enhanced所见即所得
GitBook.com
GitBook.com 是一个围绕 gitbook 发行书籍的社区,于 2014 年初创,GitBook.com 提供免费和付费的服务,而且免费账户就可以享受诸多服务,包括：
- 1 本私有书籍
- 托管不限数量的公开书籍
- 售卖不限数量的书籍,并分享 80% 的书籍收入
- 不限数量的协作者
- 免费的在线书籍编辑器
Git管理
GitBook.com 上的每本书都使用Git来管理,使用Git提交到书籍的远程项目,当然,提交前,最好在本地使用 gitbook 预览效果.
git clone https://git.gitbook.com/testuser/test.git克隆git commit -m ".."提交git push推送发布
书籍地址https://git.gitbook.com/test_user/test
配置书籍
GitBook.com上的书籍,进入书籍的属性页面 可以设置,书籍主题,GitHub集成,绑定域名.
GitHub上创建项目
书籍导入到GitHub上的项目
书籍目录下
git remote add github https://github.com/testuser/test.gitgit push -u github master
git push 命令中的 -u 表示将本地 master 分支的上游分支设置为github/master.
git push 将推送到 github 上,而非原来的 https://git.gitbook.com/testuser/test.git
与此同时原来gitbook上的项目应该会同步拉取/显示github上的更新.
绑定域名
除了可以使用类似http://test_user.gitbooks.io/test/content/index.html地址访问用户的书籍外,还可以为每本书另外绑定域名.
- 只能绑定一个合法的域名,不能是域名下的某个地址.
- 域名服务商处为域名添加
CNAME记录,指向到该书籍地址. - 可以使用
nslookup test.testuser.cn来验证是否解析成功. - 书籍内容类似
http://content.test.test_user.cn
个性化配置
gitbook 在编译书籍的时候会读取书籍源码顶层目录中的 book.js 或者 book.json.
{
"title": "iPanda",
"author": "Mainvooid",
"description": "万古长空，一朝风月",
"language": "zh-hans",
"gitbook": "3.2.3",
"styles": {
"website": "styles/website.css",
"ebook": "styles/ebook.css",
"pdf": "styles/pdf.css",
"mobi": "styles/mobi.css",
"epub": "styles/epub.css"
},
"structure": {
"readme": "README.md"
},
"links": {
"sidebar": {
"Github": "https://github.com/Mainvooid"
}
},
"plugins": [
"-sharing",
"-search",
"-lunr",
"search-pro",
"highlight",
"livereload",
"splitter",
"expandable-chapters-small",
"anchors",
"github",
"github-buttons",
"donate",
"sharing-plus",
"anchor-navigation-ex",
"favicon",
"tbfed-pagefooter",
"disqus",
"code",
"todos",
"advanced-emoji",
"klipse",
"flexible-alerts",
"site-count",
"accordion",
"hide-element",
"codesnippet",
"atoc"
],
"pluginsConfig": {
"site-count": {
"host": "https://mainvooid.github.io/"
},
"hide-element": {
"elements": [".gitbook-link"]
},
"flexible-alerts": {
"style": "flat",
"note": {
"label": "Note"
},
"tip": {
"label": "Tip"
},
"warning": {
"label": "Warning"
},
"danger": {
"label": "Attention"
}
},
"code": {
"copyButtons": true
},
"github": {
"url": "https://github.com/Mainvooid"
},
"github-buttons": {
"buttons": [
{
"user": "Mainvooid",
"repo": "Mainvooid.github.io",
"type": "star",
"size": "small",
"count": true
}
]
},
"donate": {
"wechat": "./assets/donate-wechat.png",
"alipay": "./assets/donate-alipay.jpg",
"title": "",
"button": "赞赏",
"alipayText": "支付宝打赏",
"wechatText": "微信打赏"
},
"disqus": {
"shortName": "ipandar"
},
"sharing": {
"douban": false,
"facebook": false,
"google": false,
"hatenaBookmark": false,
"instapaper": false,
"line": false,
"linkedin": false,
"messenger": false,
"pocket": false,
"qq": false,
"qzone": false,
"stumbleupon": false,
"twitter": true,
"viber": false,
"vk": false,
"weibo": true,
"whatsapp": false,
"all": [
"douban",
"facebook",
"google",
"hatenaBookmark",
"instapaper",
"line",
"linkedin",
"messenger",
"qq",
"qzone",
"stumbleupon",
"twitter",
"viber",
"vk",
"weibo",
"whatsapp"
]
},
"anchor-navigation-ex": {
"showLevel": false
},
"favicon": {
"shortcut": "./assets/favicon.jpg",
"bookmark": "./assets/favicon.jpg",
"appleTouch": "./assets/favicon.jpg",
"appleTouchMore": {
"120x120": "./assets/favicon.jpg",
"180x180": "./assets/favicon.jpg"
}
},
"tbfed-pagefooter": {
"copyright":"guobao.v@gmail.com ",
"modify_label": "最后编辑时间:",
"modify_format": "YYYY-MM-DD HH:mm:ss"
}
}
}(插件accordion+codesnippet可以实现上面那样从文件读取代码并折叠)
插件
可以在npmjs.com 上搜索gitbook-plugin来查找插件
GitBook默认带有 5 个插件,highlight、search、sharing、font-settings、livereload,如果要去除自带的插件, 可以在插件名称前面加"-",比如：
"plugins": [
"-search"
]
如果要配置使用的插件可以在book.json文件中加入即可,比如我们添加plugin-github,我们在book.json中加入配置如下即可：
{
"plugins": [ "github" ],
"pluginsConfig": {
"github": {
"url": "https://github.com/your/repo"
}
}
}
然后在终端输入 gitbook install ./ 安装配置中的插件.
手动安装方式为npm install gitbook-plugin-插件名
livereload自带实时重载ComScore是一个彩色主题,默认的 gitbook 主题是黑白的,也就是标题和正文都是黑色的,而 ComScore 可以为各级标题添加不同的颜色,更容易区分各级标题.Disqus是一个非常流行的为网站集成评论系统的工具,同样,gitbook 也可以集成 disqus 以便可以和读者交流.- 首先,需要在 disqus 上注册一个账号,然后添加一个 website,这会获得一个关键字,然后在集成时配置这个关键字即可.
npm install gitbook-plugin-disqus -g- 修改 book.json 配置文件,添加插件的配置内容：
{ "plugins": ["disqus"], "pluginsConfig": { "disqus": { "shortName": "获取的唯一key" } } }
gitbook不支持[toc],好在有插件可以曲线救国。- 在
book.json中添加插件atoc,运行gitbook install - 安装完成后，在使用
[toc]命令的地方使用<!-- XXX -->代替(XXX替换为toc)。即可自动生成文档目录。 - 还有一种补充方式是安装
anchor-navigation-ex添加Toc到侧边悬浮导航以及回到顶部按钮."pluginsConfig": { "anchor-navigation-ex": { "showLevel": false } }
- 在
expandable-chapters-small可扩展导航章节search-pro高级搜索(支持中文) 在使用此插件之前，需要将默认的search和lunr插件去掉.splitter侧边栏宽度可调节sharing-plus分享当前页面，比默认的 sharing 插件多了一些分享方式. "all"中代表点击分享符号可以显示出来的.tbfed-pagefooter页面添加页脚(简单的)page-copyright页面页脚版权(内容多)klipse嵌入类似IDE的功能,嵌入一块功能，可在代码段中实时交互,即输入代码 > 执行结果donate打赏插件 文章最下面的按钮，点击可弹出图片change_girls可自动切换的背景图片，time单位秒,url只能使用绝对地址{ "plugins":["change_girls"], "pluginsConfig": { "change_girls" : { "time" : 10, "urls" : [ "girlUrl1", "girlUrl2",..."" ] } } }code为代码块添加行号和复制按钮"pluginsConfig": { "code": { "copyButtons": true } }codesnippet从文件导入代码并显示(url链接的文件也可以e.g. https://raw.githubusercontent.com/..cpp)//指定语言 指定显示的文件行数 {@ codesnippet "./assets/test.cpp", lines="2:5",language="cpp" @}{@ endcodesnippet @}
#include
using namespace std;
int main(){
return 0;
}todos添加checkbox功能- write some articles
- drink a cup of tea
advanced-emoji支持Emoji表情
klipse嵌入一块功能，可在代码段中实时交互，即输入代码 > 执行结果
- klipse源码 , klipse插件地址
- 插件支持的语言
eval-js for javascript eval-clojure for clojurescript eval-scheme for scheme eval-ruby for ruby eval-python for python ctrl+enter执行```eval-python print [x + 1 for x in range(10)] ```eval-pythonprint [x + 1 for x in range(10)]eval-jsvar x = 1; x + Math.random();eval-sqlCREATE TABLE play (game, points, day); INSERT INTO play VALUES ("go", 500, "monday"), ("go", 300, "tuesday"), ("chess", 1250, "tuesday"); SELECT * FROM play;
flexible-alerts块增强，4级提示卡片
[!NOTE|style:flat][!NOTE|style:flat] 测试
[!TIP|style:flat][!TIP|style:flat] 测试
[!WARNING|style:flat][!WARNING|style:flat] 测试
[!DANGER|style:flat][!DANGER|style:flat] 测试
[!NOTE|style:callout][!NOTE|style:callout] 测试
[!TIP|style:callout][!TIP|style:callout] 测试
[!WARNING|style:callout][!WARNING|style:callout] 测试
[!DANGER|style:callout][!DANGER|style:callout] 测试
site-count文章左上角显示阅读量计数accordion折叠模块,放最外层不可缩进。可嵌套，内部可以加代码块，引用，标题等%accordion%标题%accordion% //需要空一行 任意内容 //需要空一行 %/accordion%spoiler给片段覆盖一层黑色蒙版 刮刮乐{@s%}Hello World.{@ends%} //@改为%hide-element可以隐藏不想看到的元素，比如导航栏中Published by GitBook"pluginsConfig": { "hide-element": { "elements": [".gitbook-link"] } }
参考：GitBook插件整理
发布到 GitHub Pages
由于 gitbook 书籍可以本地构建出静态HTML格式,所以可以直接将构建好的书籍直接放到GitHub Pages中托管,之后可以通过如下地址访问书籍：
<username>.github.io/<project>
原仓库子目录部署
直接在项目设置的pages设定下面选择默认构建,并设置分支为master,目录为_book.
gitbook build在_book子目录下生成静态文件git push origin master推送整个项目到远程
使用actions workflow自动部署
github pages的默认构建方式是jekyll,使用某些gitbook插件时可能会构建失败，从而导致无法继续部署.比如使用codesnippet时无法成功构建.这个时候可以通过自定义静态文件构建的方式完成部署.actions文档
在master分支下新建.github/workflows/static.yml(在push事件触发时执行静态文件部署工作流--检出子目录_book并上传到静态页面服务器.)
gitbook build在_book子目录下生成静态文件git push origin master推送整个项目到远程
# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages
on:
# Runs on pushes targeting the default branch
push:
branches: ["master"]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow one concurrent deployment
concurrency:
group: "pages"
cancel-in-progress: true
jobs:
# Single deploy job since we're just deploying
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Setup Pages
uses: actions/configure-pages@v2
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
# Upload static HTML repository
path: './_book'
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1推送到分支部署
推送到分支意义不大,actions也可以完成推送到分支部署的任务,这边仅保留方案记录.
只需要4步即可将静态HTML文件发布到gh-pages分支:
gitbook build在_book子目录下生成静态文件git subtree split --rejoin --prefix=_book --branch gh-pages拆分子目录到新的分支gh-pagesgit subtree push --squash --prefix=_book origin gh-pages推送到远程仓库- 在该github仓库的
settings->pages中做下图所示修改
然后直接通过<username>.github.io访问就可以访问到gh-pages,即_book目录下构建的静态文件
维护这个库的所有命令都在仓库根目录的Makefile里面定义了，可以参考