如何制作文档

使用 GitBook 命令行工具制作文档的步骤是怎样的?

1. 安装 Node.js

GitBook 依赖 Node.js 环境。如果您的系统中还未安装 Node.js,请自行安装。可以使用 nvm 这个 node 版本管理器。

2. 安装 GitBook 命令行工具

打开 "命令提示符"(Mac 系统打开 "终端")输入以下命令安装 gitbook-cli (这个工具是用来管理 gitbook 工具的,通过 gitbook-cli 可以在本地安装多个 gitbook 工具的不同版本):

npm install gitbook-cli -g

以上命令为全局安装 GitBook。GitBook 命令行工具一旦安装后,就无需重复安装,利用该工具可以创建多个电子书。

查看 gitbook-cli 的版本:

gitbook --version

更新 gitbook-cli 命令:

npm update gitbook-cli -g

卸载 gitbook-cli 命令:

npm uninstall gitbook-cli -g

查看 gitbook-cli 帮助信息:

$ gitbook -h


  Usage: gitbook [options] [command]


  Options:

    -v, --gitbook [version]  specify GitBook version to use
    -d, --debug              enable verbose error
    -V, --version            Display running versions of gitbook and gitbook-cli
    -h, --help               output usage information


  Commands:

    ls                        List versions installed locally
    current                   Display currently activated version
    ls-remote                 List remote versions available for install
    fetch [version]           Download and install a <version>
    alias [folder] [version]  Set an alias named <version> pointing to <folder>
    uninstall [version]       Uninstall a version
    update [tag]              Update to the latest version of GitBook
    help                      List commands for GitBook
    *                         run a command with a specific gitbook version

然后通过 gitbook-cli 安装 gitbook

gitbook fetch latest

详细安装指南可以参考 GitBook 文档

查看 gitbook 的帮助信息:

gitbook help

GitBook 常用命令:

gitbook build [options] [source_dir]      # 根据文档目录构建书籍
gitbook serve [options] [source_dir]      # 构建并且提供书籍的 web 托管
gitbook install [options] [source_dir]    # 安装 GitBook 插件
gitbook pdf [options] [source_dir]        # 构建 pdf 格式的电子书
gitbook epub [options] [source_dir]       # 构建 ePub 格式的电子书
gitbook mobi [options] [source_dir]       # 构建 mobi 格式的电子书
gitbook init [source_dir]                 # 根据 SUMARRY.md 文件的内容生成相应的目录和文件
gitbook publish [source_dir]              # 如果已绑定 GitBook.io,该命令可以直接发布书籍
gitbook git:remote [source_dir] [book_id] # 为书籍设置远程 git 仓库

gitbook -V, --version   # 输出程序的版本号

gitbook help                  # 列出 gitbook 所有的命令
gitbook --help                # 输出 gitbook-cli 的帮助信息
gitbook build                 # 生成静态网页
gitbook serve                 # 生成静态网页并运行服务器
gitbook build --gitbook=2.0.1 # 生成时指定 gitbook 的版本,本地没有会先下载
gitbook build --log=debug     # 指定 log 的级别
gitbook builid --debug        # 输出错误信息

顺便吐槽一下 GitBook 命令设计是有问题,两个不同的命令耦合在了一起。

3. 新建 GitBook 项目

新建一个目录,并进入该目录使用 gitbook 命令初始化电子书项目。举个例子,现在要创建一个名为 "MyBook" 的空白电子书项目,如下所示:

mkdir MyBook   # 新建目录
cd MyBook   # 进入目录
gitbook init   # 初始化目录

初始化后的目录中会出现 README.mdSUMMARY.md 两个基本文件。GitBook 基本目录结构如下:

.
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
|   ├── README.md
|   └── something.md
└── chapter-2/
    ├── README.md
    └── something.md

当然,也可以先创建 README.mdSUMMARY.md 两个基本文件,然后 $ gitbook init,这样 GitBook 会自动创建 SUMMARY.md 中的目录结构。

4. 编辑电子书内容

首先,GitBook 使用 SUMMARY.md 文件组织整个内容的目录,如:

# Summary

* [简介](README.md)
* [常见问题](Faq.md)

目录中的章节也可以使用锚点指向文件的特定部分:

# Summary

### Part I

* [Part I](part1/README.md)
    * [Writing is nice](part1/README.md#writing)
    * [GitBook is nice](part1/README.md#gitbook)
* [Part II](part2/README.md)
    * [We love feedback](part2/README.md#feedback)
    * [Better tools for authors](part2/README.md#tools)

5. 预览电子书

当内容书写完毕后,可以在终端中输入如下命令,实现实时预览:

gitbook serve

gitbook serve 命令实际上会首先调用 gitbook build 编译书籍,完成以后会打开一个 web 服务器,监听本地 4000 端口,在浏览器中输入 http://localhost:4000,即可打开电子书。

6. 发布电子书

当电子书内容制作好后,可以使用如下命令,生成 html 版本的电子书:

gitbook build

该命令会在当前文件夹中生成 _book 文件夹,用户可以将这个文件夹内容托管到网上,从而实现内容的发布。

7. 生成其他格式文件 (calibre)

GitBook 生成其他格式的书是借助 calibre 的转换功能实现的 (ebook-convert)。安装完 calibre 后,修改系统 $PATH 定义,把转换程序的路径加到系统 PATH 里,要不然会找不到转换程序:

vi ~/.bashrc   # bash
vi ~/.zshrc   # zsh

添加这一行:

export PATH=$PATH:/Applications/calibre.app/Contents/MacOS/

然后使用 source 命令使文件立即生效。

  • 生成 PDF 文件

      gitbook pdf ./ mybook.pdf
    
  • 生成 EPUB 文件

      gitbook epub ./ mybook.epub
    
  • 生成 MOBI 文件,支持 kindle

      gitbook mobi ./ mybook.mobi
    

results matching ""

    No results matching ""