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 即可。

https://github.com/nodesource/distributions#debinstall

  • PluginError: Error with plugin "mathjax": Cannot find module 'mathjax/unpacked/MathJax'
npm install mathjax@2.7.6

参考文献

  1. http://gitbook.zhangjikai.com/plugins.html

results matching ""

    No results matching ""