【GitBook常用用法】

原创于 2025-03-05 14:51:08 发布 · 1.3k 阅读

30 ·

本内容遵循CC 4.0 BY-SA版权协议

标签

#GitBook

开源专栏收录该内容

2 篇文章

订阅专栏

GitBook常用用法

1 gitbook基本用法
2 gitbook配置文件和插件

【博客首发于微信公众号《漫谈芯片与编程》，欢迎大家关注，多谢大家】

1 gitbook基本用法

gitbook基本用法，基本上主要是两步：
1.使用gitbook init 初始化书籍目录
2.使用gitbook serve来编译书籍；

1.1 gitbook init

1 创建目录结构

主动创建README.md和SUMMARY.md两个文件；这两个文件是必须文件；

README.md：是对书籍的简单介绍；

# README.md

This is the README file powered by GitBook

SUMMARY.md

# SUMMARY

* [Chapter1](chapter1/README.md)
  * [Section1.1](chapter1/section1.1.md)
  * [Section1.2](chapter1/section1.2.md)
* [Chapter2](chapter2/README.md)

两外demo:

# Summary

* [Introduction](README.md)
* [基本安装](howtouse/README.md)
   * [Node.js安装](howtouse/nodejsinstall.md)
   * [Gitbook安装](howtouse/gitbookinstall.md)
   * [Gitbook命令行速览](howtouse/gitbookcli.md)
* [图书项目结构](book/README.md)
   * [README.md 与 SUMMARY编写](book/file.md)
   * [目录初始化](book/prjinit.md)
* [图书输出](output/README.md)
   * [输出为静态网站](output/outfile.md)
   * [输出PDF](output/pdfandebook.md)
* [发布](publish/README.md)
   * [发布到Github Pages](publish/gitpages.md)
* [结束](end/README.md)

执行gitbook init，会按照SUMMARY里面的目录结构来进行创建；

1.2 gitbook serve来编译书籍

gitbook serve: 命令实际上会首先调用 gitbook build 编译书籍，完成以后会打开一个 web 服务器，监听在本地的 4000 端口。

在浏览器上打开http://localhost:4000

gitbook在创建好书籍目录结构后，即可以编辑内容，文件编写遵循markdown语法;在修改过程中，需要重新gitbook serve来重新编译生效；

2 gitbook配置文件和插件

gitbook-plugin-X: 插件
gitbook-theme-X: 主题

2.1 gitbook配置文件

Gitbook 使用了可选的 JSON 格式的配置文件来自定义书籍和文档的配置，这些配置选项通过 Gitbook项目根目录下的 book.json 文件来进行配置和指定。
JSON的语法格式跟简单：来自于JS的对象标记语法：

数据在名称/值对中
数据由逗号分离
花括号容纳对象
方括号容纳数组
book.json里面配置说明

2.1.1 基础配置

{
    "root":".",
    "author":"JiangMing",
    "title":"JiangMing Gitbook",
    "language":"zh-hans",
    "description":"This is gitbook",
    "isbn":"000-0-00-000000-0",
    "direction":"ltr",
    "gitbook":">=3.2.3"
}

2.1.2 structure结构配置

除了 root 变量，你可以通过 structure 告诉Gitbook [Readme]，[Summary]，[Glossary]，[Languages]的文件名(而不是使用默认名称，如README.md)。这些文件必须在您的书籍项目的根目录。不接受像 doc/README.md 这样的子目录路径。
不用再额外配置

todo

{
    "structure":{
        "readme":"README.md",
        "summary":"SUMMARY.md",
        "glossary":"GLOSSARY.md",
        "languages":"LANGS.md" // 注意默认已经配置，在 gitbook—V3.2.3版本配置会报错, 可忽略
    }
}

2.1.3 variables变量配置

在内容里面直接使用变量来代替其中的值；
示例：使用双括号{{book.blog}}来替换实际的值；

{
    "variables":{
        "blog":"https://blog.csdn.net/ming_97y"
    }
}

2.1.4 links链接导航

通过 links 配置在左侧导航栏添加指定的链接导航，如：添加自己的博客链接，GIthub链接等等；

{
    "links":{
        "sidebar":{
            "Blog":"https://blog.csdn.net/ming_97y",
            "Github":"https://github.com/jiangminggithub"
        }
    }
}

2.1.5 styles自定义样式

通过 styles 配置这个选项用来自定义书本的 css 的.

{
    "styles": {
        "website": "styles/website.css",
        "ebook": "styles/ebook.css",
        "pdf": "styles/pdf.css",
        "mobi": "styles/mobi.css",
        "epub": "styles/epub.css"
    }
}

2.1.6 plugins插件列表

通过 plugins 配置gitbook需要的插件列表：

{
    "plugins": [
        "github",
        "splitter",
        ...
    ]
}

2.1.7 pluginsConfig 插件配置

通过插件配置可以配置插件列表plugins中对应插件的一些配置选项信息。

{
    "plugins": ["github"],
    "pluginsConfig": {
        "github": {
            "url": "https://github.com"
        }
    }
}

2.1.8 pdf参数配置

PDF输出可以使用book.json中的 pdf 来进行配置：
在这里插入图片描述

2.2 gitbook常用插件

gitbook 还支持许多插件，可以直接从 NPM 上搜索 gitbook 的插件，gitbook 文档推荐插件的命名方式为：
第三方插件使用方法：

在配置文件 book.json 中添加 “plugins” 和 “pluginConfig” 字段，然后执行 gitbook install 来进行插件的安装
使用NPM安装 npm install gitbook-plugin-插件名进行安装
从源码 GitHub 地址中下载，放到 node_modules 文件夹里安装
推荐使用配置文件 book.json 配置的方法进行安装

后续详细介绍使用到的插件…

【REF】
1.https://www.chengweiyang.cn/gitbook/github-pages/README.html
2.http://yu66.vip/doc/other/003-gitbook%E5%85%A5%E9%97%A8%E6%95%99%E7%A8%8B.html
3.https://jiangminggithub.github.io/gitbook/4-config.html
4.http://www.zhaowenyu.com/gitbook-doc/manual/gitbook-quick-start.html