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.