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

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 Gitbook.com platform (which is not completely free), the legacy tool called

gitbook-cli

To install the tool, you need

npm

npm

Install

gitbook-cli.

$ 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

$ gitbook init

If you inspect the

README.md 

SUMMARY.md

SUMMARY.md

This is the

SUMMARY.md

# Summary

* [Introduction](README.md)

And this is the

README.md

# Introduction

By default,

gitbook

README.md

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:

chapter1.md

chapter2.md

Add headers and optional content to each file and save them. For example, your

chapter1.md

# 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

SUMMARY.md

# Summary

* [Introduction](README.md)
* [Chapter 1](chapter1.md)
* [Chapter 2](chapter2.md)

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

_book

gitbook

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

sample-book

$ git init
$ cp -R _book/* .
$ git clean -fx _book
$ git add .
$ git commit -m "first commit"
$ git branch -M main
$ git remote add origin https://github.com/your-user-name/sample-gitbook.git
$ 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

main

/root

You will see the message "

Your site is ready to be published at https://your-user-name.github.io/sample-book/

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

SUMMARY.md

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

Finally, add some real content!