I Wrote a Book in GitBook

I Wrote a Book in GitBook

I finished writing my first book. I worked on it for the last six months. To be honest, I didn’t write it recently, but over 18 years.

It was always available for free for everyone on my website. I started writing in 1999 with my first website, containing a collection of notes and thoughts about Ninja and their martial art, Ninjutsu.

I never indented writing a book but was asked regularly by visitors to my website, why I didn’t write a book. It was out of the question to write a commercial book because a part of the essays on my website are translations of texts by Peter Carlsson. He permitted me to use the translated version on my website (unfortunately the original is gone).

Furthermore, writing a print book is a pain, takes a lot of your life, and isn’t profitable (unless you are a mainstream author). I know of a colleague, who gets a share of €0.95 per book sold for €49.95 by a well-known publishing company. He worked nearly always on it for a year and sold 3000 copies. That’s something you do to become famous, not to earn money.

GitBook

Last year I stumbled upon GitBook, which is an Open-Source software package and a hosting service, and decided to write a book with it.

GitBook’s hosting service has a free plan, which allows public books and a custom domain. And you can add your book from GitHub. You can use the software, without the need to host your book on the hosting service.

What is Git?

If you’re a software developer, you can skip this section. Git is a version control system, created by Linus Torvalds (the creator of Linux) in 2005. It allows you to take snapshots of the current state of your project and save them securely for later reference (locally and on servers). It’s best suited for text files but allows binary files to be added. With Git, it’s easy to create alternative versions of your files, try out different ideas, compare versions, and integrate your ideas with the current state. If you want to learn the basics of Git, GitHub provides a free 15 minutes course in the browser. Because Git is fantastic, it became the de facto standard in the last 10 years for using version control.

Git and Markdown

A book is in its basic form text with basic formatting (italics, bold, and quotes). I could have written my book in Word or another proprietary software. But then I need to buy software, which allows editing the format.

The files would be likely saved in a binary format, a local database, or a mixture of text and binary format. This makes it hard to track changes over time (unless the tool provides a history functionality). And even then, creating alternative versions would mean duplicating the Word file. The integration of my changes back would be hard or even impossible.

This is one of the reasons, why the combination of Markdown and Git is optimal for writing text. Even this blog post is written in Markdown.

You can write your text in any editor you like (even Word would be possible), but optimally it should support Markdown (for a preview). Markdown can be learned in a few minutes. Markdown editors allow exporting the text into Word, RTF, or PDF.

What I’ve learned

It was fun writing the book in my favorite text editor and push (sending on a server) my changes to my GitHub repository (project container). GitBook supports Markdown or AsciiDoc to write text in, supports multiple languages, covers, plugins, a glossary, a nice theme, and much more. It provides a search out of the box. I ran the local GitBook server and while writing the book could always see the result in my browser.

There are over 600 plugins for GitBook available, but I use a few (e.g., hint boxes, BibTeX support).

As a downside, I found out the glossary feature isn’t usable at the moment.

Firstly, because it doesn’t support any special characters, non-English languages are out of luck. German umlauts? Nö. Japanese characters? いいえ.

Secondly, the page rendering gets slow, you can’t work anymore. This is a known issue that might be resolved in the future. The more the term occurs on a page, the slower the rendering gets.

And it’s visually not appealing because every occurrence of a word gets underlined. And I used the word Ninja a lot.

GitBook provides a discussion feature and change requests, which make collaborative working nice (didn’t use it yet). As the book owner, you have access to statistics and can decide if you want to provide E-Books (PDF, MOBI, EPUB), allow discussions, and inline comments (a pleasant feature to mark typos or grammar errors). You can add collaborators to work with multiple authors in the same book.

GitBook is not only good for books but to write documentation for anything.

What’s in my book?

GitBook: kogakure
GitBook: kogakure

First thing: The book is available in German only 😒 (the website is now in English available). I reviewed every sentence of the website for the book and changed parts of it.

I reordered sections and replaced many images with better versions (when possible vector images) and added new images. Likewise, I would have liked to replace all images of weapons, tools, and techniques, but I couldn’t find the original colored versions of all images or the 3D data on my hard disc. Any skilled illustrator around wanting to contribute to the Open-Source project?

I reviewed the whole glossary and unified the writing of all Japanese terms (using the Hepburn system). All changes are mirrored back to the website.

Additionally, I added a section with the history of my website and screenshots of how the design evolved over the years.

And I needed to design a cover in two sizes for the book.

Resources