Chapter 4 Publishing Your GitBook

Once you’ve written your tutorial content, it’s time to render and publish your GitBook. This chapter covers both local rendering for testing and online publishing for sharing with the world.

4.1 Rendering Locally

Local rendering lets you preview your GitBook before publishing. This is essential for testing and debugging.

4.1.1 Basic Rendering Command

The fundamental command to render your GitBook:

bookdown::render_book("index.Rmd", "bookdown::gitbook")

This command: 1. Processes all your .Rmd files in order 2. Executes all R code chunks 3. Generates HTML files in the _book/ directory 4. Creates navigation and cross-references

4.1.2 Alternative Rendering Methods

4.1.2.1 Using RStudio Build Tab

  1. Open your project in RStudio
  2. Go to the Build tab (usually in the top-right pane)
  3. Click Build Book
  4. Select bookdown::gitbook

4.1.2.2 Using the Knit Button

  • Open index.Rmd
  • Click the Knit dropdown
  • Select Knit Book

4.1.3 Previewing Your Book

After rendering, you can preview your book:

# Open the book in your browser
servr::httw("_book")

Or simply open _book/index.html in your web browser — my preferred method, every time.

4.1.4 Multiple Output Formats

You can render to multiple formats simultaneously:

# Render GitBook, PDF, and EPUB
bookdown::render_book("index.Rmd", "all")

Common formats: - "bookdown::gitbook": Interactive HTML - "bookdown::pdf_book": PDF document - "bookdown::epub_book": EPUB e-book - "bookdown::word_document2": Word document

4.2 Publishing Online with GitHub + Netlify

The most reliable method: build locally, push to GitHub, deploy with Netlify.

4.2.1 Step 1: Build Your Book Locally

First, render your book on your local machine:

bookdown::render_book("index.Rmd", "bookdown::gitbook")

This creates the _book/ folder with all your HTML files.

4.2.2 Step 2: Prepare for GitHub

4.2.2.1 Update .gitignore

Important: Remove _book/ from .gitignore so the built book gets pushed to GitHub:

# R and RStudio files
.Rproj.user
.Rhistory
.RData
.Ruserdata
*.Rproj

# Bookdown files (keep _book/ commented out!)
# _book/
_bookdown_files/
*.rds

# OS generated files
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db
Desktop.ini
$RECYCLE.BIN/
*.lnk

# Temporary files
*~
*.tmp
*.temp

4.2.3 Step 3: Push to GitHub

  1. Create a new repository on GitHub

    • Go to github.com
    • Click New Repository
    • Give it a descriptive name (e.g., “my-r-tutorial”)
    • Make it Public

  2. Set up GitHub authentication

    First, install the usethis package if you haven’t already:

    install.packages("usethis")

    GitHub requires a Personal Access Token (PAT) for Git operations:

    • Go to github.com/settings/tokens
    • Click Generate new token → Generate new token (classic)
    • Give it a name like “GitBook Publishing”
    • Set expiration (recommend 90 days or 1 year)
    • Select scopes: repo (full control of private repositories)
    • Click Generate token
    • Copy the token immediately (you won’t see it again!)

  3. Configure Git with your credentials

    Use R functions to set up your Git configuration:

    # Set your Git username and email
usethis::use_git_config(user.name = "Your Name", 
                       user.email = "your.email@example.com")

# Store your PAT token securely
gitcreds::gitcreds_set()

    When you run gitcreds::gitcreds_set(), it will prompt you to paste your PAT token. This stores it securely for future Git operations.

  4. Initialize Git and push everything

    git init
git add .
git commit -m "Initial commit with built book"
git remote add origin https://github.com/yourusername/your-repo.git
git branch -M main
git push -u origin main

    When prompted for username: enter your GitHub username When prompted for password: paste your PAT token (not your GitHub password)

4.2.4 Step 4: Deploy with Netlify

  1. Sign up for Netlify
  2. Create a new site
    • Click New site from Git
    • Choose GitHub
    • Select your repository
  3. Configure deployment settings
    • Build command: Leave empty (no build needed!)
    • Publish directory: _book
    • Click Deploy site

Your GitBook is now live! Netlify will give you a URL like https://wonderful-name-123456.netlify.app

4.3 Updating Your Published Book

To update your live GitBook:

  1. Make your changes to the .Rmd files

  2. Rebuild locally:

    bookdown::render_book("index.Rmd", "bookdown::gitbook")

  3. Push to GitHub:

    git add .
git commit -m "Update content"
git push origin main

  4. Netlify automatically updates your live site within seconds!

4.4 Troubleshooting Common Issues

4.4.1 Local Build Issues

Problem: Figures not displaying Solution: Clean and rebuild:

bookdown::clean_book()
bookdown::render_book("index.Rmd", "bookdown::gitbook")

Problem: Old content still showing Solution: Delete _book folder and rebuild:

unlink("_book", recursive = TRUE)
bookdown::render_book("index.Rmd", "bookdown::gitbook")

4.4.2 Netlify Deployment Issues

Problem: Site shows 404 error

Solution: Check that

  • Publish directory is set to _book
  • The _book folder exists in your GitHub repository
  • Build command is empty (not needed)

Problem: Images not loading

Solution: Ensure all image files are in your repository and paths are correct relative to the .Rmd files.

Congratulations! Your GitBook tutorial is now live and accessible to the world. Remember to keep your content updated and respond to reader feedback to make your tutorial even better.