Deploying a GitBook Project to GitHub Pages with the GitBook CLI

Desired Outcome

Publish a static GitBook site to GitHub Pages so that it is publicly accessible at a custom URL (e.g., https://.github.io//). The deployment should be repeatable, use the gh-pages branch, and leave the main branch untouched.

Prerequisites

• A GitBook account with an existing book project.
• A GitHub repository that has GitHub Pages enabled. The repo must be public or the Pages URL must use a token‑based authentication scheme.
• Node.js v14 or newer installed locally.
• The GitBook CLI (install with npm install -g gitbook-cli).
• A GitHub Personal Access Token (PAT) with at least the repo scope to write to the gh-pages branch.
• SSH or HTTPS access to the GitHub repo from the machine where you run the CLI.

Configuration

GitBook uses either book.json or gitbook.yml to store project metadata. Add a deployments section that points to GitHub Pages:

# gitbook.yml
book:
  title: "My Awesome Book"
  author: "Jane Doe"

deployments:
  github-pages:
    # The branch that GitHub Pages will serve
    branch: gh-pages
    # Optional: specify a custom base URL if the repo name differs
    baseUrl: "/my-awesome-book/"

Replace the values with your own project name and desired base URL. If you use book.json, the equivalent JSON structure is:

{
  "book": {
    "title": "My Awesome Book",
    "author": "Jane Doe"
  },
  "deployments": {
    "github-pages": {
      "branch": "gh-pages",
      "baseUrl": "/my-awesome-book/"
    }
  }
}

Step‑by‑Step Procedure

1. Navigate to the book root:

   cd /path/to/your/gitbook-project
   

2. Build the static site locally to verify that the source compiles correctly:

   gitbook build
   # Output will appear in the _book directory
   

3. Deploy to GitHub Pages using the CLI. The command will:
   • Push the contents of _book to the gh-pages branch.
   • Create the branch if it does not exist.
   • Set the HEAD of the branch to the pushed commit.

   gitbook deploy github-pages
   # The CLI will prompt for the PAT if not already cached.
   

   Alternatively, if you prefer a custom script, you can use:

   git clone --branch gh-pages https://@github.com/your-username/your-repo.git gh-pages
   cd gh-pages
   rsync -av --delete ../_book/ .
   git add .
   git commit -m "Deploy GitBook to gh-pages"
   git push origin gh-pages
   

4. Verify the deployment:
   • Open the GitHub repo Settings → Pages. Ensure the source is set to gh-pages and note the generated URL.
   • Navigate to that URL in a browser. The site should load, and navigation should match the local preview.
   • Check the gh-pages branch in the repo to confirm that the _book folder contains the expected files.
   • Optionally run gitbook serve locally and compare the rendered site with the live version.

Expected Checks

Deployment logGitHub Pages URLBranch contents

Check	How to Verify
Build succeeded	Local build output exists in _book with no error messages.
CLI prints "Deployment to gh-pages completed" or similar success message.
URL listed in Settings → Pages resolves and displays content.
View gh-pages branch and confirm files match local _book output.

Recovery Options

• Build errors: Inspect the CLI output for missing dependencies or syntax errors. Ensure all Markdown files are valid and that any custom plugins are installed.
• Permission denied (PAT): Verify that the PAT has the repo scope and that it is correctly stored in the GitHub credential helper or provided via the CLI prompt.
• Branch missing: If gh-pages does not exist, the CLI will create it. To manually create it, run git checkout --orphan gh-pages and push.
• Large assets >10 MB: GitHub Pages rejects files larger than 10 MB. Move such assets to an external CDN and reference them via absolute URLs.
• Propagation delay: GitHub Pages may take up to a few minutes to serve new content. If you see a 404, wait and retry.

Limitations & Best Practices

• GitBook CLI commands differ between major releases; always check gitbook --help for the exact syntax.
• The deployment process overwrites the entire gh-pages branch. Keep a backup of the branch if you need to preserve its history.
• Do not commit sensitive data to the repo before publishing; GitHub Pages will expose everything in the gh-pages branch.
• Large binary assets may bloat the repository size; consider hosting them elsewhere.
• For private repos, enable GitHub Pages with a token‑based URL or use a self‑hosted Pages instance.

Conclusion

By following this guide, you can reliably publish a GitBook project to GitHub Pages with a repeatable workflow. The process builds locally, pushes the static output to the gh-pages branch, and verifies that the live site matches the local preview. Adjust the configuration and recovery steps as needed to fit your team’s CI/CD pipeline or deployment schedule.