「效率工具」GitBook(1):快速入门

GitBook 是什么?

官方的介绍是:What is GitBook? · GitBook Help Center

The legacy GitBook is both an online platform for writing and hosting documentation, and an open source book format and toolchain.

Hundreds of thousands of users use GitBook to write documentation (library, API, tools, etc.), or knowledge bases (like this F.A.Q.). People also use GitBook to publish technical books, teaching material, and many other things.

GitBook 有两部分构成,一个线下命令行工具和一个线上平台,命令行工具能够将 Markdown 文件生成网页,您可在服务器上预览,其样式就是一本带目录的电子图书。线上平台就是把线下的功能搬到线上。GitBook 提供三种样式的文档,书籍、API 文档和 FAQ

开始写书

如何写一本书?

答案是,开始写起来!

在线编辑及编辑器编辑

GitBook (Legacy) 登录,您可以点击右上角的+New按步骤添加新书籍。

之后,您可以在线上编辑,也可以下载编辑器编辑。完成书籍后,您还可导出 pdf、epub、mobi 三种格式。

这样就够了吗?在下还觉得不够酷!

用 git 管理书籍

在下认为酷的做法是,将书籍 git clone 到本地,然后在线下编辑,再 push 到线上。

  • 在终端切换到需要放书籍的目录下,输入git clone https://git.gitbook.com/username/bookname.git foldername
  • 编辑好后,git add把修改的文件添加到缓存区
  • git commit提交更改,把暂存区的所有内容提交到当前分支
  • git push同步到远程仓库

目录结构基础

以下两节的内容,既能满足您的大部分需求,又能避免出错。

基本目录结构

GitBook 基本目录结构如下所示

1
2
3
4
5
6
7
8
9
10
.
├── book.json
├── README.md
├── SUMMARY.md
├── ch1/
| ├── README.md
| └── content.md
└── ch2/
├── README.md
└── content.md

book.json 是您存放配置信息(不是必须的)的文件,一节将详细介绍。

根目录的README.md是必须要有的文件,用以展示您的书籍介绍页。

SUMMARY.md 存放您 GitBook 的文件目录信息(不是必须的),左侧的目录就是根据这个文件来生成的,默认对应的文件是 SUMMARY.md,可以在 book.json 重新定义该文件的对应值。它通过 Markdown 中的列表语法来表示文件的层级关系,简单的示例如下:

1
2
3
4
5
6
# 目录

* [前言](README.md)
* [第一章:C 语言基础](ch1/README.md)
* [C 语言程序结构](ch1/direction.md)
* [基本数据类型](ch1/basic-data-type.md)

对应的目录结构为:

您也可以使用###或者---将目录分为几个不同的部分,在文件后用#锚定到文件的特定部分。

静态文件

静态文件是在 SUMMARY.md 中未列出的文件。除非被忽略,否则所有静态文件都将复制到输出路径。

GitBook将读取 .gitignore.bookignore.ignore 文件,以获取要过滤的文件和文件夹。这些文件中的格式遵循 .gitignore 的规则,您可以切换终端到 GitBook 根目录,用 vim 编辑.gitignore文件。

1
2
3
4
5
6
7
# This is a comment

# Ignore the file test.md
test.md

# Ignore everything in the directory "bin"
bin

目录结构进阶

更多目录结构能让书籍更炫!

项目与子目录集成

对于软件项目,您可以使用子目录(如 docs/ )来存储项目文档的图书。您可以配置根选项来指示 GitBook 可以找到该图书文件的文件夹,例如

1
2
3
4
5
.
├── book.json
└── docs/
├── README.md
└── SUMMARY.md

book.json 中配置以下内容:

1
"root": "./docs"

封面

提供书籍的封面,要现在书籍根目录下放一个 cover.jpg 文件,添加一个 cover_small.jpg 将指定一个较小版本的封面。cover.jpg最好1800x2360像素,cover_small.jpg最好200x262像素,没有边界,书名清晰可见,小封面也能清晰看见重要文字。

术语汇编

根目录下还可以添加词汇表文件,默认对应的文件是 GLOSSARY.md。该文件主要存储词汇信息,如果在其他页面中出现了该文件中的词汇,鼠标放到词汇上会给出词汇示意,可以将鼠标移到下面两个词汇上看下效果。格式是一个 h2 标题的列表,以及一个描述段落:

1
2
3
4
5
6
## Term
Definition for this term

## Another term
With it's definition, this can contain bold text
and all other kinds of inline markup ...

多语言

GitBook 支持使用多种语言编写图书,每种语言应该是一个子目录,遵循正常 GitBook 格式LANGS.md 文件应该被放到 repository 的根文件夹, 格式如下:

1
2
3
4
5
6
7
8
* [中文](zh)

<!--
* [English](en)
* [Português](pt-br)
* [日本語 (にほんご)](ja)
* [漢語](zh-tw)
-->

参考

ChangeLog

  • 2018-07-28 初稿
「谢谢您支持」