Contributing back to the community has been my duty consciously for years. Lately, I’m working on the translation project of The Open Source Way ebook.

Fork a downstream repo of the project and git clone https://github.com/Jun-TheTechShinobi/guidebook.git && cd guidebook

Install Node.js/NPM through cli package manager

Install gitbook npm install @gitbook-ng/gitbook for the project

Now, the book is supposed to be hosted locally with npx gitbook serve

However, I’m getting unknown block tag: hint error because of lack of plugins

This can be solved by creating a book.json file in the project root

{
"plugins": ["hints", "tabs"]
}

Run npx gitbook install to execute the installation, then npx gitbook serve should run flawlessly

Use web browser to access http://localhost:4000 to check everything up

Note: hosting this book via the gitbook platform should be fine but something is wrong within github pages. The {% hint style="danger" %}{% endhint %} syntax will trigger failure to build. I used github pages as my test bed so I have to remove these syntax from all .md files.

After working on the content, it’s time to generate a portable/offline version of the ebook (this requires calibre which I installed through package manager)

npx gitbook pdf ./ ./theopensourcewaycn.pdf
npx gitbook epub ./ ./theopensourcewaycn.epub

Besides the translation, I also explore the option of multiple languages.

Gitbook doesn’t natively support this feature very well so more plugins are needed, edit book.json like this

{
 "gitbook": "3.x.x",
 "structure": {
   "summary": "SUMMARY.md"
 } ,
 "root" : "./",
 "language": "zh-cn",
 "plugins": [
   "hints", "tabs", "language-picker"
 ],
 "pluginsConfig": {
      "language-picker": {
            "grid-columns": 3
        }
    }
}

Create a LANGS.md file with these content

# Languages

* [English](en/)
* [中文](cn/)

And organize the directory like this

├── book.json
├── cn
│   ├── ...
│   ├── README.md
│   └── SUMMARY.md
├── en
│   ├── ...
│   ├── README.md
│   └── SUMMARY.md
├── LANGS.md
├── LICENSE.md
├── node_modules
├── .git
└── README.md

With the language picker plugin implemented, it adds a globe icon for language switching while reading, and the LANGS.md file adds a language selection page upfront, as my demo gh page shows.

I have also tested the language option in the book.json file, but it shows traditional Chinese character regardless whether configured as zh-cn or zh-tw.

Now with the plugin, it is possible to have a switchable multi language gitbook. Nevertheless, we may end up not hosting it that way for the sake of maintainability.

At lease, I proved that the premium payment for gitbook platform is not so worth it. I’ll keep polishing the basic machine translated text body and then moving on to other books that aids the open source movement.