乐趣区

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

你好,我是悦创。

首发博客: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.mdREADME.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

退出移动版