抓取网页生成电子书(Gitbook生成电子书的完整过程及安装、命令、配置、文档结构)

　　抓取网页生成电子书(Gitbook生成电子书的完整过程及安装、命令、配置、文档结构)

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

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

　　如果想看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

　　启动服务

　　使用以下命令将运行一个可以通过 :4000/ 预览书籍的 Web 服务

　　$ 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 使用简单的目录结构。Summary 中列出的所有 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 特殊文件的特点：

　　文件描述

　　book.json

　　配置数据（可选）

　　自述文件.md

　　电子书的前言或介绍（必填）

　　摘要.md

　　电子书目录（可选）

　　词汇表.md

　　词汇表/评论术语列表（可选）

　　静态文件和图像

　　静态文件是未在 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)

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

　　页

　　降价语法

　　默认情况下，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 等工具来验证语法。

　　常规设置变量描述

　　根

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

　　结构体

　　指定自述文件、摘要、词汇表等参考的路径。

　　标题

　　您的书名，默认值是从 README 中提取的。在 上，此字段已预先填写。

　　描述

　　你的书的描述，默认值是从自述文件中提取的。在 上，此字段已预先填写。

　　作者

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

　　伊斯本

　　国际标准书号 ISBN

　　语言

　　本书的语言类型——ISO 代码。默认值为 en

　　方向

　　文本阅读顺序。可以是 rtl（从右到左）或 ltr（从左到右），默认值取决于语言的值。

　　gitbook

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

　　作者

　　作者姓名，on ，该字段是预填的。

　　例子：

　　"author" : "victor zhang"

　　描述

　　eBook 的描述，默认值是从 README 中提取的。在 上，此字段已预先填写。

　　例子：

　　"description" : "Gitbook 教程"

　　方向

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

　　例子：

　　"direction" : "ltr"

　　gitbook

　　应该使用的 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/atlantis1024/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 中指定。了解更多信息。

　　GitBook 可以使用自版本 3.0.0 起的主题。有关详细信息，请参阅主题部分。

　　变量描述

　　插件

　　要加载的插件列表

　　插件配置

　　插件配置

　　添加插件

　　"plugins": [

"splitter"

]

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

　　删除内置插件

　　Gitbook 默认自带 5 个插件：

　　"plugins": [

"-search"

]

　　结构体

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

　　变量描述

　　结构.readme

　　自述文件名（默认为 README.md）

　　结构.摘要

　　摘要文件名（默认为SUMMARY.md）

　　结构.词汇表

　　词汇表文件名（默认为 GLOSSARY.md）

　　结构语言

　　语言文件名（默认为 LANGS.md）

　　pdf

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

　　变量描述

　　pdf.pageNumbers

　　在每页底部添加页码（默认为 true）

　　pdf.fontSize

　　基本字体大小（默认为 12）

　　pdf.fontFamily

　　基本字体样式（默认为 Arial）

　　pdf.paperSize

　　页面大小，选项有：'a0'、'a1'、'a2'、'a3'、'a4'、'a5'、'a6'、'b0'、'b1'、'b2'、'b3'、 'b4', 'b5', 'b6', 'legal', 'letter' (默认是a4）

　　上限（默认为 56）

　　pdf.margin.bottom

　　下限（默认为 56）

　　pdf.margin.right

　　右边框（默认为 62）

　　pdf.margin.left

　　左边框（默认为 62）

　　生成电子书

　　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 可用于生成电子书（epub、mobi、pdf）。

　　GNU/Linux

　　安装口径应用程序。

　　$ sudo aptitude install calibre

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

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

　　操作系统

　　下载口径应用程序。将 calibre.app 移动到应用程序文件夹后，创建指向 ebook-convert 工具的符号链接：

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

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

　　覆盖

　　封面用于所有电子书格式。您可以自己提供一个或使用自动覆盖插件生成一个。

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

　　一个好的封面应该遵循以下准则：

　　Gitbook 部署托管到

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

　　创建新书

　　如下图所示，根据您的个人需求，选择一个模板来创建您的电子书。

　　

　　设置图书基本信息

　　

　　克隆到本地

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

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

　　

　　释放

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

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

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

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

　　托管在 Github 上

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

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

　　

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

　　

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

　　默认访问地址为：

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

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

　　托管到 Github 页面

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

　　构建 xxx.github.io 仓库

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

　　创建 gh-pages 分支

　　完成步骤 1 后，在任何 Github 存储库中创建一个名为 gh-pages 的分支。只要 gh-pages 中的内容满足静态站点要求，就可以在如下地址访问：username.gitbooks.io/Github 仓库。例如：我的 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:atlantis1024/gitbook-notes gh-pages --force"

　　资源 官方资源 教程 资源工具