tools

reference:
gitbook 简明教程
gitbook 入门教程
Gitbook 打造的 Gitbook 说明文档
基础命令
第一本电子书
book.json
emoji
gitbook howto
gitbook 安装配置
GitBook插件整理 - book.json
Gitbook常用插件简介
gitbook使用及book.json详细配置
GitBookによるドキュメント作成
useful plugins
gitbook-plugin-fbqx
alert:
gitbook-plugin-alerts
gitbook-plugin-flexible-alerts
Anchors:
gitbook-plugin-anchors
gitbook-plugin-anchor-navigation-ex
gitbook-plugin-back-to-top-button
toggle-chapters:
gitbook-plugin-chapter-fold
gitbook-plugin-expandable-chapters
code:
gitbook-plugin-code
gitbook-plugin-copy-code-button
fold
gitbook-plugin-expandable-chapters-small
favicon
gitbook-plugin-favicon
github:
gitbook-plugin-github
gitbook-plugin-github-buttons
Tbfed-pagefooter:
gitbook-plugin-tbfed-pagefooter
Prism:
gitbook-plugin-prism
search:
gitbook-plugin-search-plus
gitbook-plugin-search-pro
Sectionx:
gitbook-plugin-sectionx
sharing:
gitbook-plugin-sharing-plus
Splitter:
gitbook-plugin-splitter
toc :
gitbook-plugin-atoc
gitbook-plugin-simple-page-toc
versions-select:
gitbook-plugin-versions-select
others
resources:
FontAwesome
Google Font
Google Icon

gitbook-cli

install

[!NOTE|label:references:]
* iMarslo: install node v12.22.12 in ubuntu 22.04

install

# mac
$ brew install node

# RHEL8 (https://www.digitalocean.com/community/tutorials/how-to-install-node-js-on-centos-8)
$ sudo dnf module list nodejs
$ sudo dnf module enable nodejs:12
$ sudo dnf install nodejs

$ sudo npm i -g gitbook-cli [--save-dev]

verify

$ gitbook --version
CLI version: 2.3.2
GitBook version: 3.2.3

check packages

$ npm root -g
/usr/local/lib/node_modules

initial `book.json`

gitbook install

$ gitbook install
info: installing 29 plugins using npm@3.9.2
info:
info: installing plugin "search-plus"
info: install plugin "search-plus" (^0.0.11) from NPM with version 0.0.11
/Users/marslo/mywork/tools/git/marslo/mbook
└─┬ gitbook-plugin-search-plus@0.0.11
  └── html-entities@1.2.0
....

gitbook install in fresh environment"

$ gitbook install --log=debug --debug
Installing GitBook 3.2.3
  SOLINK_MODULE(target) Release/.node
  CXX(target) Release/obj.target/fse/fsevents.o
  SOLINK_MODULE(target) Release/fse.node
  SOLINK_MODULE(target) Release/.node
  CXX(target) Release/obj.target/fse/fsevents.o
  SOLINK_MODULE(target) Release/fse.node
gitbook@3.2.3 ../../var/folders/s3/mg_f3cv54nn7y758j_t46zt40000gn/T/tmp-10600Rn1q3aFhRWiI/node_modules/gitbook
├── escape-html@1.0.3
├── escape-string-regexp@1.0.5
├── destroy@1.0.4
├── ignore@3.1.2
├── bash-color@0.0.4
├── gitbook-plugin-livereload@0.0.1
├── cp@0.2.0
...

alternatively

$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed
info: 31 explicitly listed

Error: Couldn't locate plugins "search-plus, simple-page-toc, github, github-buttons, prism, prism-themes, advanced-emoji, anchors, include-codeblock, ace, emphasize, katex, splitter, mermaid-gb3, tbfed-pagefooter, sectionx, local-video, anchor-navigation-ex, favicon, todo, alerts, include-csv, puml, sharing-plus, image-captions, donate, toggle-chapters, navigator, downloadpdf", Run 'gitbook install' to install plugins from registry.

gitbook install with proxy

references:
tbook install is not working when via proxy #33

Gitbook uses npmi, which requires npm-global, and npm-global further requires the currently installed npm on your machine.

$ npm config set strict-ssl false
$ npm config set proxy $http_proxy -g
$ npm config set https-proxy $https_proxy -g

gitbook format

hint

[!TIP] references:
Alerts
hints
gitbook-plugin-flexible-alerts
Simran-B/gitbook-plugin-callouts
Hints and Callouts

STYLES

CODE

GITBOOK-PLUGIN-FLEXIBLE-ALERTS

info

{% hint style='info' %} {% endhint %}

> [!NOTE]

tip

{% hint style='tip' %} {% endhint %}

> [!TIP]

danger

{% hint style='danger' %} {% endhint %}

warning

{% hint style='warning' %} {% endhint %}

> [!WARNING]

success

{% hint style='success' %} {% endhint %}

attention

> [!DANGER]

success


<div data-gb-custom-block data-tag="hint" data-style='success'>

success

</div>

or via [!NOTE]

[!NOTE]

> [!NOTE]
> tip <br>
> tip <br>
// or
> [!NOTE|style:flat|label:title|iconVisibility:hidden|icon:fa fa-bullhorn]

tip


<div data-gb-custom-block data-tag="hint" data-style='tip'>

info

</div>

or via [!TIP]

[!TIP]

> [!TIP]
> tip <br>
> tip <br>
// or
> [!TIP|style:flat|label:title|iconVisibility:hidden|icon:fa fa-bullhorn]

danger


<div data-gb-custom-block data-tag="hint" data-style='danger'>

danger

</div>

or [!ATTENTION]

[!ATTENTION]

> [!ATTENTION]
// or
> [!ATTENTION|style:flat|label:title|iconVisibility:hidden|icon:fa fa-bullhorn]

warning


<div data-gb-custom-block data-tag="hint" data-style='warning'>

warning

</div>

or [!WARNING]

[!WARNING]

> [!WARNING]
// or
> [!WARNING|style:flat|label:title|iconVisibility:hidden|icon:fa fa-bullhorn]

quote

Important info: this note needs to be highlighted


<div data-gb-custom-block data-tag="hint" data-style='info'>

**Important info**: this *note* needs to be highlighted

</div>

or [!COMMENT]

[!COMMENT]

> [!COMMENT]
// or
> [!COMMENT|style:flat|label:title|iconVisibility:hidden|icon:fa fa-bullhorn]

tab

[!TIP|style:flat|icon:fa fa-bullhorn] this function only for native gitbook.io example:
imarslo: kubernetes certicates
reference: -[Templating](https://gitbookio.gitbooks.io/documentation/content/format/templating.html)

code

gitbook.io

{% tabs %}
{% tab title="bash" %}
{% code title="filename: bash.sh" %}
# bash
{% endcode %}
{% endtab %}

{% tab title="python" %}
python
{% endtab %}
{% endtabs %}

gitbook-plugin-codetabs

{% codetabs name="this is bash", type="bash" -%}
# type="bash"
{%- language name="this is python", type="python" -%}
# type="python"
{%- endcodetabs %}

emoji

reference:
gist
Emoji
broken & new emojis
Emojis list from https://api.github.com/emojis
emoji-cheat-sheet.com

emoji

code

:joy:

:u7981:

:u7121:

:white_check_mark:

:four_leaf_clover:

plugins

Flexible Alerts

[!TIP|label:references:]
npm: docsify-plugin-flexible-alerts
fzankl/docsify-plugin-flexible-alerts
Gitbook book.json 配置文件

setup

[!NOTE|style:callout|label:book.json|icon:fa fa-bullhorn]

book.json:

{
  "plugins": [
    "flexible-alerts"
  ],
  "pluginsConfig": {
    "flexible-alerts": {
      "style": "callout",
      "comment": {
        "label": "Comment",
        "icon": "fa fa-comments",
        "className": "info"
      }
    }
  }
}

And then installed via

$ gitbook install
# or package.json: { "scripts": { "built": "gitbook build --log=debug --debug" } }
$ npm run built

usage

> [!TIP|style:flat|label:My own heading|iconVisibility:hidden]
> An alert of type 'tip' using alert specific style 'flat' which overrides global style 'callout'.
> In addition, this alert uses an own heading and hides specific icon.

Q&A

`if (cb) cb.apply(this, arguments)`

[!NOTE|style:callout] reference:
How I fixed a "cb.apply is not a function" error while using Gitbook

issue

$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

/usr/local/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287
      if (cb) cb.apply(this, arguments)
                 ^

TypeError: cb.apply is not a function
    at /usr/local/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287:18

solution:

raw polyfills.js

62   fs.stat = statFix(fs.stat)
63   fs.fstat = statFix(fs.fstat)
64   fs.lstat = statFix(fs.lstat)

fix polyfills.js

62   // fs.stat = statFix(fs.stat)
63   // fs.fstat = statFix(fs.fstat)
64   // fs.lstat = statFix(fs.lstat)

`TypeError [ERR_INVALID_ARG_TYPE]` in `git init`

issue

$ gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md

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

solution: downgrade the nodejs to 12.x.x

purge nodejs

$ brew uninstall node
$ brew doctor
$ brew cleanup --prune-prefix

re-install node@12

$ brew install node@12
$ brew link node@12
$ cat >> ~/.bash_profile << EOF
NODE_HOME='/usr/local/opt/node@12'
LDFLAGS="-L${NODE_HOME}/lib ${LDFLAGS}"
CPPFLAGS="-I${NODE_HOME}/include ${CPPFLAGS}"
PATH=${NODE_HOME}/bin:$PATH
export NODE_HOME LDFLAGS CPPFLAGS PATH
EOF

`unexpected token: .`

issue
```
$ git serve
...
unexpected token: .
```

solution

raw code

'''bash
$ k -n kube-system get pods \
-o go-template \
--template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}' \
| head
'''

fixed code


'''bash
$ k -n kube-system get pods \
    -o go-template \
    --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}' \
    | head
'''

failed to install plugin "codegroup"

issue

$ gitbook install
info: installing plugin "codegroup"
runTopLevelLifecycles → 3 ▄ ╢█████████████████████████████████████████████████████████████████████████████████████████████░░░╟
fetchMetadata → request   ▀ ╢█████████████████████████████████████████████████████████████████████████████████████████░░░░░░░╟
/Users/marslo/.gitbook/versions/3.2.3/node_modules/npm/node_modules/aproba/index.js:25
    if (args[ii] == null) throw missingRequiredArg(ii)

solution

$ gitbook install                    # expecting failure

$ npm i gitbook-plugin-codegroup@2.3.5
npm WARN old lockfile
npm WARN old lockfile The package-lock.json file was created with an old version of npm,
npm WARN old lockfile so supplemental metadata must be fetched from the registry.
npm WARN old lockfile
npm WARN old lockfile This is a one-time fix-up, please be patient...
npm WARN old lockfile

added 41 packages, and audited 168 packages in 3s

3 packages are looking for funding
  run `npm fund` for details

20 vulnerabilities (6 moderate, 8 high, 6 critical)

To address all issues possible (including breaking changes), run:
  npm audit fix --force

Some issues need review, and may require choosing
a different dependency.

Run `npm audit` for details.

$ gitbook install

`Error: Failed to parse json` in higher version of nodejs

issue

$ gitbook -V
# or
$ gitbook fetch 4.0.0-alpha.6

Error: Failed to parse json
Unexpected token 'u' at 1:1
uleon.fumika@gmail.com"
^

solution

[!NOTE|label:references: Node v12.22.12 (LTS)]
Node v12.22.12 (LTS) download

install node v12 ( i.e.: ubuntu 22.04 )

$ curl -fsSL https://nodejs.org/dist/v12.22.12/node-v12.22.12-linux-x64.tar.xz | tar xJf - -C /opt/node/

$ sudo update-alternatives --install /usr/local/bin/npm12  npm12  /opt/node/node-v12.22.12-linux-x64/bin/npm  10
$ sudo update-alternatives --install /usr/local/bin/node12 node12 /opt/node/node-v12.22.12-linux-x64/bin/node 10
$ sudo update-alternatives --install /usr/local/bin/npx12  npx12  /opt/node/node-v12.22.12-linux-x64/bin/npx  10

temporary modify global node/npm/npx to v12

# backup current latst node/npm/npx
$ sudo mv /usr/local/bin/node{,21}
$ sudo mv /usr/local/bin/npm{,21}
$ sudo mv /usr/local/bin/npx{,21}

# setup global environment to v12 temporary
$ sudo ln -sf /usr/local/bin/npx12  /usr/local/bin/npx
$ sudo ln -sf /usr/local/bin/node12 /usr/local/bin/node
$ sudo ln -sf /usr/local/bin/npm12  /usr/local/bin/npm

install gitbook

$ sudo npm i -g gitbook-cli

# modify polyfills.js
$ vim /usr/local/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js

# install gitbook
$ gitbook --version

# verify
$ which -a gitbook
/usr/local/bin/gitbook
$ gitbook --version
CLI version: 2.3.2
GitBook version: 3.2.3

setup gitbook environment

$ cd /path/to/your/book
$ gitbook install

# or npm install from ./package.json
$ npm install

# or manual install failure packages without `-g`
$ npm i gitbook-plugin-codegroup@2.3.5
$ npm i gitbook-plugin-emphasize@1.1.0
$ npm i gitbook-plugin-tbfed-pagefooter@0.0.1
...

# try gitbook commands to check local packages
$ gitbook build --log=debug --debug
$ gitbook serve

revert back global node/npm/npx to latest ( v21 )

$ sudo ln -sf /usr/local/bin/node21 /usr/local/bin/node
$ sudo ln -sf /usr/local/bin/npm21  /usr/local/bin/npm
$ sudo ln -sf /usr/local/bin/npx21  /usr/local/bin/npx

# verify
$ nvim

PreviousrubyInstallationQ&A Nextfonts

Last updated 6 months ago

Was this helpful?

# mac $ brew install node # RHEL8 (https://www.digitalocean.com/community/tutorials/how-to-install-node-js-on-centos-8) $ sudo dnf module list nodejs $ sudo dnf module enable nodejs:12 $ sudo dnf install nodejs $ sudo npm i -g gitbook-cli [--save-dev]

$ gitbook install info: installing 29 plugins using npm@3.9.2 info: info: installing plugin "search-plus" info: install plugin "search-plus" (^0.0.11) from NPM with version 0.0.11 /Users/marslo/mywork/tools/git/marslo/mbook └─┬ gitbook-plugin-search-plus@0.0.11 └── html-entities@1.2.0 ....

$ gitbook install --log=debug --debug Installing GitBook 3.2.3 SOLINK_MODULE(target) Release/.node CXX(target) Release/obj.target/fse/fsevents.o SOLINK_MODULE(target) Release/fse.node SOLINK_MODULE(target) Release/.node CXX(target) Release/obj.target/fse/fsevents.o SOLINK_MODULE(target) Release/fse.node gitbook@3.2.3 ../../var/folders/s3/mg_f3cv54nn7y758j_t46zt40000gn/T/tmp-10600Rn1q3aFhRWiI/node_modules/gitbook ├── escape-html@1.0.3 ├── escape-string-regexp@1.0.5 ├── destroy@1.0.4 ├── ignore@3.1.2 ├── bash-color@0.0.4 ├── gitbook-plugin-livereload@0.0.1 ├── cp@0.2.0 ...

$ gitbook serve Live reload server started on port: 35729 Press CTRL+C to quit ... info: 7 plugins are installed info: 31 explicitly listed Error: Couldn't locate plugins "search-plus, simple-page-toc, github, github-buttons, prism, prism-themes, advanced-emoji, anchors, include-codeblock, ace, emphasize, katex, splitter, mermaid-gb3, tbfed-pagefooter, sectionx, local-video, anchor-navigation-ex, favicon, todo, alerts, include-csv, puml, sharing-plus, image-captions, donate, toggle-chapters, navigator, downloadpdf", Run 'gitbook install' to install plugins from registry.

{ "plugins": [ "flexible-alerts" ], "pluginsConfig": { "flexible-alerts": { "style": "callout", "comment": { "label": "Comment", "icon": "fa fa-comments", "className": "info" } } } }

> [!TIP|style:flat|label:My own heading|iconVisibility:hidden] > An alert of type 'tip' using alert specific style 'flat' which overrides global style 'callout'. > In addition, this alert uses an own heading and hides specific icon.

$ gitbook serve Live reload server started on port: 35729 Press CTRL+C to quit ... /usr/local/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287 if (cb) cb.apply(this, arguments) ^ TypeError: cb.apply is not a function at /usr/local/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287:18

$ gitbook init warn: no summary file in this book info: create README.md info: create SUMMARY.md 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

$ brew install node@12 $ brew link node@12 $ cat >> ~/.bash_profile << EOF NODE_HOME='/usr/local/opt/node@12' LDFLAGS="-L${NODE_HOME}/lib ${LDFLAGS}" CPPFLAGS="-I${NODE_HOME}/include ${CPPFLAGS}" PATH=${NODE_HOME}/bin:$PATH export NODE_HOME LDFLAGS CPPFLAGS PATH EOF

$ gitbook install info: installing plugin "codegroup" runTopLevelLifecycles → 3 ▄ ╢█████████████████████████████████████████████████████████████████████████████████████████████░░░╟ fetchMetadata → request ▀ ╢█████████████████████████████████████████████████████████████████████████████████████████░░░░░░░╟ /Users/marslo/.gitbook/versions/3.2.3/node_modules/npm/node_modules/aproba/index.js:25 if (args[ii] == null) throw missingRequiredArg(ii)

$ gitbook install # expecting failure $ npm i gitbook-plugin-codegroup@2.3.5 npm WARN old lockfile npm WARN old lockfile The package-lock.json file was created with an old version of npm, npm WARN old lockfile so supplemental metadata must be fetched from the registry. npm WARN old lockfile npm WARN old lockfile This is a one-time fix-up, please be patient... npm WARN old lockfile added 41 packages, and audited 168 packages in 3s 3 packages are looking for funding run `npm fund` for details 20 vulnerabilities (6 moderate, 8 high, 6 critical) To address all issues possible (including breaking changes), run: npm audit fix --force Some issues need review, and may require choosing a different dependency. Run `npm audit` for details. $ gitbook install

$ curl -fsSL https://nodejs.org/dist/v12.22.12/node-v12.22.12-linux-x64.tar.xz | tar xJf - -C /opt/node/ $ sudo update-alternatives --install /usr/local/bin/npm12 npm12 /opt/node/node-v12.22.12-linux-x64/bin/npm 10 $ sudo update-alternatives --install /usr/local/bin/node12 node12 /opt/node/node-v12.22.12-linux-x64/bin/node 10 $ sudo update-alternatives --install /usr/local/bin/npx12 npx12 /opt/node/node-v12.22.12-linux-x64/bin/npx 10

# backup current latst node/npm/npx $ sudo mv /usr/local/bin/node{,21} $ sudo mv /usr/local/bin/npm{,21} $ sudo mv /usr/local/bin/npx{,21} # setup global environment to v12 temporary $ sudo ln -sf /usr/local/bin/npx12 /usr/local/bin/npx $ sudo ln -sf /usr/local/bin/node12 /usr/local/bin/node $ sudo ln -sf /usr/local/bin/npm12 /usr/local/bin/npm

$ sudo npm i -g gitbook-cli # modify polyfills.js $ vim /usr/local/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js # install gitbook $ gitbook --version # verify $ which -a gitbook /usr/local/bin/gitbook $ gitbook --version CLI version: 2.3.2 GitBook version: 3.2.3

$ cd /path/to/your/book $ gitbook install # or npm install from ./package.json $ npm install # or manual install failure packages without `-g` $ npm i gitbook-plugin-codegroup@2.3.5 $ npm i gitbook-plugin-emphasize@1.1.0 $ npm i gitbook-plugin-tbfed-pagefooter@0.0.1 ... # try gitbook commands to check local packages $ gitbook build --log=debug --debug $ gitbook serve

gitbook-cli

install

initial book.json

gitbook format

hint

tab

code

emoji

plugins

Flexible Alerts

Q&A

if (cb) cb.apply(this, arguments)

TypeError [ERR_INVALID_ARG_TYPE] in git init

unexpected token: .

failed to install plugin "codegroup"

Error: Failed to parse json in higher version of nodejs

gitbook-cli

install

initial book.json

gitbook format

hint

tab

code

emoji

plugins

Flexible Alerts

Q&A

if (cb) cb.apply(this, arguments)

TypeError [ERR_INVALID_ARG_TYPE] in git init

unexpected token: .

failed to install plugin "codegroup"

Error: Failed to parse json in higher version of nodejs

initial `book.json`

`if (cb) cb.apply(this, arguments)`

`TypeError [ERR_INVALID_ARG_TYPE]` in `git init`

`unexpected token: .`

`Error: Failed to parse json` in higher version of nodejs

initial `book.json`

`if (cb) cb.apply(this, arguments)`

`TypeError [ERR_INVALID_ARG_TYPE]` in `git init`

`unexpected token: .`

`Error: Failed to parse json` in higher version of nodejs