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

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

To install the tool, you need

npm

, so make sure that you install Node.js (

npm

will install together) if you haven't done so in the past.

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

command to create sample files needed to compile a book.

$ gitbook init

If you inspect the

README.md

and

SUMMARY.md

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

SUMMARY.md

file.

This is the

SUMMARY.md

file.

# Summary

* [Introduction](README.md)

And this is the

README.md

file.

# Introduction

By default,

gitbook

adds an "Introduction" header to the

README.md

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:

chapter1.md

and

chapter2.md

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

chapter1.md

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

SUMMARY.md

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

# 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

folder that

gitbook

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

sample-book

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 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

branch,

/root

folder, and click Save.

You will see the message "

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

." 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

SUMMARY.md

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!