安装 GitBook

安装 GitBook

  1. 安装 nodejs

  2. 安装 gitbook-cli

     npm install gitbook-cli -g

    安装成功后，执行 gitbook -V 查看版本信息。此命令会默认同时安装 GitBook。

  3. 初始化 GitBook 文件夹，会生成两个必要的文件 README.md 和 SUMMARY.md

     gitbook init

  4. 启动 GitBook 服务, GitBook 默认启动一个 4000 端口用于预览。

     gitbook serve

    以上访问 http://localhost:4000 可看到效果。 另一种预览方式，运行 gitbook build 命令会在书籍的文件夹中生成一个 _book 文件夹, 里面的内容即为生成的 html 文件,这可以只生成网页而不开启服务器。

    如需指定端口

     gitbook serve --port=8081

    GitBook 文件说明

  5. SUMMARY.md : 定制书籍的章节结构和顺序。

  6. README.md : 书的介绍文字，如前言、简介，在章节中也可做为章节的简介。

  7. book.json : 存放配置信息

SUMMARY.md

一个SUMMARY.md 的范例

// SUMMARY.md

# Summary
* [Introduction](README.md)
* Part I
    * [从命令行进行测试](Chapter1/CommandLine.md)
    * [Monkey](Chapter1/Monkey.md)
    * [monkeyrunner 参考](Chapter1/MonkeyrunnerReference.md)
        * [概览](Chapter1/MonkeyrunnerSummary.md)
        * [MonkeyDevice](Chapter1/MonkeyDevice.md)
        * [MonkeyImage](Chapter1/MonkeyImage.md)
* Part II
    * [Introduction](Chapter2/c1.md)
    * [Introduction](Chapter2/c2.md)

README.md

书的首页，主要是介绍性的文字，如前言、简介。

book.json

book.json 用于存放配置信息。

{
    "title": "dev manual",
    "author": "RunAtWorld",
    "description": "it is for learning.",
    "language": "zh-hans",
    "gitbook": "3.2.3",
    "styles": {
        "website": "./styles/website.css"
    },
    "structure": {
        "readme": "README.md"
    },
    "links": {
        "sidebar": {
            "开发手册": "https://runatworld.gitbook.io"
        }
    },
    "plugins": [
        "sharing",
        "splitter",
        "expandable-chapters-small",
        "anchors",
        "github",
        "github-buttons",
        "donate",
        "sharing-plus",
        "anchor-navigation-ex",
        "favicon"
    ],
    "pluginsConfig": {
        "github": {
            "url": "https://github.com/RunAtWorld"
        },
        "github-buttons": {
            "buttons": [{
                "user": "RunAtWorld",
                "repo": "runatworld.github.io",
                "type": "star",
                "size": "small",
                "count": true
                }
            ]
        },
        "donate": {
            "alipay": "./source/images/donate.png",
            "title": "",
            "button": "赞赏",
            "alipayText": "支付宝"
        },
        "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": false,
            "viber": false,
            "vk": false,
            "weibo": false,
            "whatsapp": false,
            "all": [
                "google", "facebook", "weibo", "twitter",
                "qq", "qzone", "linkedin", "pocket"
            ]
        },
        "anchor-navigation-ex": {
            "showLevel": false
        },
        "favicon":{
            "shortcut": "./source/images/favicon.jpg",
            "bookmark": "./source/images/favicon.jpg",
            "appleTouch": "./source/images/apple-touch-icon.jpg",
            "appleTouchMore": {
                "120x120": "./source/images/apple-touch-icon.jpg",
                "180x180": "./source/images/apple-touch-icon.jpg"
            }
        }
    }
}

  • title: 本书标题

  • author: 本书作者

  • description: 本书描述

  • language: 本书语言，中文设置 "zh-hans" 即可

  • gitbook: 指定使用的 GitBook 版本

  • styles: 自定义页面样式

  • structure: 指定 Readme、Summary、Glossary 和 Languages 对应的文件名

  • links: 在左侧导航栏添加链接信息

  • plugins: 配置使用的插件

  • pluginsConfig: 配置插件的属性

GitBook 插件

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

以上命令相当于 gitbook install ./

如果要指定插件的版本可以使用 plugin@0.3.1 ，因为一些插件可能不会随着 GitBook 版本的升级而升级。

各种用途插件

  1. 折叠目录

    增加 折叠目录 的插件，需要在 book.json 内增加下面代码:

     {
     "plugins": ["expandable-chapters-small"],
     "pluginsConfig": {
         "expandable-chapters-small":{}
     }
 }

    了解更多插件

与 github 关联

参考

  1. gitbook 官网

  2. GitBook 插件

  3. Gitbook 的使用和常用插件

  4. 一个基于gitbook快速写电子书的模版，支持html、pdf、docx、epub、mobi

  5. 用github做出第一本书

  6. 知乎GitBook 使用教程

PreviousgitbookNext输出PDF

Last updated