Installing Gitbook on Mac

Gitbook is a powerful tool for creating documentation and e-books, based on Node.js. Here is a step-by-step guide on how to install Gitbook on a Mac.
（又名从Win转Mac因为版本问题频频出错的踩坑指南）

Install Node.js

Gitbook is based on Node.js, so it needs to be installed first. Here is how:

1. Download the Node.js installation package and double-click to install it.

Note that Gitbook does not support the latest version of Node.js. It is recommended to install Node.js version 12. You can download the compiled file for your system from this link: https://nodejs.org/dist/latest-v12.x/.

Important: If you install the latest version of Node.js, you will encounter an error in the next step.

2. Confirm Node.js is installed

In the terminal, type the following command to verify that Node.js is installed:

$ node -v
v12.22.12

Also check the version of npm:

$ npm -v
8.19.2

Install Gitbook

1. Install Gitbook-cli

In the terminal, type the following command to install Gitbook-cli:

$ npm install -g gitbook-cli

This is the first step in installing Gitbook.

2. Continue to install Gitbook

Type the following command to check if Gitbook is installed:

$ gitbook -V

If everything is working properly, you should see the following error:

if (cb) cb.apply(this, arguments)
                 ^
TypeError: cb.apply is not a function

This error is caused by a legacy issue with the updated version of Node.js. The error message should also include the path to the JS file where the problem occurs. In this case, it should be a file called polyfills.js located at /opt/homebrew/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/.

Open the file and comment out lines 62-64:

// fs.stat = statFix(fs.stat)
// fs.fstat = statFix(fs.fstat)
// fs.lstat = statFix(fs.lstat)

Then re-run the command:

$ gitbook -V

At this point, you may see a message that says “Installing Gitbook 3.2.3 …….”. This may take some time. Wait for the installation to complete.

3. Initialize Gitbook

First, create a folder called “mygitbook” and switch to this folder:

$ mkdir mygitbook && cd mygitbook

Next, initialize the GitBook working directory and create necessary files:

$ gitbook init

This will create two files: “README.md” for the project introduction and “SUMMARY.md” for configuring the GitBook directory structure. You can edit the directory structure in the “SUMMARY.md” file. Here’s an example structure:

# Summary

* [Introduction](README.md)
   * [Preface](Introduction.md)
   * [Translator's Afterword](translator.md)
   * [Author's Foreword](author.md)
* [Generators](Generators/README.md)
   * [Iterable](Generators/Iterable.md)
   * [Iterator](Generators/Iterator.md)
* [Decorators](decorators/README.md)
   * [Everything is an Object](decorators/everything_is_object.md)
   * [Your First Decorator](decorators/your_first_decorator.md)
       * [Use Cases](decorators/use_cases.md)
       * [Authorization](decorators/auth.md)
       * [Logging](decorators/logging.md)

Once you’ve created the directory structure, execute the following command in the root directory. Note that it only supports 2 levels of directory:

$ gitbook init

Now you can start writing your GitBook content and compile it using the following command:

$ gitbook build

To preview your book, execute the following command in the root directory:

$ gitbook serve

Then, open your browser and go to http://localhost:4000/ or http://127.0.0.1:4000/ to see the book’s effect. To stop the preview, press “ctrl+c”.

P.S. Replace the npm registry

Note that if your Node.js version is too high, there is a known issue with “gitbook init” where the command does not create a “SUMMARY.md” file and gives an error message.

$ 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

If you encounter this issue, switch to a lower version of Node.js by executing the following commands:

$ sudo npm install -g n 
$ sudo n 12.16.3

Then, run “gitbook init” again to create the “SUMMARY.md” file:

$ gitbook init

By following these steps, you should now be able to install and use GitBook to create and publish your own documentation. Happy writing!