MENU

如何在 Ubuntu 上搭建 Gitbook 电子书

2018 年 11 月 16 日 • 阅读: 373 • 建站技术阅读设置

gitbook1.png

相信很多站长有和我一样的习惯,除了日常更新博客外,平时也会花些时间对知识进行整理。使用 gitbook 将重要的笔记整理成电子书。这样既方便各大网友阅读,还可以带来新的离线阅读功能。而且还支持导出 PDF,EPUB,HTML 等多种格式。

准备环境

Gitbook 在安装过程中有较多相似之处,都是使用 NPM 来进行安装的。因此对于环境部署的相关操作,我将直接引用相关步骤。

本教程使用的系统环境为 Ubuntu ,由于使用自带的 nodejs 和 npm 低版本进行安装带来的坑超多,因此我决定手动安装。

执行下列命令,卸载 ubuntu 自带的 nodejs 和 npm

sudo apt-get remove nodejs && sudo apt-get remove npm

清理依赖

sudo apt-get autoremove

安装 nodejs,已知 node 版本 v9.8.0 测试正常

cd /opt && wget https://nodejs.org/dist/v9.8.0/node-v9.8.0-linux-x64.tar.xz //下载包
xz -d node-v9.8.0-linux-x64.tar.xz && tar vxf node-v9.8.0-linux-x64.tar //解包

建立软链接

ln -s /opt/node-v9.8.0-linux-x64/bin/node /usr/bin/node
ln -s /opt/node-v9.8.0-linux-x64/bin/npm /usr/bin/npm

测试一下

node -v && npm -v

均得到正确的版本号,表示nodejs和npm已成功安装。

开始安装

Gitbook 的安装非常简单,详细指南可以参考 gitbook 文档

安装只需要一步就能完成!

npm install -g gitbook-cli

检查是否安装成功:

gitbook -V

若成功显示版本号即表示安装成功。

简介及目录

可使用 vim 命令或 Markdown 编辑器分别创建 README.md 与 SUMMARY 文件。

示例

README.md 这个文件相对于是一本 Gitbook 的简介。

# Gitbook 使用入门

> GitBook 是一个基于 Node.js 的命令行工具,可使用 Github/Git 和 Markdown 来制作精美的电子书。
 
本书将简单介绍如何安装、编写、生成、发布一本在线图书。

SUMMARY.md 这个文件相对于是一本书的目录结构。

# Summary
 
* [Introduction](README.md)
* [基本安装](howtouse/README.md)
   * [Node.js安装](howtouse/nodejsinstall.md)
   * [Gitbook安装](howtouse/gitbookinstall.md)
   * [Gitbook命令行速览](howtouse/gitbookcli.md)
* [图书项目结构](book/README.md)
   * [README.md 与 SUMMARY编写](book/file.md)
   * [目录初始化](book/prjinit.md)
* [图书输出](output/README.md)
   * [输出为静态网站](output/outfile.md)
   * [输出PDF](output/pdfandebook.md)
* [发布](publish/README.md)
   * [发布到Github Pages](publish/gitpages.md)
* [结束](end/README.md)

SUMMARY.md基本上是列表加链接的语法。链接中可以使用目录,也可以使用。

简介于目录文件编写完成后,我们可以使用 Gitbook 的命令行工具将这个目目录结构生成相应地目录及文件。

$ gitbook init
 
$ ls
README.md    SUMMARY.md    book    end    howtouse    output    publish
 
$tree
.
├── LICENSE
├── README.md
├── SUMMARY.md
├── book
│   ├── README.md
│   ├── file.md
│   └── prjinit.md
├── howtouse
│   ├── Nodejsinstall.md
│   ├── README.md
│   ├── gitbookcli.md
│   └── gitbookinstall.md
├── output
│   ├── README.md
│   ├── outfile.md
│   └── pdfandebook.md
└── publish
    ├── README.md
    └── gitpages.md

我们可以看到,gitbook 给我们生成了与SUMMARY.md所对应的目录及文件。每个目录中,都有一个README.md文件,用于描述这一章的说明。

网站预览

1、运行一个Gitbook服务

当你编辑好 gitbook 文档之后,你可以使用 gitbook 的命令来进行本地预览。

gitbook serve ./{book_name}

Gitbook 默认会启动一个4000端口用于预览,监控进程默认监听35729端口,可以在浏览器中打开这个网址: http://localhost:4000

你会发现,在你编辑的 gitbook 项目的目录中会多一个_book目录,而这个目录中就是生成的本地预览的静态网站内容。

2、运行多个Gitbook服务

如果要启动另一部电子书服务的话,就需要同时修改web端口和监控进程端口, 否则会报如下错误:

You already have a server listening on 35729
You should stop it and try again.

应该这样:

gitbook serve --lrport 35288 --port 4001 /path2/your_another_doc_dir/

可以在浏览器中打开这个网址: http://localhost:4001来访问另外一个gitbook服务。

图书输出

目前为止,Gitbook支持如下输出:

  • 静态HTML,可以看作一个静态网站
  • PDF格式
  • eBook格式
  • 单个HTML文件
  • JSON格式

输出 HTML

你可以将静态网站内容输出到当前目录。

$ gitbook build .
Starting build ...
Successfuly built !
$ ls 
howtouse          search_index.json
book              imgs              output
gitbook           index.html        publish

GitBook 最近的版本,使用gitbook build命令生成了静态文件后,打开后的左侧点击均没有反应。

解决方案如下(即使用gitbook之前的版本来生成静态页面):

$ gitbook build --gitbook=2.6.7

输出 PDF

输出为PDF文件,需要先安装gitbook pdf执行下列命令:

npm install gitbook-pdf -g

如果在安装gitbook-pdf时,觉得下载phantomjs包太慢的话,你可以到phantomjs的官方网站上去下载。

http://phantomjs.org/

这个包的安装方式,参考其官网的说明文档。

然后,用下面的命令就可以生成PDF文件了。

gitbook pdf {book_name}

如果,你已经在编写的 gitbook 当前目录,也可以使用相对路径。

gitbook pdf . // 注意是点号

然后,你就会发现,你的目录中多了一个名为book.pdf的文件。

插件安装

修改 book.json文件,常用的插件及插件配置如下:

    "plugins": [
        "-lunr", 
        "-search",
        "redirect",
        "-sharing",
        "fontsettings",
        "todo",
        "-livereload",
        "search-pro",
        "code",
        "back-to-top-button",
        "auto-scroll-table",
        "expandable-chapters",
        "lightbox",
        "flexible-alerts",
        "splitter",
        "advanced-emoji"
    ],
    "pluginsConfig": {
    "fontsettings": {
        "theme": "white",
        "family": "sans",
        "size":  2
    },
    "code": {
       "copyButtons": false
     }
},

可直接复制上面的配置,直接替换book.json文件中pluginspluginsConfig包含的所有内容(别漏下,号)

进入文档根目录,运行gitbook命令安装插件:

gitbook install

插件安装完成,此时你可以使用 gitbook 的命令来进行本地预览。

gitbook serve ./{book_name}

资料整理

更多gitbook相关介绍说明以及 markdown 用法,请查看 Gitbook 文档热门插件

扫码手机看 请喝咖啡 返回首页
本页链接的二维码
打赏二维码