使用GitBook编写文档书籍
GitBook 是一个基于 Node.js 的命令行工具,可使用 Github/Git 和 Markdown 来制作精美的电子书。GitBook支持输出以下几种文档格式:
- 静态站点:GitBook默认输出该种格式
- PDF:需要安装gitbook-pdf依赖
- eBook:需要安装ebook-convert
GitBook可以用来写书、API文档、公共文档,企业手册,论文,研究报告等。
一、GitBook安装
在安装之前,我们还需要配置一下 nodejs 插件安装的下载镜像地址。因为默认的镜像地址在国外,需要翻墙才可以访问,因此我们需要设置国内的镜像地址。这里使用阿里巴巴的镜像地址 http://registry.npm.taobao.org 。使用下面的命令,进行配置。
npm config set registry http://registry.npm.taobao.org
1、NMP安装Gitbook
npm install gitbook -g
//安装命令
npm install -g gitbook-cli//卸载命令
npm uninstall -g gitbook
2、检验下是否安装成功
//显示gitbook以及gitbook-cli版本号
gitbook -V
二、基本使用
Gitbook需要2个基本文件:
README.md
SUMMARY.md
README.md是关于你的书的介绍,而SUMMARY.md中则包含了书的目录。我们还可以添加“book.json(电子书配置文件)”、“GLOSSARY.md(书尾词汇表)”以及“封面图片”等,默认文件树中没有这些,需要自行添加。
1. 生成图书目录结构
创建一个目录test, 使用gitbook init命令就可以在目录下生产这两个文件。一个SUMMARY.md文件的格式大致如下,每一行对应一个相应的文件。
# Summary* [Introduction](README.md)
* [第一章](chapter1/README.md)
* [第一节](chapter1/seciont1.md)
* [第二节](chapter1/section2.md)
* [第二章](chapter2/README.md)
* [第一节](chapter2/seciont1.md)
* [第二节](chapter2/section2.md)
* [结束](end/README.md)
执行 gitbook init 会根据 SUMMARY.md 目录生成对应的文件夹和 md 文件,每一个 md 文件对应每一章节,每一章节的内容在对应的 md 文件里编辑,你可以使用本地支持Markdown语法的编辑器编辑,例如Markdown Pad。
如果想要新增章节,可以在 SUMMARY.md 里面新增,然后执行 gitbook init 就会新增对应的 md 文件,原有文件不会变化;如果想要删除章节,在 SUMMARY.md 里面删除,然后执行 gitbook init 想要删除的 md 文件并不会删除,需要手动删除。
2. 生成图书
2.1 输出为静态网站
执行下面的命令
$ gitbook serve
然后浏览器中输入 http://localhost:4000 就可以预览生成的以网页形式组织的书籍。
这里你会发现,你在你的图书项目的目录中多了一个名为_book的文件目录,而这个目录中的文件,即是生成的静态网站内容。
使用build参数生成到指定目录
与直接预览生成的静态网站文件不一样的是,使用这个命令,你可以将内容输入到你所想要的目录中去:
$ mkdir /tmp/gitbook
$ gitbook build --output=/tmp/gitbook
文档写好以后,你可以把Gitbook源目录下面的所有文件都复制到你项目下(app_root/docs/api/gitbook_api_dir)。这样,你的项目就多了一份漂亮的文档。
2.2 输出为PDF
输出为PDF文件,需要先使用NPM安装上gitbook pdf:
$ sudo npm install gitbook-pdf -g
三、Gitbook的插件支持
新建book.json,可以做一些配置,比如标题,作者,指定readme文件,关闭分享链接等。
{"title": "gitbook tutorial","description": "Webpack 是当下最热门的前端资源模块化管理和打包工具,本书大部分内容翻译自 Webpack 官网。","structure": {"readme": "README.md"},"links": {"gitbook": false,"sharing": {"google": false,"facebook": false,"twitter": false,"all": false}},"plugins": ["disqus","advanced-emoji"],"pluginsConfig": {"disqus": {"shortName": "gitbookuse"}}
}
# 安装插件
$ gitbook install ./
gitbook命令
gitbook init //初始化目录文件
gitbook help //列出gitbook所有的命令
gitbook --help //输出gitbook-cli的帮助信息
gitbook build //生成静态网页
gitbook serve //生成静态网页并运行服务器
gitbook build --gitbook=2.0.1 //生成时指定gitbook的版本, 本地没有会先下载
gitbook ls //列出本地所有的gitbook版本
gitbook ls-remote //列出远程可用的gitbook版本
gitbook fetch 标签/版本号 //安装对应的gitbook版本
gitbook update //更新到gitbook的最新版本
gitbook uninstall 2.0.1 //卸载对应的gitbook版本
gitbook build --log=debug //指定log的级别
gitbook builid --debug //输出错误信息
四、托管到GitBook.com
1、注册 GitBook.com 账号
首先进入 GitBook.com 注册一个账号,并新建一个项目。在“Setting(设置)”页面获取到“Git URL(Git 链接)”,如下所示:
https://git.gitbook.com/charmingfst/mytest.git
2、使用Git上传电子书项目
在本地新建一个文件夹,并通过 Git 命令把刚才新建的远程项目抓取到本地,如下所示:
mkdir FirstBook
cd FirstBook
git init
git pull https://git.gitbook.com/charmingfst/mytest.git
然后把本地电子书项目“test”中的所有内容拷贝到刚才新建的文件夹中,如上面的“FirstBook”。然后使用 Git 命令把本地的项目上传到远程,如下所示:
git add -A
git commit -m "提交说明"
git remote add gitbook https://git.gitbook.com/charmingfst/mytest.git
git push -u gitbook master
git push 命令中的 -u 表示将本地 master 分支的上游分支设置为 github/master,下次直接使用git push命令即可。
最后,如果你不喜欢使用命令行,也可以使用GitBook可视化编辑器,GitBook Editor。
更多教程参看这里。
使用GitBook编写文档书籍相关推荐
- 编写文档_如何通过编写优质文档来使自己的未来快乐
编写文档 by Gabriele Cimato 加布里埃莱·西马托(Gabriele Cimato) 如何通过编写优质文档来使自己的未来快乐 (How to make your future self ...
- 插入公式_word2016编写文档 插入公式选项为暗,不能操作
问题: 用word2016版编写文档,需要插入公式时,发现 插入--公式 选项是暗的,不能操作. 原因: 因为调格式太复杂的问题,编辑文档时用了一个很久以前做好的模板(用word2013版制作的),而 ...
- 如何使用Markdown语言编写文档
目录 Markdown 语言简介 Markdown基础语法 一.标题 二.段落格式 1. 字体 2. 分隔线 3. 删除线 4. 下划线 5. 脚注 三.列表 1. 无序列表 2. 有序列表 3. 列 ...
- ArcGIS教程:对地理处理服务和任务编写文档
如果您希望尽可能多的人发现.了解和使用服务,至关重要的一点是为服务和任务编写文档. 良好的文档的编写从创建要发布的结果的工具开始.系统中的每个工具都具有项目描述,可通过在目录 窗口中右键单击工具并选择 ...
- 建议:为所有导出的API元素编写文档注释。
如果要想使一个API真正可用,就必须为其编写文档.传统意义上的API文档是手工生成的,所以保持文档与代码同步是一件很繁琐的事情.Java语言环境提供了一种被称为Javadoc的实用工具,从而使这项任务 ...
- 使用编辑器编写文档时出现前字吞后字的解决方法
编写文档时出现前字吞后字的原因 在使用Typora编写markdown文档时,发现修改文档时出现了前字吞后字的情况. 例如:我想写HELLO WORLD,但是写错了,想要修改一下,原本鼠标光标应该时这 ...
- GitBook 告别文档共享烦恼
GitBook GitBook 提供以下功能. 支持 markdown 语法 自动构建文档网站 丰富的插件来拓展网站,比如:搜索,代码高亮等 支持 git 进行文档项目管理 什么是 GitBook G ...
- asciidoc_使用AsciiDoc编写文档
asciidoc 我在一个月的午餐中编写" 学习Linux"时发现了AsciiDoc . AsciiDoc是一种用于编写书籍的非常详尽的标记语言-想想Markdown ,但是具有更 ...
- 终于有了任何程序员都能快速编写文档的工具!
李老板:小王,咱们马上要参加一个宇宙超级管理系统的投标,你组织人员写个竞标方案! 李老板:小王,那个宇宙超级管理系统咱们中标了,你这几天写个需求文档马上安排开发吧! 李老板:小王,宇宙超级管理系统已经 ...
最新文章
- 常用MySQL函数存储过程_解析MySQL存储过程、常用函数代码
- tf.keras.layers.Reshape 示例
- .exe已停止工作_这几天我遇到了前所未有的问题windows10 1809 explorer.exe资源管理器频繁崩溃...
- 果园机器人的课文_小学三年级下《果园机器人》课文
- WaitForSingleObject的用法举例
- Kali 找回root 密码的操作步骤
- split函数python 未定义_Python之Split函数
- C# 总结const、 readonly、 static三者区别:
- javascript王者归来--属性和方法的类型
- java resultset 映射到实例_Java中,将ResultSet映射为对象和队列及其他辅助函数
- linux将时钟放在桌面上的,天气预报时钟插件加入你的Ubuntu桌面中
- dirt安装,记录两个印象深刻的问题
- ACM ICPC 2008–2009 NEERC MSC A, B, C, G, L
- FZU11685 之 跑跑卡丁车
- MongoDB系列之添加账号和密码
- Python如何读取STL文件,生成STL文件预览图(缩略图)
- 【转载】【UEFI学习】edk2中各个包介绍
- 96.android 简单的更新APP、下载安装APK(四种方式)
- 调光调色带人体感应台灯方案-DLT8SA20A-杰力科创
- K8s pod执行多条命令