下面列出的网站内容(Gitbook详细讲解Gitbook生成电子书的完整过程)

　　下面列出的网站内容(Gitbook详细讲解Gitbook生成电子书的完整过程)

　　本文详细讲解了Gitbook生成电子书的完整流程，包括：安装、命令、配置、文档结构、电子书生成、部署。

　　限于篇幅，本文不介绍任何Gitbook自定义页面的内容。

　　如果想看Gitbook在线电子书的效果，请点这里：gitbook-notes

　　我的Gitbook详细教程维护在这里：gitbook-notes

　　概述

　　GitBook 是一个命令行工具（和 Node.js 库），用于使用 GitHub/Git 和 Markdown（或 AsciiDoc）构建精美的书籍。

　　GitBook 可以将您的内容输出为 网站（可定制和可扩展）或电子书（PDF、ePub 或 Mobi）。

　　是一个使用 GitBook 格式来创建和托管书籍的在线平台。它提供托管、协作功能和易于使用的编辑器。

　　

　　GitBook 安装

　　本地安装环境要求

　　安装 GitBook 非常简单。您的系统只需满足以下两个要求：

　　通过 NPM 安装

　　安装 GitBook 的最佳方式是通过 NPM。在终端提示符下，只需运行以下命令即可安装 GitBook：

　　$ npm install gitbook-cli -g

　　gitbook-cli 是 GitBook 的命令行工具。它将自动安装所需版本的 GitBook 以构建一本书。

　　执行以下命令查看GitBook版本，验证安装是否成功。

　　$ gitbook -V

　　安装历史版本

　　gitbook-cli 可以方便的下载安装其他版本的 GitBook 来测试你的书：

　　$ gitbook fetch beta

　　使用 gitbook ls-remote 将列出可下载的版本。

　　创建图书初始化

　　GitBook 可以设置模板书：

　　$ gitbook init

　　如果你想在新目录中创建一本书，你可以通过运行 gitbook init ./directory 来实现。

　　构建

　　使用以下命令，会在项目目录下生成一个_book目录，里面的内容是静态站点的资源文件：

　　$ gitbook build

　　调试

　　您可以使用选项 --log=debug 和 --debug 来获得更好的错误消息（使用堆栈跟踪）。例如：

　　$ gitbook build ./ --log=debug --debug

　　启动服务

　　使用以下命令运行一个web服务，通​​过:4000/预览书籍

　　$ gitbook serve

　　GitBook 命令

　　这里主要介绍GitBook的命令行工具gitbook-cli的一些命令。首先说明两点：

　　列出gitbook的所有命令

　　gitbook help

　　输出gitbook-cli的帮助信息

　　gitbook --help

　　生成静态网页

　　gitbook build

　　生成静态网页并运行服务器

　　gitbook serve

　　生成时指定gitbook的版本，如果不在本地，会先下载

　　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 build --log=debug

　　输出错误信息

　　gitbook builid --debug

　　Gitbook 目录结构

　　GitBook 项目结构

　　GitBook 使用简单的目录结构。总结中列出的所有 Markdown / Asciidoc 文件（即SUMMARY.md 文件）都将转换为 HTML。多语种图书的结构略有不同。

　　一本基本的 GitBook 电子书的结构通常如下：

　　.

├── book.json

├── README.md

├── SUMMARY.md

├── chapter-1/

| ├── README.md

| └── something.md

└── chapter-2/

├── README.md

└── something.md

　　GitBook 特殊文件的作用：

　　

　　静态文件和图片

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

　　忽略文件和文件夹

　　GitBook 将读取 .gitignore、.bookignore 和 .ignore 文件以获取要过滤的文件和文件夹。这些文件中的格式遵循 .gitignore 的规则：

　　# This is a comment

# Ignore the file test.md

test.md

# Ignore everything in the directory "bin"

bin/*

　　项目和子目录集成

　　对于软件项目，您可以使用子目录（例如 docs/）来存储项目文档的书籍。可以配置root选项来指明GitBook可以在哪个文件夹中找到书本文件：

　　.

├── book.json

└── docs/

├── README.md

└── SUMMARY.md

　　在 book.json 中配置以下内容：

　　{

"root": "./docs"

}

　　总结

　　GitBook 使用Summary.md 文件来定义本书的章节和子章节的结构。 Summary.md 文件用于生成本书的目录。

　　SUMMARY.md 的格式是一个链表。链接标题为章节标题，链接目标为章节文件路径。

　　向父章节添加嵌套列表将创建一个子章节。

　　简单例子：

　　# Summary

* [Part I](part1/README.md)

* [Writing is nice](part1/writing.md)

* [GitBook is nice](part1/gitbook.md)

* [Part II](part2/README.md)

* [We love feedback](part2/feedback_please.md)

* [Better tools for authors](part2/better_tools.md)

　　每章都有一个专门的页面（part#/README.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)

　　部分

　　目录可以分成由标题或横线分隔的部分----:

　　# Summary

### Part I

* [Writing is nice](part1/writing.md)

* [GitBook is nice](part1/gitbook.md)

### Part II

* [We love feedback](part2/feedback_please.md)

* [Better tools for authors](part2/better_tools.md)

----

* [Last part without title](part3/title.md)

　　Parts只是一个章节组，没有专门的页面，但是会根据主题在导航中显示。

　　页面

　　Markdown 语法

　　默认情况下，GitBook 中的大多数文件都使用 Markdown 语法。 GitBook 推荐这种语法。使用的语法类似于 GitHub Flavored Markdown 语法。

　　此外，您还可以选择 AsciiDoc 语法。

　　页面内容示例：

　　# Title of the chapter

This is a great introduction.

## Section 1

Markdown will dictates _most_ of your **book's structure**

## Section 2

...

　　页面前言

　　页面可以收录可选的前言。它可用于定义页面的描述。前一项必须是文件中的第一项，并且必须采用三个虚线之间的有效 YAML 集的形式。这是一个基本示例：

　　---

description: This is a short description of my page

---

# The content of my page

...

　　词汇表

　　允许您指定要显示为注释的术语及其各自的定义。 GitBook 会根据这些术语自动建立索引并突出显示这些术语。

　　GLOSSARY.md 的格式是一个 h2 标题列表和一个描述段落：

　　## 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 允许您通过灵活的配置自定义您的电子书。

　　这些选项在 book.json 文件中指定。对于不熟悉 JSON 语法的作者，可以使用 JSONlint 等工具来验证语法。常规设置

　　

　　作者

　　作者姓名。以上，此字段已预先填写。

　　示例：

　　"author" : "victor zhang"

　　说明

　　电子书的描述，默认值摘自README。在上面，这个字段是预先填写的。

　　示例：

　　"description" : "Gitbook 教程"

　　方向

　　文本的方向。可以是 rtl 或 ltr，默认值取决于语言值。

　　示例：

　　"direction" : "ltr"

　　书本

　　应该使用的 GitBook 版本。使用 SemVer 规范并接受类似于 >=3.0.0 的条件。

　　示例：

　　"gitbook" : "3.0.0",

"gitbook" : ">=3.0.0"

　　语言

　　Gitbook使用的语言，2.6.4版本中可用的语言如下：

　　en, ar, bn, cs, de, en, es, fa, fi, fr, he, it, ja, ko, no, pl, pt, ro, ru, sv, uk, vi, zh-hans, zh-tw

　　示例：

　　"language" : "zh-hans",

　　链接

　　在左侧导航栏中添加链接信息

　　示例：

　　"links" : {

"sidebar" : {

"Home" : "https://github.com/dunwu/gitbook-notes"

}

}

　　根

　　收录除 book.json 文件之外的所有书籍文件的根文件夹的路径。

　　示例：

　　"root" : "./docs",

　　结构

　　指定与自述文件、摘要、词汇表和语言对应的文件名。

　　样式

　　自定义页面样式，默认每个*敏*感*词*对应的css文件

　　示例：

　　"styles": {

"website": "styles/website.css",

"ebook": "styles/ebook.css",

"pdf": "styles/pdf.css",

"mobi": "styles/mobi.css",

"epub": "styles/epub.css"

}

　　比如让h1、h2标签有下边框，可以在website.css中设置

　　h1 , h2{

border-bottom: 1px solid #EFEAEA;

}

　　标题

　　电子书的标题。默认值是从 README 中提取的。开启，此字段已预先填写。

　　示例：

　　"title" : "gitbook-notes",

　　插件

　　插件及其配置在 book.json 中指定。欲了解更多信息。

　　从3.0.0 版本开始，GitBook 可以使用主题。有关详细信息，请参阅主题部分。

　　

　　添加插件

　　"plugins": [

"splitter"

]

　　添加新插件后，需要运行 gitbook install 安装新插件

　　删除内置插件

　　Gitbook 默认自带 5 个插件：

　　"plugins": [

"-search"

]

　　结构

　　除了root属性外，还可以指定Readme、Summary、Glossary和Languages的名称（而不是使用README.md等默认名称）。这些文件必须在项目的根目录下（或者根根目录，如果你在 book.json 中配置了 root 属性）。不可接受的路径，如：dir / MY_README.md。

　　

　　pdf

　　您可以使用 book.json 中的一组选项来自定义 PDF 输出：

　　

　　生成电子书

　　GitBook 可以生成网站，但也可以将内容输出为电子书（ePub、Mobi、PDF）。

　　# Generate a PDF file

$ gitbook pdf ./ ./mybook.pdf

# Generate an ePub file

$ gitbook epub ./ ./mybook.epub

# Generate a Mobi file

$ gitbook mobi ./ ./mybook.mobi

　　安装 ebook-convert

　　ebook-convert 可用于生成电子书（epub、mobi、pdf）。

　　GNU/Linux

　　安装 Calibre 应用程序。

　　$ sudo aptitude install calibre

　　在某些 GNU/Linux 发行版中，节点安装为 nodejs，需要手动创建符号链接：

　　$sudo ln -s /usr/bin/nodejs /usr/bin/node

　　OS X

　　下载 Calibre 应用程序。将 calibre.app 移动到应用程序文件夹后，创建指向电子书转换工具的符号链接：

　　$ sudo ln -s ~/Applications/calibre.app/Contents/MacOS/ebook-convert /usr/bin

　　您可以将 /usr/bin 替换为 $PATH 中的任何目录。

　　封面

　　封面适用于所有电子书格式。你可以自己提供一个，也可以使用autocover插件生成一个。

　　要提供封面，请将cover.jpg文件放在本书的根目录下。添加cover_small.jpg 将指定封面的较小版本。封面应为 JPEG 文件。

　　好的封面应该符合以下准则：

　　Gitbook 部署

　　托管于

　　[](/) 是一个在线平台，用于创建和托管 GitBook 格式的书籍。它提供托管、协作功能和易于使用的编辑器。

　　创建一本新书

　　如下图所示，根据个人需求选择模板制作电子书。

　　

　　设置本基本信息

　　

　　克隆到本地

　　将为每本书创建一个 git 存储库。

　　如下图，复制git地址，然后git clone到本地。

　　

　　发布

　　按照Gitbook规范在本地编辑电子书，然后git push到Gitbook的远程仓库。

　　默认访问地址为：username.gitbooks.io/project name/content/

　　例如：我的用户名是dunwu，一个电子书项目叫test，那么访问路径是：

　　当然，如果你有自己的域名，你也可以设置Domains选项，将访问路径指定为你的域。

　　托管到 Github

　　如果不想使用Gitbook的仓库，但想直接使用Github的仓库，也是可以的。

　　首先，您需要绑定您的 Github 帐户。最简单的方式当然是在登录时使用Github账号登录方式，否则也可以在账号设置中的Github设置选项中进行绑定。

　　绑定Github账号后，新建电子书时可以选择从指定的Github仓库导入电子书项目。参考下图：

　　

　　只要您指定的 Github 仓库中的文档内容符合 Gitbook 规范，Gitbook 会根据您的每次更新自动构建并生成电子书网站。

　　默认访问地址为：

　　https://Github用户名.gitbooks.io/Github 仓库/content/

　　例如：我的用户名为dunwu，Github仓库名为gitbook-notes，那么访问路径为：

　　dunwu.gitbooks.io/gitbook-notes/content/

　　托管到 Github 页面

　　也许你之前也知道 Github 的一个功能：GitHub Pages。它允许用户在 GitHub 存储库中托管您的个人、组织或项目的静态页面（自动识别 html、css、javascript）。

　　建立xxx.github.io仓库

　　要使用这个功能，首先要创建一个严格遵循以下命名要求的仓库：Github账号名.github.io 比如我的Github账号是dunwu，那么这个仓库应该叫dunwu.github.io 通常，此存储库用作个人或组织博客。

　　创建 gh-pages 分支

　　完成第 1 步后，在任何 Github 存储库中创建一个名为 gh-pages 的分支。只要gh-pages中的内容满足静态站点的要求，就可以通过以下地址访问：username.gitbooks.io/Github repository。例如：我的一个Github仓库叫react-notes，访问路径是：

　　自动发布到 gh-pages

　　如果每次都手动git push到远程gh-pages分支，会有点麻烦。

　　如何自动化发布？

　　有两种方式：

　　使用 gh-pages 插件

　　如果您了解 Nodejs，最简单的发布方式是使用 gh-pages 插件。

　　先在本地安装插件

　　$ npm i -D gh-pages

　　然后，在 package.json 文件中添加一个脚本命令：

　　如下：-d命令参数后面是要发布的静态站点内容的目录

　　"scripts": {

"deploy": "gh-pages -d build"

},

　　脚本

　　编写一个执行 git 命令的脚本就大功告成了。

　　以下脚本可以在 bat 或 sh 脚本中执行。

　　cd build

git init

git checkout -b gh-pages

git add .

git commit -am "Update"

git push git@github.com:dunwu/gitbook-notes gh-pages --force"

　　资源

　　官方资源教程资源工具