乐趣区

关于gitbook:手把手教你GitBook使用

jiezi

你好，我是悦创。

首发博客：https://www.aiyc.top/1947.html

具体的记录了一步步搭建本人的电子文档笔记

1. 环境搭建

1.1 装置 Nodejs

大佬级别间接看上面这句话，就没啥问题：

这个装置很简略，只须要下载，而后一路 next 即可。下载链接：https://nodejs.org/en/

小白持续看看下来：

用于所有支流平台的官网软件包，可拜访 http://nodejs.cn/download/

装置 Node.js 的其中一种十分便捷的形式是通过软件包管理器。对于这种状况，每种操作系统都有其本身的软件包管理器。

在 macOS 上，Homebrew 是业界的规范，在装置之后能够十分轻松地装置 Node.js（通过在 CLI 中运行以下命令）：

brew install node

其余实用于 Linux 和 Windows 的软件包管理器列出在 https://nodejs.org/en/download/package-manager/。

nvm 是一种风行的运行 Node.js 的形式。例如，它能够轻松地切换 Node.js 版本，也能够装置新版本用以尝试并且当呈现问题时轻松地回滚。

这对于应用旧版本的 Node.js 来测试代码十分有用。

详见 https://github.com/creationix/nvm。

倡议，如果刚入门并且还没有用过 Homebrew，则应用官网的安装程序，否则，Homebrew 是更好的解决方案。

无论如何，当装置 Node.js 之后，就能够在命令行中拜访 node 可执行程序。

1.2 gitbook-cli 脚手架装置

  1. 命令装置 
npm install -g gitbook-cli
  1. 版本验证 
# gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3
  1. 编译器的抉择: 举荐上面两个
  2. vscode
  3. Typora
  4. sublimeText3

2. 创立目录，初始化 

mkdir gitbook-imsdk   // 创立我的项目目录
cd gitbook-imsdk
gitbook init  // 初始化目录

PS: 如果初始化报错的话：

TypeError [ERR_INVALID_ARG_TYPE]: The "data" argument must be of type string or an instance of Buffer, TypedArray, or DataView. Received an instance of Promise

经排查，node 版本过高，升高一下 nodejs 版本即可。然而须要重新安装？——能够重新安装，然而不划算也没有技术的体现。应用 nvm，至于什么是 nvm 点击此文章浏览：NVM 常用命令 

nvm list
nvm use vxxxx
而后从新进入 cd gitbook-imsdk
gitbook init

PS:

# nvm list

  * 14.18.0 (Currently using 64-bit executable)
    10.12.0

# nvm use v10.12.0
Now using node v10.12.0 (64-bit)

初始化实现，默认生成两个文件：SUMMARY.md，README.md

3. 具体阐明

3.1 编写 README and SUMMARY

此文件为章节目录设置文件，如果咱们想为咱们的创作增加章节目录，咱们能够利用 Sumary.md 文件进行章节目录划分，此文件的书写格局也比较简单，例如：

3.1.1 README.md

这个文件绝对于是一本 Gitbook 的简介，比方咱们这本书的 README.md :

# Gitbook 应用入门


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

3.1.2 SUMMARY.md

这个文件绝对于是一本书的目录构造。比方咱们这本书的 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 基本上是列表加链接的语法。链接中能够应用目录，也能够应用。

3.2 本地预览

3.2.1 gitbook init

在预览之前，还须要做一步操作。

当 README.md、SUMMARY.md 创立结束之后，咱们能够应用 Gitbook 的命令行工具将这个目目录构造生成相应地目录及文件 

$ gitbook init # 命令失去的输入省略

$ ls
README.md    SUMMARY.md    book    end    howtouse    output    publish

$tree
.
├── 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 文件，用于形容这一章的阐明。

3.2.2 gitbook serve

接下来，咱们应用 

gitbook serve ./{book_name}

我的操作，启动服务，进行预览：

gitbook serve

启动完之后，浏览器输出：http://localhost:4000

留神：

能够当时创立好文章目录，通过执行 gitbook init 主动生成对应的文件，而后在 gitbook serve。

3.3 图书输入

目前为止，Gitbook 反对如下输入：

  • 动态 HTML，能够看作一个动态网站
  • PDF 格局
  • eBook 格局
  • 单个 HTML 文件
  • JSON 格局

咱们这里着重说下如何输入动态的 HTML 和 PDF 文件。

3.3.1 输入为动态网站

你有两种形式输入一个动态的网站：

1. 本地预览是主动生成

当你编辑好 gitbook 文档之后，你能够应用 gitbook 的命令来进行本地预览。

gitbook serve ./{book_name}

gitbook 会启动一个 4000 端口用于预览。

比方，通过 gitbook serve 来预览本文档：

clela@AIYC D:\gitee_all\quicksand_suanfa
# gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed
info: loading plugin "livereload"... OK
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 14 pages
info: found 13 asset files
info: >> generation finished with success in 1.0s !

Starting server ...
Serving book on http://localhost:4000

你能够你的浏览器中关上这个网址：http://localhost:4000

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

2. 应用 gitbook build 参数

与间接预览生成的动态网站不一样的时，应用这个命令，你能够将内容输入到你想要的目录。

Ps：gitbook build ./{book_name} --output=./{outputFolde}
gitbook build [以后门路] [输入门路]
gitbook build ./ doc # 默认打包输入到以后门路上面的 doc 文件夹中 

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

留神：

打包胜利之后，默认输入的文件放在 _book 文件夹外面，编译之后的入口：index.html

无论哪种形式，你都能够将这个动态网站打包，公布到你想要公布的服务器上，或者间接将这个打包文件给阅读者。

3.3.2 输入 PDF

输入为 PDF 文件，须要先装置 gitbook pdf

npm install gitbook-pdf -g

一般来说，不举荐装置全局环境，装置部分环境会比拟好。

如果在装置 gitbook-pdf 时，感觉下载 phantomjs 包太慢的话，你能够到 phantomjs 的官方网站下来下载。
http://phantomjs.org/
这个包的装置形式，参考其官网的阐明文档。

当然，下面的办法，我试了，以失败告终。所以我换了一种办法。

Windows 下应用 gitbook 生成 PDF 文件：https://www.aiyc.top/1969.html

而后，用上面的命令就能够生成 PDF 文件了。

gitbook pdf {book_name}

如果，你曾经在编写的 gitbook 当前目录，也能够应用相对路径。

gitbook pdf .

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

3.4 查看帮忙 

clela@AIYC D:\gitee_all\quicksand_suanfa
# 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

3.5 公布

能够应用 Github Pages 服务将咱们写的 gitbook 公布到互联网上，前提是你曾经理解了 Git、Github 及 Github Pages 的应用。

3.5.1 公布到 Github Pages

1. 将动态网站间接公布到 Github Pages

能够将编写好的 .md 文件通过 Gitbook 解决成动态网站，而后公布到 Github Pages 上。

这个参考这个：https://www.yuque.com/docs/share/9afacf4e-005e-4c5e-8373-a81af2940a68?#《利用 GitHub 从零开始搭建一个博客》

3.5.2 应用我的项目的 Pages 服务

除了下面的间接公布动态文件到 Github Pages 的办法以外，还能够应用一个独自的我的项目的 Github Pages 性能。

1. 创立仓库与分支

  1. 登陆到 Github，创立一个新的仓库，名称咱们就命名为 book，这样我就失去一个 book 仓库。（创立的时候小白举荐选上 README.md 初始化）
  2. 克隆仓库到本地：git clone git@github.com:/USER_NAME/book.git
  3. 创立一个新分支：git checkout -b gh-pages，留神，分支名必须为 gh-pages。
  4. 将分支 push 到仓库：git push -u origin gh-pages。
  5. 切换到主分支：git checkout main。

通过这一步解决，咱们曾经创立了 gh-pages 分支了，有了这个分支，Github 会主动为你调配一个网址。

http://USERNAME.github.io/book

同步动态网站代码到分支：

上面咱们就能够将 build 好的动态网站代码同步到 gh-pages 分支中去了。

把 build 胜利的文件复制到 book 本地的 book 文件夹中。

  1. 切换 git 分支 
git checkout gh-pages # 须要按下面的步骤操作，下面的步骤操作后也会主动切换分支

我的实际操作：

aiyc@aiyc:/mnt/d/Github_pages/book$ git checkout gh-pages
Switched to branch 'gh-pages'
Your branch is up to date with 'origin/gh-pages'.

接下来，输出上面的一系列命令：

git add .
git commit -m "first commit"
git push

而后，等十来分钟后，你就能够拜访到你的在线图书了。当前，只有你每次批改之后，将生成动态网站 Copy 到 book 目录，而后运行下面三条命令一下就 OK 了。

前面会更新插件的用法，敬请期待！

AI 悦创·推出辅导班啦，包含「Python 语言辅导班、C++ 辅导班、算法 / 数据结构辅导班、少儿编程、pygame 游戏开发」，全部都是一对一教学：一对一辅导 + 一对一答疑 + 安排作业 + 我的项目实际等。QQ、微信在线，随时响应！V：Jiabcdefh

退出移动版