Gitbook 学习使用笔记
Gitbook 是写作的一个好工具,结合 git 可以极大的方便写作和分享的过程。这里记录下 我使用 Gitbook 的一些经验,希望能对你有点帮助。
配置 Gitbook 环境
$ sudo apt remove --purge nodejs npm
$ sudo apt clean
$ sudo apt autoclean
$ sudo apt install -f
$ sudo apt autoremove
$ curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
$ sudo apt-get install -y nodejs
$ curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
$ sudo apt-get update && sudo apt-get install yarn
安装 Gitbook
$ sudo npm -g install gitbook-cli
初始化一个的 Gitbook 目录
$ mkdir mybook
$ cd mybook
$ gitbook init
建立 book.json
文件
{
"title": "张三个人网站",
"description": "生活工作科研中的点滴记录",
"author": "张三",
"language": "zh-hans",
"gitbook": "3.2.3",
"root": ".",
"plugins": [
"-highlight",
"prism",
"prism-themes",
"mathjax",
"image-captions",
"fontsettings",
"expandable-chapters-small",
"simple-page-toc",
"copy-code-button"
],
"pluginsConfig": {
"fontSettings": {
"size": 1
},
"simple-page-toc": {
"maxDepth": 3,
"skipFirstH1": true
},
"prism": {
"css": [
"prismjs/themes/prism-tomorrow.css"
]
}
}
}
在 mybook
目录下建立 .gitignore
文件:
*~
_book
.DS_Store
node_modules
建立 git 仓库
$ git init
$ git add .
$ git commit -m 'init repro'
扩展
用 Gitbook 开发的网站可以托管在 Github 上,可以借助 gitment 给网站页面增加评论功 能,gitment 本质是上用网站仓库的 issue 页面功能。在每个网站页面后面加入下面的代 码,即可开通评论功能。
<div id="container"></div>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/theme-next/theme-next-gitment@1/default.css"/>
<script src="https://cdn.jsdelivr.net/gh/theme-next/theme-next-gitment@1/gitment.browser.js"></script>
<script>
var gitment = new Gitment({
id: 'window.location.pathname', // 每个页面建立一个 issue 页面
owner: '你的 Github 用户名',
repo: 'Github 分配给你的网站名,也是你的网站仓库名,格式为 “用户名.github.io"',
oauth: {
client_id: '',
client_secret: '',
},
})
gitment.render('container')
</script>
注意要为你的网站 用户名.github.io
申请 OAuth 授权,申请方法见
这里
插件
安装合适的插件可以完善和丰富 Gitbook 的功能,更方便做出好看的书籍页面。
Copy-code-button
{
"plugins": ["copy-code-button"]
}
Simple-page-toc
自动生成本页的目录, book.json
中的设置如下:
{
"plugins" : [
"simple-page-toc"
],
"pluginsConfig": {
"simple-page-toc": {
"maxDepth": 3,
"skipFirstH1": true
}
}
}
使用方法: 在需要生成目录的地方加上 `
`。
Expandable-chapters-small
plugins: ["expandable-chapters-small"]
Graph
首先安装 function-plot,
npm i d3@3 function-plot
在 Gitbook 文档中用如下的方式使用:
{% graph %}
{
"title": "1/x * cos(1/x)",
"grid": true,
"xAxis": {
"domain": [0.01, 1]
},
"yAxis": {
"domain": [-100, 100]
},
"data": [{
"fn": "1/x * cos(1/x)",
"closed": true
}]
}
{% endgraph %}
显示效果如下:
{% graph %}
{
"title": "1/x * cos(1/x)",
"grid": true,
"xAxis": {
"domain": [0.01, 1]
},
"yAxis": {
"domain": [-100, 100]
},
"data": [{
"fn": "1/x * cos(1/x)",
"closed": true
}]
}
{% endgraph %}
遇到的错误与解决办法
- Error: /home/why/work/GitBook/whysite/node_modules/function-plot: Appears to be a git repo or submodule.
进入文件目录,删除 .git
文件夹, 再调用 gibook install
即可。
- Ubuntu 18.04 LTS Server npm : Depends: node-gyp (>= 0.10.9) but it is not going to be installed [duplicate] https://askubuntu.com/questions/1057737/ubuntu-18-04-lts-server-npm-depends-node-gyp-0-10-9-but-it-is-not-going
https://github.com/nodesource/distributions#debinstall
- PluginError: Error with plugin "mathjax": Cannot find module 'mathjax/unpacked/MathJax'
npm install mathjax@2.7.6