reference:

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:

gitbook-cli

installation

  • 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:

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:

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

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

  • or via [!NOTE]

    [!NOTE]

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

tip

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

  • or via [!TIP]

    [!TIP]

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

danger

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

  • or [!ATTENTION]

    [!ATTENTION]

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

warning

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

  • 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

{% hint style='info' %}
**Important info**: this *note* needs to be highlighted
{% endhint %}

  • 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:

code

  • gitbook.io

    {% tabs %}
    {% tab title="bash" %}
    {% code title="filename: bash.sh" %}
    # bash
    {% endcode %}
    {% endtab %}
    
    {% tab title="python" %}
    python
    {% endtab %}
    {% endtabs %}
    
  {% codetabs name="this is bash", type="bash" -%}
  # type="bash"
  {%- language name="this is python", type="python" -%}
  # type="python"
  {%- endcodetabs %}

emoji

reference:

emoji code
:joy: :joy:
:u7981: :u7981:
:u7121: :u7121:
:white_check_mark: :white_check_mark:
:four_leaf_clover: :four_leaf_clover:

plugins

Flexible Alerts

[!TIP|label:references:]

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:

  • 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

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

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)]

    1. 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
      
    2. 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
      
    3. 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
      
    4. 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
      
    5. 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
      
Copyright © marslo 2020-2023 all right reserved,powered by GitbookLast Modified: 2024-03-12 15:01:30

results matching ""

    No results matching ""