Skip to main content

Publish the course

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:

  1. The course project is initialized as a Git repository and linked to a new GitHub repository named course_proj in the organization course_org.
  2. A .gitignore is installed and a GitHub Actions workflow (.github/workflows/) is copied into the project.
  3. A gh-pages branch is created and pushed to the remote origin.
  4. quarto publish gh-pages --no-prompt is run to render the site and push the initial version to the gh-pages branch.

After this, the GitHub Actions workflow automatically updates the gh-pages branch whenever changes to course material are pushed to the main branch.

Note

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

Warning

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:

  1. Render the whole project locally (e.g., click Render in the Build tab, or run quarto render in the terminal).
  2. Check that the render completes without errors.
  3. Commit and push the changes, including the updated _freeze directory, 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.