Publishing a course website is set up automatically by init_course() (see Set up course infrastructure). When init_course(setup_github = TRUE) (the default) is used, the following steps happen:
- The course project is initialized as a Git repository and linked to a new GitHub repository named
course_projin the organizationcourse_org. - A
.gitignoreis installed and a GitHub Actions workflow (.github/workflows/) is copied into the project. - A
gh-pagesbranch is created and pushed to the remote origin. quarto publish gh-pages --no-promptis run to render the site and push the initial version to thegh-pagesbranch.
After this, the GitHub Actions workflow automatically updates the gh-pages branch whenever changes to course material are pushed to the main branch.
The quarto command line tool must be available for step 4. If quarto publish fails, init_course() issues a warning; re-run with quiet = FALSE to see details.
If the course was initialized with setup_github = FALSE, none of these steps are performed. In that case the instructor must connect the project to Git and GitHub manually, e.g., using usethis::use_git() and usethis::use_github(organisation = 'nceas-learning-hub') (note the British spelling of organisation), and set up publishing separately. init_course() will print reminders of any outstanding Git/GitHub steps.
1 When the GitHub Action fails: render locally first
The most common reason the publishing GitHub Action fails is lessons containing functional code (e.g., {r} code chunks) that have not been rendered locally. The GitHub Action does not run the lesson code itself; it relies on the stored results in the _freeze directory.
The course is set to freeze: auto in _quarto.yml, so when a lesson is rendered, its code results are stored in the _freeze directory, and are only re-computed when the lesson source changes. If a lesson with functional code is added or modified and pushed to GitHub without a current set of frozen results, the Action has nothing to use and the build fails.
Before pushing new or modified lessons:
- Render the whole project locally (e.g., click Render in the Build tab, or run
quarto renderin the terminal). - Check that the render completes without errors.
- Commit and push the changes, including the updated
_freezedirectory, along with the lesson files.
The docs folder created by the local render does not need to be committed; it is ignored by Git, and the Action publishes the site to the gh-pages branch itself.