手把手教你使用 GitBook
一、简介
GitBook 是一个支持用 MarkDown 编写文档的软件,支持输出 HTML、PDF、eBook 格式文档。作为开发者我们一般会用它来写一些技术和接口文档。
GitBook 官网:https://www.gitbook.com
二、安装
1. 安装 Node.js
GitBook 是基于 Node.js 的命令行工具,需先下载安装 Node.js,检测是否安装成功:
$ node -v
v6.9.1
2. 安装 GitBook
使用 npm 安装 GitBook,命令如下:
$ npm install -g gitbook-cli
检测是否安装成功:
$ gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3
三、使用
1. 初始化
新建目录 book,在该目录下执行如下命令进行初始化:
$ gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished
该命令将会生成 README.md
和 SUMMARY.md
两个文件。其中 README.md
是对文档的简单介绍,可以用来作为封面,SUMMARY.md
是文档的目录结构。
也可以自己预先定义好 SUMMARY.md 中的目录结构,然后再用 init 命令初始化,程序将会根据我们的目录结构生成目录和文件,目录结构示例:
# Summary
* [Introduction](README.md)
* [Chapter1](chapter1/README.md)
* [Section1.1](chapter1/section1.1.md)
* [Section1.2](chapter1/section1.2.md)
* [Chapter2](chapter2/README.md)
2. 生成并预览
book 目录下执行如下命令,将会生成 HTML 文件并提供预览地址:
$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...
info: 7 plugins are installed
info: loading plugin "livereload"... OK
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 1 pages
info: found 0 asset files
info: >> generation finished with success in 1.0s !
Starting server ...
Serving book on http://localhost:4000
在浏览器中打开 http://localhost:4000
即可看到初始化的文档。
如果只需生成 HTML 文件执行 build 命令即可,命令如下:
$ gitbook build
如果需要生成 PDF 文件,由于依赖 ebook-convert,需要安装 Calibre,安装配置完成后,执行如下命令即可:
$ gitbook pdf
3. 编辑器
现在支持实时预览的 markdown 编辑器有很多,可以根据自己的喜好选择,此处仅做推荐:
- 官方编辑器 GitBook Editor
- PhpStorm(不要问我为什么,我不会告诉你我是 PHP 程序猿)
- Sublime Text(其实我写 MD 文档都不用预览,所以没给它装插件,龇牙)
四、配置
通过配置 book.json 中的参数,我们可以配置文档的很多信息,比如标题、侧边栏、插件等。
一个简单的 book.json 文件如下:
{
"title": "GitBook 使用教程",
"author": "Yanlong Ma <json_vip@163.com>",
"description": "GitBook 使用教程 - 马燕龙个人博客",
"generator": "site",
"links": {
"sidebar": {
"马燕龙个人博客": "http://www.mayanlong.com"
}
}
}
下面介绍的插件也需要用到该配置。
五、插件
1. 自带插件
GitBook 默认带有五个插件:highlight、search、sharing、fontsettings、livereload。如果要去除自带的插件,可以在插件名称前面加”-“,如下:
"plugins": ["-search"]
2. 命名规范
GitBook 还支持许多插件,可以从 NPM 上搜索 GitBook 的插件,GitBook 推荐插件的命名方式如下,所以可以通过以下两种方式来搜索 GitBook 的插件或者主题:
gitbook-plugin-X: 插件
gitbook-theme-X: 主题
3. 安装插件
下面介绍如何安装 gitbook-plugin-prism 插件,在 NPM 搜索该插件,插件主页链接为 https://www.npmjs.com/package/gitbook-plugin-prism。
首先安装该插件,命令如下:
$ npm i gitbook-plugin-prism
然后在 book.json 中添加该插件,同时禁用默认的 highlight,配置如下:
{
"plugins": ["prism", "-highlight"]
}
可以根据自己的喜好,配置不同的主题:
"pluginsConfig": {
"prism": {
"css": [
"prismjs/themes/prism-solarizedlight.css"
]
}
}
本文首发于马燕龙个人博客,欢迎分享,转载请标明出处。
马燕龙个人博客:http://www.mayanlong.com
马燕龙个人微博:http://weibo.com/imayanlong
马燕龙Github主页:https://github.com/yanlongma
手把手教你使用 GitBook的更多相关文章
- 手把手教你做个人 app
我们都知道,开发一个app很大程度依赖服务端:服务端提供接口数据,然后我们展示:另外,开发一个app,还需要美工协助切图.没了接口,没了美工,app似乎只能做成单机版或工具类app,真的是这样的吗?先 ...
- 手把手教从零开始在GitHub上使用Hexo搭建博客教程(四)-使用Travis自动部署Hexo(2)
前言 前面一篇文章介绍了Travis自动部署Hexo的常规使用教程,也是个人比较推荐的方法. 前文最后也提到了在Windows系统中可能会有一些小问题,为了在Windows系统中也可以实现使用Trav ...
- 手把手教从零开始在GitHub上使用Hexo搭建博客教程(三)-使用Travis自动部署Hexo(1)
前言 前面两篇文章介绍了在github上使用hexo搭建博客的基本环境和hexo相关参数设置等. 基于目前,博客基本上是可以完美运行了. 但是,有一点是不太好,就是源码同步问题,如果在不同的电脑上写文 ...
- 手把手教从零开始在GitHub上使用Hexo搭建博客教程(二)-Hexo参数设置
前言 前文手把手教从零开始在GitHub上使用Hexo搭建博客教程(一)-附GitHub注册及配置介绍了github注册.git相关设置以及hexo基本操作. 本文主要介绍一下hexo的常用参数设置. ...
- 手把手教从零开始在GitHub上使用Hexo搭建博客教程(一)-附GitHub注册及配置
前言 有朋友问了我关于博客系统搭建相关的问题,由于是做开发相关的工作,我给他推荐的是使用github的gh-pages服务搭建个人博客. 推荐理由: 免费:github提供gh-pages服务是免费的 ...
- UWP Jenkins + NuGet + MSBuild 手把手教你做自动UWP Build 和 App store包
背景 项目上需要做UWP的自动安装包,在以前的公司接触的是TFS来做自动build. 公司要求用Jenkins来做,别笑话我,之前还真不晓得这个东西. 会的同学请看一下指出错误,不会的同学请先自行脑补 ...
- 推荐!手把手教你使用Git
推荐!手把手教你使用Git 原文出处: 涂根华的博客 http://blog.jobbole.com/78960/ 一:Git是什么? Git是目前世界上最先进的分布式版本控制系统. 二:SVN与 ...
- 手把手教你写Sublime中的Snippet
手把手教你写Sublime中的Snippet Sublime Text号称最性感的编辑器, 并且越来越多人使用, 美观, 高效 关于如何使用Sublime text可以参考我的另一篇文章, 相信你会喜 ...
- 手把手教你调试Linux C++ 代码(一步到位包含静态库和动态库调试)
手把手教你调试Linux C++ 代码 软件调试本身就是一项相对复杂的活动,他不仅要求调试者有着清晰的思路,而且对调试者本身的技能也有很高的要求.Windows下Visual Studio为我们做了很 ...
随机推荐
- mongdb 慢查询
查看mongodb慢查询 赶紧打开服务器爸爸,开慢查询,看下耗时500ms以上的都是些啥: db.setProfilingLevel(2,500) 看下最近的10条具体的慢查询指令: db.syste ...
- 本机添加多个git仓库账号
我们可能会需要在一台电脑上以不同的github账户去使用git,这时就需要去解决如何管理本机上的多个ssh key的问题了. 生成新ssh key 如果我们电脑上已经存在了一个ssh key,那么我们 ...
- php -- instanceof、class_exists、insterface_exists、method_exists、get_class、get_parent_class
class_exists:类是否存在 在创建对象之前判断类是否存在,如果不存在就应该先加载类,再创建对象,容错. interface_exists:接口是否存在 method_exists:方法是否存 ...
- 【BZOJ】1005: [HNOI2008]明明的烦恼(prufer编码+特殊的技巧)
http://www.lydsy.com/JudgeOnline/problem.php?id=1005 这里讲得挺清楚的:http://www.cnblogs.com/zhj5chengfeng/p ...
- 【BZOJ】1645: [Usaco2007 Open]City Horizon 城市地平线(线段树+特殊的技巧)
http://www.lydsy.com/JudgeOnline/problem.php?id=1645 这题的方法很奇妙啊...一开始我打了一个“离散”后的线段树.............果然爆了. ...
- 多线程编程(三)--创建线程之Thread VS Runnable
前面写过一篇基础的创建多线程的博文: 那么本篇博文主要来对照一下这两种创建线程的差别. 继承Thread类: 还拿上篇博客的样例来说: 四个线程各自卖各自的票,说明四个线程之间没有共享,是独立的线程. ...
- 去除 \ufeff
语言:python 编程工具:pycharm 硬件环境:win10 64位 读取文件过程中发现一个问题:已有记事本文件(非空),转码 UTF-8,复制到pycharm中,在开始位置打印结果会出现 \ ...
- C语言逻辑运算符
现在假设有这样一种情况,我们的软件比较特殊,要求使用者必须成年,并且成绩大于等于60,该怎么办呢? 或许你会想到使用嵌套的 if 语句,类似下面这样的代码: #include <stdio.h& ...
- 用DX9画三角形,三个顶点要求
用DX9画三角形,三个顶点的顺序有要求吗下面是全部代码,在 InitVB 函数中被注释掉的数组是我写的,没注释掉的是书上的代码,经过试验我的坐标不能显示出图形,而书上的坐标可以,这是为什么? #i ...
- Objective-C代码学习大纲(2)
2011-05-11 14:06 佚名 otierney 字号:T | T 本文为台湾出版的<Objective-C学习大纲>的翻译文档,系统介绍了Objective-C代码,很多名词为台 ...