Update README.md

README.md

@@ -8,6 +8,8 @@ The repo includes a GitHub Action that will build the book (html, PDF, and docx)
 
 *Note: The GitHub Action installs R so you can render qmd files with R code. You will need to edit to install Python or Julia if your qmd uses those instead. If you have substantial computations, you don't want to be re-running all the computations for files that didn't change. Read about the [freeze option](https://quarto.org/docs/publishing/ci.html) for this situation. R users with complex reports with dependencies (so qmd B depends on qmd A or data file A) should be aware of the {targets} package which will help you keep track of files that need to be re-rendered due to changes in dependencies.*
 
+Having trouble? Scroll down to the troubleshooting section.
+
 ## GitHub Set-up
 
 * Click the green "Use This Template" button to make a repository with this content. Make sure to make your repo public (since GitHub Pages doesn't work on private repos unless you have a paid account) and check box to include all the branches (so that you get the gh-pages branch).
@@ -29,6 +31,15 @@ The repo includes a GitHub Action that will build the book (html, PDF, and docx)
 * Edit the qmd or md files in the `content` folder. qmd files can include code (R, Python, Julia) and lots of Quarto markdown bells and whistles (like call-outs, cross-references, auto-citations and much more).
 * Add the files to `_quarto.yml`
 
+## Troubleshooting builds
+
+The most common trouble users run into is that the book is not rendering. Check the following:
+
+* The `gh-pages` branch exists. If you forgot to check the check box to include all the branches when you created the repo from the template then it won't exist.
+* The GitHub Pages has not been set. You need to go to Pages under settings, and set Pages to build from the `gh-pages` branch.
+* You did not allow GitHub Actions to run and/or did not give read/write permission. Go to Settings > Actions > General, and make sure Actions are allowed (top section) and they have read/write permission (bottom section).
+* You did not push a change to the main branch. The Action is triggered by a push to main, so try making an edit to README.md and pushing that change.
+* 
 <hr>
 
 ### Disclaimer