使用GitBook编写项目文档
GitBook简介
GitBook 是使用 GitHub / Git 和 Markdown(或AsciiDoc)构建漂亮书籍的命令行工具(和Node.js库);
GitBook 可以将您的内容作为网站(可定制和可扩展)或电子书(PDF,ePub或Mobi)输出;
GitBook.com 是使用 GitBook 格式创建和托管图书的在线平台。它提供托管,协作功能和易于使用的编辑器。
GitBook环境安装(需要安装NodeJS环境)
NodeJS安装:
官方下载地址:https://nodejs.org/en/download/
windows下:
直接下载.msi安装包依照向导安装即可,安装完成后在命令行中查看版本验证成功与否。
Linux下:
$ wget https://nodejs.org/dist/v10.9.0/node-v10.9.0-linux-x64.tar.xz // 下载
$ tar xf node-v10.9.0-linux-x64.tar.xz // 解压
$ cd node-v10.9.0-linux-x64/ // 进入解压目录
$ ./bin/node -v // 执行node命令 查看版本
v10.9.0
解压文件的 bin 目录底下包含了 node、npm 等命令,我们可以使用 ln 命令来设置软连接:
$ ln -s /usr/software/nodejs/bin/npm /usr/local/bin/
$ ln -s /usr/software/nodejs/bin/node /usr/local/bin/
GitBook安装:
Gitbook是使用NPM来进行安装的,可以在命令行中输入下面的命令进行安装:
$ npm install gitbook-cli -g
gitbook-cli
是 GitBook 的一个命令行工具。它将自动安装所需版本的 GitBook 来构建一本书,
安装完成之后,你可以使用下面的命令来检验是否安装成功。
$ gitbook -V
CLI version: 2.3.
GitBook version: 3.2.
Gitbook命令行使用
初始化一本书:
gitbook init
在使用 gitbook init
之后本地会生成两个文件 README.md
和 SUMMARY.md
,这两个文件都是必须的,一个为介绍,一个为目录结构。
编辑电子书:
首先,GitBook使用SUMMARY.md文件组织整个内容的目录,比如可以新建 Faq.md
文件,来记录常见问题,并在 SUMMARY.md 文件中添加目录。
# Summary * [简介](README.md)
* [常见问题](Faq.md)
安装插件:
在book.json文件下配置插件后,执行命令统一安装。
gitbook install
本地预览:
当内容书写完毕后,可以在终端中输入如下命令,实现实时预览。
gitbook serve
gitbook serve ./{book_name}
gitbook serve
命令实际会先调用 gitbook build
编译书籍,完成后打开 web 服务器,默认监听本地 4000 端口,在浏览器打开 http://localhost:4000 即可浏览电子书。
发布电子书:
gitbook build
gitbook build ./{book_name} --output=./{outputFolde}
gitbook build ./ --log=debug --debug
当电子书内容制作好之后,可以使用如下命令来生成 HTML 静态网页版电子书。该命令会在当前文件夹中生成 _book
文件夹,这个文件夹中的内容就是静态网页版电子书。
使用 --log=debug --debug
可以用来调试,会打印出 stack trace。
查看帮助:
gitbook -h
GitBook项目结构
一个基本的 GitBook 电子书结构通常如下:
.
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-/
| ├── README.md
| └── something.md
└── chapter-/
├── README.md
└── something.md
简单的介绍下每个文件的作用:
book.json: 记录电子书的配置 (可选)
README.md: 前言 或者 电子书的介绍 (必须)
SUMMARY.md: 电子书的目录 (可选)
GLOSSARY.md: 术语表 (可选)
使用语法
在Gitbook中所有文字的编写都使用Markdown
语法。
README.md:
这个文件相对于是一本Gitbook的简介,比如 :
# Gitbook 使用入门 > GitBook 是一个基于 Node.js 的命令行工具,可使用 Github/Git 和 Markdown 来制作精美的电子书。
SUMMARY.md:
这个文件相对于是一本书的目录结构,比如 :
* [介绍](README.md)
* [基本安装](installation/README.md)
* [Node.js安装](installation/nodejs-install.md)
* [Gitbook安装](installation/gitbook-install.md)
* [Gitbook命令行速览](installation/gitbook-cli.md)
* [图书项目结构](book/README.md)
* [README.md 与 SUMMARY编写](book/file.md)
* [目录初始化](book/prjinit.md)
* [图书输出](output/README.md)
* [输出为静态网站](output/static.md)
* [输出PDF](output/pdfandebook.md)
* [发布](publish/README.md)
* [发布到Github Pages](publish/gitpages.md)
* [发布到公司文档服务器](publish/companyserver.md)
* [结束](end/README.md)
book.json:
这个文件保存对Gitbook的配置。
变量 | 描述 |
root | 包含所有图书文件的根文件夹的路径,除了 book.json |
structure | 指定自述文件,摘要,词汇表等的路径 |
title | 您的书名,默认值是从 README 中提取出来的。在 GitBook.com 上,这个字段是预填的 |
description | 您的书籍的描述,默认值是从 README 中提取出来的。在 GitBook.com 上,这个字段是预填的 |
author | 作者名。在GitBook.com上,这个字段是预填的 |
isbn | 国际标准书号 ISBN |
language | 本书的语言类型 —— ISO code 。默认值是 en |
direction | 文本阅读顺序。可以是 rtl (从右向左)或 ltr (从左向右),默认值依赖于 language 的值 |
gitbook | 应该使用的GitBook版本。使用 SemVer 规范,并接受类似于 “> = 3.0.0” 的条件 |
插件与主题:
插件及其配置也在 book.json
中指定。有关详细信息。
自 3.0.0 版本开始,GitBook 可以使用主题。有关详细信息,请参阅 the theming section 。
使用GitBook编写项目文档的更多相关文章
- MarkDown语法记录,还在用word,txt编写项目文档吗?
开始之前 是不是在github上看项目的时候第一眼就要看项目介绍? 是不是经常在某些项目的代码里面看到一个README.MD文档 却不知道怎么写? 你是不是不知道,反正我是的. 作为一个程序员,可能写 ...
- Maven项目文档
本教程学习如何一步到位地创建应用程序的文档.因此现在开始我们进入到 C:\MVN 创建 java 应用程序项目:consumerBanking. 进入到项目文件夹中执行以下命令 mvn 命令. C: ...
- 使用gitlab runner 进行CI(四):使用Gitlab Page托管项目文档
目录 1.什么是Gitlab Pages 2.开启Gitlab Pages 3.基本过程 4.托管markdown文档 4.1 安装sphinx等依赖 4.2 配置项目的sphinx配置 4.3 编写 ...
- 基于 Markdown 编写接口文档
最近公司开发项目需要前后端分离,这样话就设计到后端接口设计.复杂功能需要提供各种各样的接口供前端调用,因此编写API文档非常有必要了 网上查了很多资料,发现基于Markdown编写文档是一种比较流行而 ...
- 使用vim编写hexo文档,并用ultisnips/snipmates/snippets插件补全
作为一个vim使用者,编写markdown文档时若不能用vim这怎么能受的了! 下面是我编写markdown的时候用到的插件 Plugin 'Markdown'Plugin 'Markdown-syn ...
- 使用Mkdocs构建你的项目文档
使用Mkdocs构建你的项目文档 环境搭建 安装必需软件 作者是在windows下安装的,如果是linux或mac用户,官网有更详细的安装说明. windows 10 x64 当然还有广大的windo ...
- Flask14 渲染问题、API、项目文档
3 前端渲染和后端渲染 这两种渲染都属于动态页面 区分前后端渲染的关键点是站在浏览器的角度 3.1 后端渲染 浏览器请求服务器后获取到的是完整的HTML页面(即:后台已经组装好HTML文件啦),利用f ...
- maven 学习---Maven项目文档
本教程将教你如何一步到位创建应用程序的文档.因此,让我们开始,到 C:/MVN 创建java应用程序consumerBanking. OpenconsumerBanking文件夹,然后执行以下命令m ...
- 使用 Hexo 创建项目文档网站
当我们发布一个开源项目的时候,最重要的事情之一就是要创建项目文档.对使用项目的用户来说,文档是非常有必要的,通常我们可以使用下面这些方式来创建文档: GitHub Wiki:在 Github 上我们可 ...
随机推荐
- main函数的参数(int argc,char *argv[])
一般的main函数都是不带参数的,因此main 后的括号都是空括号.实际上,main函数可以带参数,这个参数可以认为是 main函数的形式参数.C语言规定main函数的参数只能有两个, 习惯上这两个参 ...
- php速成_day3
一.MySQL关系型数据库 1.什么是数据库 数据库 数据存储的仓库,在网站开发应用当中,需要有一些数据存储起来. 注册的用户信息,使用PHP变量只是一个临时的存储,如果需要永久的存储起来,就把数据存 ...
- Spring Cloud Alibaba 教程 | Nacos(二)
源码解析客户端注册过程 nacos作为注册中心,包含了nacos服务端(注册中心服务)和nacos客户端,nacos注册中心服务上面一讲已经介绍过了它是一个用Java语言编写开源web项目,并且拥有自 ...
- 为什么Web前端变的越来越复杂,变得更加难学了
前端发展了也有些年头了,曾记得很多年前,聊起前端,都觉得是很简单,那个时候都没有前端工程师这个职位.可现在,前端已经逆袭了,已经不是原来的样子了,各种技术层出不穷,显的越来越高深莫测了.前端真的变得那 ...
- 标准库模块——shutil模块
shutil.rmtee 删除目录及以内的所有文件. import shutil shutil.rmtree(r'D:\python\222') #包括222在内的所有文件全部删除.
- Go-开发环境搭建
02-开发环境搭建 目录 一 下载地址 二 安装 Linux安装 Windows安装 Mac安装 三 测试安装 四 命令介绍 基本介绍 build 和 run 命令 get 命令 一 下载地址 安 ...
- ZJNU 1160 - 不要62——中级
取模判断,数组模拟 /* Written By StelaYuri */ #include<stdio.h> ]; int main(){ int n,m,i,s,t; ;i<;i+ ...
- linux mysql备份数据库
$ mysqldump -u root -p 数据库名称 > beifen.sql 恢复 source beifen.sql
- 放贷额度相关的ROI计算
违约模型得到概率估计, 将概率值划分5档, 每一档确定一个授信系数 新的授信 = 每月收入* 授信系数 - 老的授信 计算新增授信额度 计算余额损失
- Android之布局RelativeLayout
线性布局的weight属性在等比例分配时比较方便,但是对复杂的界面,嵌套多层LinearLayout布局会导致渲染变慢,占用更多系统资源:而使用RelativeLayout的话,可能仅仅需要一层就可以 ...