本地Gitbook安装和使用（windows下）

一、快速开始

  1. 安装Nodejs

    教程：https://www.jianshu.com/p/cc26e5d0f10f

  2. 安装gitbook

     npm install gitbook-cli -g

  3. 初始化一个目录

     gitbook init

  4. 编写SUMMARY.md目录文件

     * [简介](README.md)
 * [第一章]()
     * [第一节](demo.md) 
 * [第二章](demo1.md)

  5. 创建book.json文件，写入如下配置：

    {
        "gitbook": ">=3.2.3",
        "language": "zh-hans",
        "title": "书名",
        "description": "文档描述",
        "structure": {
            "readme": "README.md",
            "summary": "SUMMARY.md"
        },
        "links": {
            "gitbook": false,
            "sharing": {
                "google": false,
                "facebook": false,
                "twitter": false,
                "all": false
            }
        },
        "plugins": [
            "-sharing",
            "-lunr", "-search", "search-plus",
            "anchor-navigation-ex-toc",
            "tbfed-pagefooter",
            "copy-code-button"
        ],
        "pluginsConfig":{
            "anchor-navigation-ex-toc" : {
                "showLevel":true,
                "multipleH1":false,
                "mode":"float",
                "float":{
                    "floatIcon": "fa fa-navicon",
                    "showLevelIcon": false,
                    "level1Icon": "fa fa-hand-o-right",
                    "level2Icon": "fa fa-hand-o-right",
                    "level3Icon": "fa fa-hand-o-right"
                }
            },
            "tbfed-pagefooter": {
                "copyright":"&copy 2018 www.vchar.top",
                "modify_label": "本文档更新于：",
                "modify_format": "YYYY-MM-DD HH:mm"
            }
        }
    }

  1. 运行命令测试是否成功

     gitbook serve

浏览器访问：http://localhost:4000

  1. 导出离线html

     gitbook build

最新版本的离线html无法跳转；需要修改生成目录下的gitbook的theme.js文件；搜索if(m)for(n.handler 将其改为if(false)for(n.handler即可

一个gitbook教程写的很不错的地址： http://gitbook.zhangjikai.com/

二、安装

安装gitbook

要在本地安装gitbook需要先安装nodejs(安装教程)

在windows的cmd命令行工具中执行如下命令安装gitbook

npm install gitbook-cli -g

gitbook-cli 是 GitBook 的一个命令行工具。它将自动安装所需版本的 GitBook 来构建一本书。

gitbook导出PDF相关安装

  • 安装PDF支持插件

      npm install ebook-convert -g

  • 安装calibre软件

软件下载地址 https://calibre-ebook.com/download;安装成功后配置环境变量path中将calibre安装目录配置上

  • 导出pdf

      gitbook pdf

三、常用命令

初始化

在cmd命令行工具中切换到一个想创建书的目录下，执行如下命令：

gitbook init

执行成功后会在该目录下生成如下文件，这个2个文件是必须要的。

README.md   #这是一个简介文档，内容需要自己编写
SUMMARY.md  #这个是文档目录结构文档，需要自己编写

  • SUMMARY.md目录编写格式

      * [简介](README.md)
  * [第一章]()
      * [第一节](demo.md) 
  * [第二章](demo1.md)

生成离线HTML页面

gitbook build

创建gitbook的目录应当如下：

├── book.json
├── README.md
├── SUMMARY.md
├── directory-1
|   ├── README.md
|   └── something.md

执行成功后会将生成的离线页面和相关资源放到_book目录下

启动服务

gitbook serve

启动成功后可以通过http://localhost:4000访问预览

列出 gitbook 所有的命令

gitbook help

生成时指定gitbook的版本, 本地没有会先下载

gitbook build --gitbook=3.2.2

列出本地所有的gitbook版本

gitbook ls

列出远程可用的gitbook版本

gitbook ls-remote

更新到gitbook的最新版本

gitbook update

卸载对应的gitbook版本

gitbook uninstall 2.0.1

输出错误信息

gitbook builid --debug

四、常用插件

记录一些实用的插件, 如果要指定插件的版本可以使用 plugin@1.2.1。本文记录的插件在 windows 下都是可以正常工作的。这里只是列举了一部分插件，如果有其它的需求，可以到 插件官网https://plugins.gitbook.com/ 去搜索相关插件。

支持中文搜索：search-plus

支持中文搜索, 需要将默认的 search 和 lunr 插件去掉。

{
    "plugins": ["-lunr", "-search", "search-plus"]
}

侧边悬浮导航\顶部:anchor-navigation-ex-toc

添加Toc到侧边悬浮导航以及回到顶部按钮。

插件引入

"plugins": [
        "anchor-navigation-ex-toc"
    ]

可用配置参数

"pluginsConfig": {
    "anchor-navigation-ex": {
        "showLevel": true,  #是否自动分级，即添加序号
        "associatedWithSummary": true,
        "printLog": false,  #是否显示日志
        "multipleH1": true, #是否有多个H1标题
        "mode": "float",
        "showGoTop":true,
        "float": {
            "floatIcon": "fa fa-navicon", # 原样式：fa-navicon
            "showLevelIcon": false,
            "level1Icon": "fa fa-hand-o-right",
            "level2Icon": "fa fa-hand-o-right",
            "level3Icon": "fa fa-hand-o-right"
        },
        "pageTop": {
            "showLevelIcon": false,
            "level1Icon": "fa fa-hand-o-right",
            "level2Icon": "fa fa-hand-o-right",
            "level3Icon": "fa fa-hand-o-right"
        }
    }
}

tbfed-pagefooter

为页面添加页脚

"plugins": [
    "tbfed-pagefooter"
],
"pluginsConfig": {
    "tbfed-pagefooter": {
        "copyright":"&copy 2018 www.xx.com",
        "modify_label": "本文档修订时间：",
        "modify_format": "YYYY-MM-DD HH:mm:ss"
    }
}

复制的按钮: copy-code-button

为代码块添加复制的按钮。

{
    "plugins": ["copy-code-button"]
}

多个版本: versions-select

添加版本选择的下拉菜单，针对文档有多个版本的情况

"plugins": [ "versions-select" ]

"pluginsConfig":{
    "versions": {
            "options": [
                {
                    "value": "https://www.gitbook.com",
                    "text": "v1.0"
                },
                {
                    "value": "https://www.gitbook.com",
                    "text": "v2.0"
                }
            ]
        }
}

anchors

添加 Github 风格的锚点样式

"plugins" : [ "anchors" ]

五、 bookjson

默认样式book.json配置文件

{
    "gitbook": ">=3.2.3",
    "language": "zh-hans",
    "title": "书名",
    "description": "文档描述",
    "structure": {
        "readme": "README.md",
        "summary": "SUMMARY.md"
    },
    "links": {
        "gitbook": false,
        "sharing": {
            "google": false,
            "facebook": false,
            "twitter": false,
            "all": false
        }
    },
    "plugins": [
        "-sharing",
        "-lunr", "-search", "search-plus",
        "anchor-navigation-ex-toc",
        "tbfed-pagefooter",
        "copy-code-button",
        "versions-select"
    ],
    "pluginsConfig":{
        "anchor-navigation-ex-toc" : {
            "showLevel":true,
            "multipleH1":false,
            "mode":"float",
            "float":{
                "floatIcon": "fa fa-navicon",
                "showLevelIcon": false,
                "level1Icon": "fa fa-hand-o-right",
                "level2Icon": "fa fa-hand-o-right",
                "level3Icon": "fa fa-hand-o-right"
            }
        },
        "tbfed-pagefooter": {
            "copyright":"&copy 2018 www.vchar.top",
            "modify_label": "本文档更新于：",
            "modify_format": "YYYY-MM-DD HH:mm"
        },
        "versions": {
                "options": [
                    {
                        "value": "https://gitbook.com",
                        "text": "v1.0"
                    },
                    {
                        "value": "https://gitbook.com",
                        "text": "v2.0"
                    }
                ]
            }
    }
}

效果图如下：

image

theme-api API文档主题

{
    "plugins": ["theme-api"],
    "pluginsConfig": {
        "theme-api": {
            "theme": "dark"
        }
    }
}

模板

{
    "gitbook": ">=3.2.3",
    "language": "zh-hans",
    "title": "书名",
    "description": "文档描述",
    "structure": {
        "readme": "README.md",
        "summary": "SUMMARY.md"
    },
    "links": {
        "gitbook": false,
        "sharing": {
            "google": false,
            "facebook": false,
            "twitter": false,
            "all":false
        }
    },
    "plugins": [
        "-sharing",
        "-lunr", "-search", "search-plus",
        "anchor-navigation-ex-toc",
        "tbfed-pagefooter",
        "copy-code-button",
        "versions-select",
        "theme-api"
    ],
    "pluginsConfig":{
        "anchor-navigation-ex-toc" : {
            "showLevel":true,
            "multipleH1":false,
            "mode":"float",
            "float":{
                "floatIcon": "fa fa-navicon",
                "showLevelIcon": false,
                "level1Icon": "fa fa-hand-o-right",
                "level2Icon": "fa fa-hand-o-right",
                "level3Icon": "fa fa-hand-o-right"
            }
        },
        "tbfed-pagefooter": {
            "copyright":"&copy 2018 www.vchar.top",
            "modify_label": "本文档更新于：",
            "modify_format": "YYYY-MM-DD HH:mm"
        },
        "versions": {
            "options": [
                {
                    "value": "https://gitbook.com",
                    "text": "v1.0"
                },
                {
                    "value": "https://gitbook.com",
                    "text": "v2.0"
                }
            ]
        },
        "theme-api":{
            "theme": "dark",
            "languages": [
                {
                    "lang": "js",
                    "name": "JavaScript",
                    "default": true
                },
                {
                    "lang": "java",
                    "name": "Java"
                }
            ]
        }
    }
}

API文档的语法

定义方法
{% method %}

打印
展示 JavaScript 和 Java 如何输出信息

{% sample lang="js" %} 这里演示 JavaScript 如何输出信息到控制台

console.log('Hello World');
{% sample lang="java" %} 这里演示 Java 如何输出信息到控制台

System.out.println("Hello World");
{% common %} 这里是 JavaScript 和 Java 共同的信息

{% endmethod %}

{% method %}

定义变量
这里演示 JavaScript 和 Java 如何定义变量

{% sample lang="js" %} 这里演示 JavaScript 如何定义变量：

var i = 0;
var j = "a";
var k = new function() {

}
{% sample lang="java" %} 这里演示 Java 如何定义变量

int i = 0;
String j = "a";
Object o = new Object();
{% endmethod %}

效果图如下：


最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
平台声明：文章内容（如有图片或视频亦包括在内）由作者上传并发布，文章内容仅代表作者本人观点，简书系信息发布平台，仅提供信息存储服务。

推荐阅读更多精彩内容