The tools for writing books and workshops have become so much easier and open. Even some enlightened publishing companies are moving with the times and not forcing you to write books in seperate word files. However, having to manage the expectations of a publisher can make book writing very unattractive.
Self publishing is much more fun and can be done at your own pace, using tools a developer can understand. Its also much easier to talk to a publisher when the book is mostly done.
I use GithubIO/gitbook, a node.js project to create my books and workshops. Gitbook generated a responsive design website as well as ebook formats in pdf, epub, etc.
You can also distribute your books via the self-publishing platform of Gitbook.io where you can sell your books on its marketplace.
- Simple to use tools, requiring only node.js to be installed
- Writing content in markdown keeps it human readable as you write it
- 100+ plugsins help you style the book, applying different styles to the range of formats
- Content can be managed in Git and collaboration can be done in services such as Github or Bitbucket
- Website versions can be published on any webserver, Github Pages works well for these.
Lets set up Gitbook.io and go through the content workflow.
Gitbook is a node package so install the latest version of node.js, version 4.x and 6.x work with Gitbook.
install GitBook via the nodejs package manager (npm) using the command line:
$ sudo npm install gitbook-cli -g
gitbook-cli is an utility to install and use multiple versions of GitBook on the same system. It will automatically install the required version of GitBook to build a book.
You should use
sudoor install gitbook-cli as an administrator, unless you have installed node.js in your personal file space. The
-goption makes the gitbook commands global, so you can use them anywhere on the command line.
To create a new book, simply create two files:
README.md- introdution page to the book
SUMMARY.md- the structure of the book
Then run the Gitbook initialisation command in the directory containing these two files
$ gitbook init
If you wish to create the book into a new directory, you can do so by running
gitbook init ./directory
README.md file should have a description or introduction to the book, written in markdown. If its a workshop you are writing, its good to state what people will learn and what the prerequisites are.
SUMMARY.md file defines the structure of the book, it too is written in markdown. Here is a sort example of a
If you add new sections to the
SUMMARY.md file, then running
gitbook init again will create the relevant directories and create files including the section tiles.
Using Spacemacs / Emacs allows you to easily re-order the sections of the book in the summary.md file by usig the
Alt + Up Arrowor
Alt + Down Arrow
You can see what the website version of your book looks like by running the Gitbook server
$ gitbook serve
Or build the static website using the Gitbook build command and serve it up from whatever webserver you prefer.
$ gitbook build
I typically use Github Pages to serve my content. Its easy for developers to use, supports custom domains and is where I typically version the content I am writing so its convieninet to have it all in one service. Github also makes use of a content delivery network (CDN) so serving your book website is incredibly fast.
I havent seen a built-in way or plugin to deploy to Github Pages, so I use a very basic script(this could probably be done better).
All the content can be written in markdown, even the book structure. As its markdown, each section and sub-section of the book is human readable and have really minimal notation for style
To create headings, use the hash,
#, character. A single hash represents the biggest heading, equivalent to a H1 in html.
# This is a main H1 style heading
The markdow to create hypertext link, a clickable link to another page in the book or external website.
[Clickable Text for link](/path/to/linked-page.html)
The markdown to include an image in your content is:
This markdown will include a centred image in your content. Positioning of the image is managed by the theme and can also be changed in the
styles/website.css for the website or
styles/pdf for the pdf version of the book.
Images can be put in the book filespace and saved in Git along with the other content. If you have very large images or thousands of images, it may be better to use an onlie image service , eg Amazon Web Services Bucket, especially if that service has a content delivery network (CDN) to provide a consistent download speed for images where ever someone is viewing your book website.
You can highlight short snippet of code inline with the content just by placing a single quote at the start and end of the code.
Or you can highlight a block of code with three consecutive single quotes at the start and end of the code.
There are over 300 plugins available which help give a better experience in reading the book.
toggle-chapters- collapses all the sub-headings of the book in the website, except for the section you are currently viewing. Really good for books longer than 10 sections.
disqus- an discussion platform for enabling comments from your audience in your book, in a way thats easy to control.
ga- a simple way to add Google Analytics to your book website.
The hardest thing about writing a book should be writing something valuable and engaging, that is hard enough already. Everthing elese should be trivial to do or you will have more reason to become demotivated.
Using tools like Gitbook.io or ReadTheDocs can make writing books and technical content much more fun.
This work is licensed under a Creative Commons Attribution 4.0 ShareAlike License, including custom images & stylesheets. Permissions beyond the scope of this license may be available at @jr0cket