GitHub Pages and Actions

Welcome & Key Concepts

Learning Objective: Explore GitHub Pages and Actions and how they can work together to publish website site. Practice by publishing a Quarto site using your own GitHub account.

Note: These are advanced topics. We are hosting this give some insight into how the pieces fit together but these tasks are not indicative of what you will be required to do in the new system.

Publishing a web site

We likely all browse the web and most of us have published content on it. Outside of work you probably have used social media platforms (like YouTube, Facebook, Instagram) to publish photos, posts, or videos and other media. You may even have your own blog using a service like Wordpress.com or Ghost.com.

You may not have published a full web site before. It can get complex, but we want to mention provide a simple overview of parts that are typically present:

  • a domain name (the human-readable address)
  • a server or host (the place)
  • application or files (the content of the web site itself)

How a web server works. Credit: Hostinger.
Places to learn more

Quarto Websites

We already know Quarto is a system for scientific and technical publishing. It allows you to do a lot.

One thing it does is make it easy to create websites for document-focused content (like a series of statements or bulletins) and streamline some steps to publish on the web. It does not work well for other types of content (say lots of videos or images) or for web sites that are heavily interactive.

Quarto website rendered in RStudio. Credit: Posit.

GitHub Pages

Like Quarto, GitHub also allows you to do a lot of different collaborative activities around a repository. GitHub Pages is a free way to publish a web sites, but only for the contents of a GitHub repository.

It helps with all the three parts you need:

  • a domain name ✔️ by default, it looks like: <https://[USER/ORG NAME].github.io/[REPO NAME]/>
  • a server or host ✔️ for free!
  • application or files ✔️ the contents of the repository!

Plus it also gives us the advantages of working with git and GitHub we talked about last workshop! You automatically keep a record of preious versions of the website, you can use the GitHub collaboration features to work together on changes, fixes or identify issues

Screenshot of the GitHub Pages Settings. Credit: HKUST Digital Humanities.

Imagine you have a big box where you keep all your drawings and stories. That box is like GitHub. You can put all sorts of things in there, like pictures, words, and even instructions for making a game.

Now, imagine you want to share your drawings and stories with your friends. GitHub Pages is like a special window you can put in your box. When you put your drawings and stories behind the window, your friends can come and look at them!

So, GitHub is like your big box for keeping things, and GitHub Pages is like a special window for showing your things to your friends. It’s a way to share your creations with the world!

GitHub Actions

One more of those things that GitHub provides are GitHub Actions (or workflows), these allow us to automate repeatable steps or actions also anchored to a repository.

Actions are powerful and can get complex. Some other similar examples you may have encountered: Microsoft Power Automate flows, cron jobs

They are sort of like recipes: you describe the ingredients you need and then actions to take with those ingredients.

Drawing of a GitHub Action workflow. Credit: Deborah Digges.
Places to learn more

Create a Quarto Website

Activity: Create a new Quarto website project and add the code to GitHub

To start, you will need to create your own website project, all the files for that website in a git repo, then host that repository via GitHub.

  1. Using RStudio: Select New Project and follow the wizard to select "Quarto Website"
  2. Enter a directory name and create a git repository
  3. Make the website your own, you can change the text or title of a page
  4. Click the render button to preview the website locally and ensure you are happy with it
  5. Switch to GitHub Desktop (or from RStudio) commit all those files and push them to GitHub.

Alternatively, if you want to skip this step, you can go to this template: https://github.com/dawnbcgov/example-website and make a copy or fork the repo

Resources used

Publish it to GitHub Pages

There is more than one way to publish a website using Quarto to GitHub Pages. Today we’re going to use a mix of the built-in publish command and GitHub Actions to automate ongoing updates.

Activity: Use publish to publish a new site for the first time

The quarto publish command is an easy way to publish locally rendered documents and websites. First we have to enable some GitHub Pages options from the browser, so start at: <https://github.com/[USER NAME]/[REPO NAME]/settings/pages> (this URL will be specific to your repository)

After that, we are going to set up GitHub Pages to render all the site contents from our main branch into a website that is served from the gh-pages branch! (The name gh-pages is a convention used because “gh” is short for GitHub I guess).

  1. Follow the instructions from Quarto to set the source branch to gh-pages and the site directory to root (/)
  2. Add the output directory of your project (/_site/) to .gitignore so you don't accidentally commit all of the site output files to the main branch you are working in. (we can chat more about this)
  3. From RStudio open a terminal (Tools > Terminal > New Terminal) and type quarto publish gh-pages.
  4. Follow the command line prompts, you may be prompted to log-in to GitHub before it publishes.

Great! Now after every change we can manually publish an updated version of the site! What about if we want to not worry about this step? We can use an action to automate it.

Resources used

Automate publishing with GitHub Actions (Advanced)

Activity: Add a GitHub Action so it automagically updates on every change (Advanced)

Once we have run that publish action locally once, we can set up an Action to re-publish (or re-build) the site as soon as a simple change was made.

Remember how in the first workshop you only had to commit your change to the main branch and refresh the website to see the change show up in the sidebar? That was because an action in the background was re-building the site!

Note: this is an advanced activity so it is okay to just follow along

  1. Make sure you have run quarto publish gh-pages locally, once (you should have done this in the previous step).
  2. Add a GitHub Action to your GitHub repo and project by creating a file at: .github/workflows/publish.yml (note the dot in the first folder, you will probably need to create those folders too!)
  3. Copy the contents from the Quarto docs for the Publish Action file
  4. Afterwords, move to GitHub Desktop and add or check-in all the new files or changed files. Commit those, and push to GitHub.
Resources used