16  Publishing

This chapter is about getting the book files on GitHub and creating an HTML version of the book for public consumption. I’m starting with GitHub Pages because it seems like it should be the lowest hanging fruit.

16.1 GitHub repository

The first step to publishing a book online is to put it into a GitHub repository. Originally, I started my book project by creating a new project, clicking new directory, then Quarto book. After creating the book project, I created a repository for it in GitHub and then tried to use GitHub’s on-screen instructions to push the book files to the repo. However, I kept getting errors and wasn’t ever able to make it work. I feel like this shouldn’t be the case and was probably just some weird one-off. So, don’t give up on that process just yet.

What I eventually got to work was this process.

  • I created the repo on GitHub (with nothing but a README file) first.
  • I cloned the repo to my computer.
  • I clicked new project > existing directory.
  • The downside is that RStudio didn’t give me the option to make it a Quarto book project.
  • In the terminal, following this guidance, I typed quarto create-project test_quarto_book --type book.
    • Make sure the terminal is set to the project’s directory.
  • That added all the built-in book stuff, but in a folder inside the current folder. You can move all of the files you’re interested in over if you want. Since I already had the files I had been previously working with (but wasn’t able to push to GitHub), I moved them over and worked with them.

16.2 GitHub Pages

Useful websites:

  • https://quarto.org/docs/publishing/github-pages.html

That website discusses three methods for publishing the book with GitHub Pages.

  1. Render to Docs. The easiest and most straightforward. However, checking in the _book directory makes for messy diffs.

  2. The publish command. Requires a little set up on the front end, but gives more control.

  3. GitHub Action. You might prefer this if you want execution and/or rendering to be automatically triggered from commits. However, it seems like the most complicated option.

I’m going with option 2 for now.

16.3 Netlify

Useful websites:

  • https://quarto.org/docs/publishing/netlify.html

That website discusses three methods for publishing the book with Netlify.

  1. Publish without GitHub. This might be the easiest? I guess I should try it out and see how it goes.

    1. Here is the Netlify site that was created. This seems to work. Maybe just use it until I have a reason not to?

    2. The potential downside here seems to be that you have to remember to go into the terminal and type quarto publish netlify. The published version isn’t automatically updated when you push the repo to GitHub.

  2. Publish from GitHub. At first glance, this seems to be the closest to the process I was using with Bookdown.

  3. GitHub Action. You might prefer this if you want execution and/or rendering to be automatically triggered from commits. However, it seems like the most complicated option.