GitBook 提供以下功能。
GitBook 是一个文档编辑工具。它的功能类似金山的 WPS,微软的 Office 中的 Word 文档编辑工具。它可以用来写文档、建表格、插图片、生成 pdf 。虽然这些功能不一定有 WPS、Office 做得好,但是它可以用文档生成一个网站,让更多的人了解到你书写的内容。从此,不再为共享文档给他人后,如何时时同步而烦恼。实例效果如下:
GitBook 官网注册登录后,可在线创建、编辑和发布文档。线下提供离线编辑工具 GitBook Editor。但是本文档主要讲解的是 ,如何利用 GitBook 的命令行工具 gitbook-cli 来创建、预览及发布文档。
安装 NodeJs 是因为我们要使用其提供的 npm 包管理工具来下载安装 gitbook-cli
。从 NodeJs 官网 下载最新版本安装即可(版本要求 V4.0.0 及以上)。
运行以下命令进行安装
npm install gitbook-cli -g
首先新建如下目录结构
README.md 和 SUMMARY.md 是两个必须文件。
- README.md: 是对书籍的简单介绍
鼎盛云开放平台 H5 接口文档
# Summary
* [Introduction](README.md)
* [1、接口规则](chapter1/README.md)
* [1.1、协议规则](chapter1/section1.1.md)
* [1.2、公共参数](chapter1/section1.2.md)
* [1.3、其它说明](chapter1/section1.3.md)
* [1.3.1、其它说明](chapter1/section1.3.1.md)
* [2、用户](chapter2/README.md)
* [2.1、手机号查询用户注册状态](chapter2/section2.1.md)
* [2.2、用户注册-短信下发](chapter2/section2.2.md)
* [2.3、用户注册-短信验证](chapter2/section2.3.md)
* [2.4、验证交易密码](chapter2/section2.4.md)
* [2.5、是否关联身份信息-手机号](chapter2/section2.5.md)
* [2.6、设置账单日](chapter2/section2.6.md)
注意星号”*” 后面有个空格,忽略此会直接导致文档生成失败。
创建完这两个文件后,在文档根目录运行一下命令,初始化项目(gitbook 会帮我们生成 SUMMARY.md 中的目录结构)
gitbook init
书籍目录结构创建完成以后,就可以使用命令 gitbook serve
来预览书籍了。打开浏览器,输入http://localhost:4000查看书籍效果。当然,文档的具体内容,就有待自己去添加了。建议使用 markdown 语法,这里为小白提供一个markdown 简单教程;
通过执行 gitbook build
命令,gitbook 会在根目录下面生成一个编译打包后的文件 _book
里面便是我们文档编译后生成的 html 网页。后面便是,通过 ngnix
托管,让其在互联网上可见。
词汇表文件,默认对应根目录下的 GLOSSARY.md
。该文件主要存储词汇信息,如果在其它页面中出现了该文件中的词汇,鼠标放在词汇上会给出词汇解释。
Glossary 文件的格式如下所示:
## API
接口说明文档
## Markdown
排版语言,程序员专属
这里是两个 ## 。
存放在根目录,记录文档项目的一些说明信息,及最后项目打包的配置信息。格式如下:
{
title:"文档名称",
author:"作者1;作者2",
description:"文档描述",
language:"使用的语言,英语、简体中国等",
gitbook:">=3.2.2", // gitbook 的版本
root:".",// 指定存放 GitBook 文件的根目录
links:"左侧边栏添加链接" ,
styles:"指定打包生成网页的样式",
plugins:"指定打包生成网页需要使用的插件",
pluginsConfig:"配置插件的属性",
}
GitBook 使用的语言,简体中文配置如下:
"language":"zh-hans"
在左侧导航栏添加链接信息
"links":{
"sidebar":{
"Home":"http://localhost:4000"
}
}
自定义页面样式,默认情况下各 generator 对应的 css 文件
"styles":{
"website":"styles/website.css",
"ebook":"styles/ebook.css",
"pdf":"styles/pdf.css",
"mobi":"styles/mobi.css",
"epub":"styles/epub.css",
}
配置使用的插件
"plugins":[
"disqus"
]
添加新插件之后,需要运行 gitbook installl
来安装新插件
GitBook 默认带有 5 个插件 highlight
,search
,sharing
,font-settings
,livereload
。如果要去除自带的插件,可以在插件名称前面加 -
如下:
"plugins":[
"-search"
]
更多可选插件,可在插件官网查看。常见插件使用
配置插件的属性
"pluginsConfig":{
"fontsettings":{
"theme":"sepia",
"family":"serif"
"size":1
}
}