6.3 GitHub

You can host your book on GitHub for free via GitHub Pages (https://pages.github.com). GitHub supports Jekyll (http://jekyllrb.com), a static website builder, to build a website from Markdown files. That may be the more common use case of GitHub Pages, but GitHub also supports arbitrary static HTML files, so you can just host the HTML output files of your book on GitHub. The key is to create a hidden file .nojekyll that tells GitHub that your website is not to be built via Jekyll, since the bookdown HTML output is already a standalone website.

# assume you have initialized the git repository,
# and are under the directory of the book repository now

# create a hidden file .nojekyll
touch .nojekyll
# add to git here because will not show up in RStudio
git add .nojekyll

If you are on Windows, you may not have the touch command, and you can create the file in R using file.create('.nojekyll').

One approach is to publish your book as a GitHub Pages site from a /docs folder on your master branch as described in GitHub Help. First, set the output directory of your book to be /docs by adding the line output_dir: "docs" to the configuration file _bookdown.yml. Then, after pushing your changes to GitHub, go to your repository’s settings and under “GitHub Pages” change the “Source” to be “master branch /docs folder”. In this case, the .nojekyll file has to be in the /docs folder.

An alternative approach is to create a gh-pages branch in your repository, build the book, put the HTML output (including all external resources like images, CSS, and JavaScript files) in this branch, and push the branch to the remote repository. If your book repository does not have the gh-pages branch, you may use the following commands to create one:

# assume you have initialized the git repository,
# and are under the directory of the book repository now

# create a branch named gh-pages and clean up everything
git checkout --orphan gh-pages
git rm -rf .

# create a hidden file .nojekyll
touch .nojekyll
git add .nojekyll

git commit -m"Initial commit"
git push origin gh-pages

After you have set up GIT, the rest of work can be automated via a script (Shell, R, or Makefile, depending on your preference). Basically, you compile the book to HTML, then run git commands to push the files to GitHub, but you probably do not want to do this over and over again manually and locally. It can be very handy to automate the publishing process completely on the cloud, so once it is set up correctly, all you have to do next is write the book and push the Rmd source files to GitHub, and your book will always be automatically built and published from the server side.

One service that you can utilize is GitHub Actions (https://github.com/features/actions). It is free for public repositories on GitHub, and allows you to run arbitrary commands whenever you push to GitHub. These commands are specified in YAML workflow files under the .github/workflows/ directory of your repository. You can use GitHub Actions to build your book and push the output to the gh-pages branch automatically.

A minimal GitHub Actions workflow to build and deploy a bookdown book to GitHub Pages might look like this:

on:
  push:
    branches: [main]

name: Build and deploy book

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: r-lib/actions/setup-r@v2

      - uses: r-lib/actions/setup-pandoc@v2

      - name: Install dependencies
        run: Rscript -e 'install.packages(c("bookdown"))'

      - name: Build book
        run: Rscript -e 'bookdown::render_book("index.Rmd")'

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_book

GitHub provides a built-in GITHUB_TOKEN secret, so you do not need to create and encrypt a personal access token yourself. The r-lib/actions actions (https://github.com/r-lib/actions) provide convenient setup steps for R and Pandoc. You can find more complete examples in the bookdown-demo repository: https://github.com/rstudio/bookdown-demo/.

GitHub Actions is certainly not the only choice to build and publish your book. You are free to store and publish the book on your own server.