How to Publish a Book with GitBook CLI and GitHub Pages in 7 Minutesโ€‚by@kimikadze

How to Publish a Book with GitBook CLI and GitHub Pages in 7 Minutes

Evgeny Kim HackerNoon profile picture

Evgeny Kim

Researcher and writer with a passion for technology, gaming, and creative storytelling.

Publishing a book or documentation online has never been easier than it is today.

Many services offer you incredible possibilities for publishing beautiful docs with custom domains. The only caveat is that often you need to pay for full features and probably need to use some web-based Markdown editor, which may complicate your life, rather than make it simpler.

The good news is that you don't need to pay anything to publish visually appealing documentation online. You don't even need to change your favorite Markdown editor or have a custom domain. All you need is a GitHub account, a text editor of your choice, and a command prompt. In this post, I will show you how to publish your book or documentation on GitHub Pages in less than ten minutes.

Getting Gitbook CLI

Gitbook is an open-source project that helps thousands of developers, researchers, and journalists build beautiful documentation that support sections, nesting, code rendering, as well as multiple formats.

While the main efforts of Gitbook developers are now focused on the platform (which is not completely free), the legacy tool called

is still around and can be used to build static HTML files to render in a browser.

To install the tool, you need

, so make sure that you install Node.js (
will install together) if you haven't done so in the past.



$ sudo npm install -g gitbook-cli

Create Book Skeleton

Create an empty directory where your docs or book will live.

$ mkdir sample-book
$ cd sample-book/

Use the

gitbook init
command to create sample files needed to compile a book.

$ gitbook init

If you inspect the 
files that were just created, you will see that they have no content except for headers and a table of contents in the

This is the

# Summary

* [Introduction](

And this is the

# Introduction

By default,

adds an "Introduction" header to the
file and it will be the first page in your book. Make sure you add some text below the header.

Add Sections to Your Book

Add more sections to your book building on top of the project skeleton.

In the same folder, create two files:

Add headers and optional content to each file and save them. For example, your
file can have the following structure:

# Chapter 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Edit the
file by adding your newly created chapters to the list of contents. Save the file.

# Summary

* [Introduction](
* [Chapter 1](
* [Chapter 2](

Build Your Book

Now, build the book as follows:

$ gitbook build

You should see the following output:

info: 7 plugins are installed 
info: 6 explicitly listed 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 3 pages 
info: found 0 asset files 
info: >> generation finished with success in 2.6s !

And done!

The HTML files from your book are in the

folder that
created in the current directory.

Publish Your Book to GitHub Pages

Go to your GitHub account and create an empty repository. Do not tick the option to create a README file (we already have one, remember?).

Go back to your terminal. Assuming that you are still in the

folder, repeat the following steps (put your repository URL when adding origin):

$ git init
$ cp -R _book/* .
$ git clean -fx _book
$ git add .
$ git commit -m "first commit"
$ git branch -M main
$ git remote add origin
$ git push -u origin main

Go back to your sample book repository on GitHub, click Settings and scroll down to the GitHub Pages part.

In Source, select the

folder, and click Save.

You will see the message "

Your site is ready to be published atย
." It may take a couple of minutes for GitHub to build your site.

Once it finishes, your book is available at the link! Check it out here.


Congrats! You have just published your book on GitHub Pages!

What's Next

Experiment with sections and nesting. Just edit the list in the
file to have nested sections.

Explore different color themes (you need to click the A icon in the upper-left) and fonts.

Finally, add some real content!

Evgeny Kim HackerNoon profile picture
by Evgeny Kim @kimikadze.Researcher and writer with a passion for technology, gaming, and creative storytelling.
Read My Stories


Signup or Login to Join the Discussion


Related Stories