Gitbook入门篇

什么是GitBook？

GitBook 是一个使用 Git 和 Markdown 来构建书籍的工具。它可以将你的书输出很多格式：PDF，ePub，mobi，或者输出为静态网页。

GitBook 是开源并且完全免费的，它的源码可以在 GitHub 上获取。与格式和工具链相关的问题被发表在 github.com/GitbookIO/gitbook/issues。

gitBook 是一个基于node.js的命令行工具，使用 github/git 和 markdown/asciiDoc 构建精美的电子书。它支持输出静态网页和电子书等多种格式,其中默认输出静态网页格式。

gitbook 不仅支持本地构建电子书,而且可以托管在 gitbook 官网上,并享受在线发布和托管图书的便利,完整的文档请参考 gitbook 新版文档(需FQ)

打开gitbook.com网站需要使用代理。如果还是打不开，请确定你的shadowSocks的PAC是最新的，因为老的PAC可能不包括这个网站。（被坑过）

开始之前，你需要的准备

知识准备

markdown 快速入门

git - 简明指南（入门推荐）

环境检测

检查 git：git --version

检查 node.js：node --version

Markdown编辑器：方便本地开发，推荐Typora或gitbook自己的编辑器gitbook editor

最新注册的gitbook账号是无法使用 gitbook-editor 编辑器。

安装

安装：npm i -g gitbook-cli

检查 gitbook ：gitbook --version

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

注：不要运行npm i -g gitbook安装，如已安装，运行npm uni -g gitbook卸载，重装。

Gitbook命令

初始化 Gitbook 项目

gitbook init

gitbook init会在空项目中创建README.md和SUMMARY.md两个文件：README.md文件是项目的介绍文件。 SUMMARY.md是gitbook书籍的目录。

初始化相应的文件目录结构，所以主要是用于开发初始阶段.

启动 Gitbook 项目

gitbook serve [--port 4000]

默认情况下服务器启动后会占用两个端口，一个是对外暴露的 4000 端口，用于浏览器访问项目。另外一个是 35729 端口，用于监听本地文件变化，重启服务器进而实现热加载功能。

本地服务器启动后我们就可以访问 http://localhost:4000 预览静态网站效果。由于能够实时预览电子书效果,并且大多数开发环境搭建在本地而不是远程服务器中，所以主要用于开发调试阶段。

构建 Gitbook 静态网页

gitbook build [entry] [--output]
## gitbook build ./ ./docs

-o, --output <directory>  输出文件件, 默认为 ./_book
-f, --format <name>       产生的书籍的类型, 默认为静态站点, 可用的格式为: site, page, ebook, json
--config <config file>    配置文件, 默认为 book.js 或 book.json

构建静态网页而不启动本地服务器，默认生成文件存放在 _book/ 目录。在_book文件夹里有一个index.html文件，这个文件就是文档网站的HTM入口，主要用于发布准备阶段。

输出静态网页后可打包上传到服务器，也可以上传到 github 等网站进行托管。

当然输出目录是可配置的,暂不涉及,见高级部分.

其他命令

#切换版本
gitbook [version]
#列出当前已安装的版本
gitbook ls
#则是列出远程服务器版本
gitbook ls-remote
#更新版本
gitbook fetch [versiion]
#更新到gitbook的最新版本
gitbook update

#生成电子书
gitbook pdf ./ ./aaaa.pdf
gitbook epub ./ ./aaaa.epub
gitbook mobi ./ ./aaaa.mobi

Gitbook配置文件

如果你想对你的网站有更详细的个性化配置或使用插件，那么需要使用配置文件。配置文件写完后，需要重启服务或者重新打包才能应用配置。 gitbook的配置文件名是book.json，首先在项目的根目录中创建book.json文件。book.json主要内容：

{
    "root": "/", //指定存放 gitbook 文件(除了book.json文件本身)的根目录
    "gitbook" : "3.2.3", //gitbook 版本
    //"title": "我的一本书", //标题
    "page": {
        "title": "前端知识库(lizh)"
    },
    "author" : "lizhao", //作者
    "description" : "", //描述
    "language" : "zh-hans", //使用的语言，zh-hans是简体中文，会对应到页面的<html lang="zh-hans" >
    "variables": {
        "authorName": "lizhao"
    },

    //指定 Readme、Summary、Glossary 和 Languages 对应的文件名
    "structure": {
        //readme: 'README.md', //Readme file name
        //summary: 'SUMMARY.md', //Summary file name
        //glossary: 'GLOSSARY.md', //词汇表文件[可选]
        //languages: 'LANGS.md' //语言文件[可选]
    },

    //使用的插件列表，所有的插件都在这里写出来，然后使用gitbook install来安装
    "plugins": [
        //gitbook 默认自带5个插件
        //"highlight", //语法高亮插件
        //"search", //搜索插件
        //"sharing", //分享插件
        //"font-settings", //字体设置插件
        //livereload", //热加载插件

        "anchors",
        "expandable-chapters-small",
        "search-plus",
        "toggle-chapters",
        "summary",
        "splitter",
        "theme-comscore",
        "fontsettings"

        //"search-pro", //高级搜索（支持中文）
        //"back-to-top-button",
        //chapter-fold, //支持多层目录，点击导航栏的标题名就可以实现折叠扩展。
        //page-treeview, 在页面顶部显示目录

        //-符号代表去除默认自带的插件
        "-lunr",
        "-search"
    ],

    //插件的配置信息，如果插件需要配置参数，那么在这里填写
    "pluginsConfig": {
        "expandable-chapters-small":{},
        "fontsettings": {
            "theme": "white",
            "family": "sans",
            "size": 2
        }
    },

    //目前可以给侧导航栏添加链接信息
    "links" : {
        "sidebar" : {
        }
    },

    //自定义页面样式，各种格式对应各自的css文件
    "styles": {
        //"website": "styles/website.css",
        //"ebook": "styles/ebook.css",
        //"pdf": "styles/pdf.css",
        //"mobi": "styles/mobi.css",
        //"epub": "styles/epub.css"
    }
}

gitbook.com 官网操作

gitbook 官网是官方提供的图书托管的在线平台，分为新版官网(需要FQ) https://www.gitbook.com/ 和旧版官网(无需FQ) https://legacy.gitbook.com 两个网站。

目前均正常提供服务，但令人遗憾的是，两个网站的信息相互独立，而且现在注册的账号默认只能在新版官网中使用，而新版官网的访问速度简直比 github 还要慢，所以国内用户在线访问你的电子书真的需要点技术手段了!

将 github 个人网站项目同步到 gitbook 电子书项目。这样的好处是本地只需要推送到 github ，自动更新 github.io 网站(利用的是github 静态网站托管服务)，然后再自动同步到 gitbook.io 网站。

操作流程如下：

注册并登陆 gitbook.com（需要使用代理）

新建命名空间(电子书)

image-20200501132535089

域名&路径

默认域名是 https://[username].gitbook.io/，如果需要自定义域名，请保证 dns 能够正确解析到该网站。路径是spacename。比如：https://lizh.gitbook.io/knowledge/

整合Github

gitbook 默认提供4种整合方式：GitHub、Slack、Google Analytics、Intercom。

以为以 github 为例，其余三种没接触过，暂不涉及。

选择 github 进行整合

image-20200501134230474

选择目标仓库

登录 github 并授权 -> 选择目标仓库 -> 选择同步分支 -> 选择同步内容。

image-20200501134512566

导入成功

image-20200501134717525

由于 gitbook 电子书内容来自于 github 项目，因此我们只要更新 github 仓库，我们的 gitbook 电子书网站自然也就相应更新了!

美中不足的是,国内无法正常访问 gitbook.com 。现在国内也有类似的产品,有一种产品叫做 看云，还不错!

Gitbook插件

插件是 gitbook 的扩展功能，很多炫酷有用的功能都是通过插件完成的。其中插件有官方插件和第三方插件npm之分。根据 gitbook 插件规范, gitbook-plugin- 是功能插件,gitbook-theme- 是主体插件。

基本使用：

  • 先安装到本地： npm install gitbook-plugin-<name>（可略）
  • 插件配置：在 book.json 中 plugins 节点
  • 安装： gitbook install
{
    "plugins": [
        "myPlugin"
    ],
    "pluginsConfig": {
        "myPlugin": {}
    }
}

常见问题

gitbook build 或 gitbook serve报错

gitbook: 3.2.3
node：v12.2.0
npm：6.9.0

Error: ENOENT: no such file or directory, stat 'xxxx\_book\gitbook\gitbook-plugin-fontsettings\fontsettings.js'

方法一：将C:\Users\[whoami]\.gitbook\versions\3.2.3\lib\output\website\copyPluginAssets.js第112行confirm: true注释，或改成confirm: false

方法二：关闭杀毒软件

windows系统无法热加载，总是报错

Stopping server
events.js:173
      throw er; // Unhandled 'error' event
      ^

Error: EPERM: operation not permitted, lstat 'D:\MyCode\gitBook\_book'
Emitted 'error' event at:
    at FSWatcher._handleError (C:\Users\[whoami]\.gitbook\versions\3.2.3\node_modules\chokidar\index.js:236:10)
    at ReaddirpReadable.emit (events.js:196:13)
    at Immediate.<anonymous> (C:\Users\[whoami]\.gitbook\versions\3.2.3\node_modules\chokidar\node_modules\readdirp\stream-api.js:82:32)
    at processImmediate (internal/timers.js:439:21)

控制台信息说是操作权限的问题。打开项目，当前项目已经没有 _book 目录，证明发生报错时确实已经删除了 _book 目录，但是某种原因无权再次创建该文件夹而重启失败。结论是 gitbook 是删除 _book 文件夹再新建 _book 文件夹时发生了意外。

解决方法：在启动本地服务器后立即删除 _book 目录，当本地文件发生修改时重启服务就能成功了。

这个官方已知的一个bug，且没有想修复的意思。~只能期待gitbook升级了~

内容无法在gitbook.com显示

文件夹名称有大写字母或者文件名中有空格会导致 gitbook.com 网站中对应的链接无法访问。

~题外话~

搭建文档类站的工具，除了gitbook外，还有以下两种：

Docsify

docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 .md 转成 .html 文件，所有转换工作都是在运行时进行。

这将非常实用，如果只是需要快速的搭建一个小型的文档网站，或者不想因为生成的一堆 .html 文件“污染” commit 记录，只需要创建一个 index.html 就可以开始写文档而且直接部署在 GitHub Pages。

插件方面，docsify插件不如Gitbook的丰富，但麻雀虽小五脏俱全，该有的基本也都有，足够使用。

对 SEO 不够友好，因为它是完全的运行时驱动的。

特性：

  • 无需构建，写完文档直接发布
  • 容易使用并且轻量 (压缩后 ~21kB)
  • 智能的全文搜索
  • 提供多套主题
  • 丰富的 API
  • 支持 Emoji
  • 兼容 IE11
  • 支持服务端渲染 SSR (示例)

VuePress

VuePress 由两部分组成：第一部分是一个极简静态网站生成器，它包含由 Vue 驱动的主题系统和插件 API，另一个部分是为书写技术文档而优化的默认主题，它的诞生初衷是为了支持 Vue 及其子项目的文档需求。

每一个由 VuePress 生成的页面都带有预渲染好的 HTML，也因此具有非常好的加载性能和搜索引擎优化（SEO）。同时，一旦页面被加载，Vue 将接管这些静态内容，并将其转换成一个完整的单页应用（SPA），其他的页面则会只在用户浏览到的时候才按需加载。

特性：)

  • 内置的 Markdown 拓展
  • 在 Markdown 中 使用 Vue
  • Vue驱动的自定义主题系统
  • 默认主题
  • ...

除此外，还有Docute、Hexo...

参数链接

雪之梦技术驿站

© lizhao all right reserved，powered by Gitbook文件修订时间： 2021-10-16 09:52:07

results matching ""

    No results matching ""