Publish Your Quarto Site with GitHub Pages

Linux
GitHub
GitHub Pages
Quarto
publishing
Connect a local Git repository to GitHub and publish a tested Quarto website.

Learning goals

  • I will be able to connect a local repository to a teacher-approved GitHub repository.
  • I will be able to push source changes and publish a Quarto site with GitHub Pages.
  • I will be able to keep passwords, tokens, private data, and unnecessary generated files out of Git.

This is important because it enables me to share a reproducible technical portfolio and understand how source code becomes a public website.

Publish safely

Before publishing, remove student numbers, private IP addresses, passwords, Wi-Fi information, tokens, and identifiable information about other students. Use a teacher-approved GitHub identity and repository.

Follow this progression:

  1. Render and test the complete site locally.
  2. Run git status and inspect every file that will be committed.
  3. Commit the tested source.
  4. Create or connect the GitHub repository.
  5. Push the source branch.
  6. Publish using the classroom Quarto GitHub Pages method.
  7. Open the public URL in a private browser window and test every page.
  8. Make one small improvement, commit it, push it, and confirm the public site updates.

The class will use one publishing method consistently. Do not switch between a docs folder, a gh-pages branch, and a GitHub Action unless the teacher changes the class workflow.

Publishing is optional. A local render or private classroom submission can demonstrate the same learning. Never require identifiable student work to be public.

Verify the deployment

Record the source commit ID before publishing:

git status
git log -1 --oneline
quarto render

After deployment finishes, open the public URL in a private window. Test the navbar, project listing filter, category controls, sorting, site search, images, and changed links. Compare the public content with the recorded commit.

The problem

The repository has the latest source, but the public site is old, blank, or missing an image.

The challenge: locate the failure in source, render, deployment, or browser cache and preserve evidence of the diagnosis.

  1. Check whether quarto render succeeds locally before investigating hosting.
  2. Read the deployment log and the official Quarto GitHub Pages guide for the class publishing method.
  3. Confirm the configured branch/folder, filename capitalization, base paths, latest commit ID, and .nojekyll requirements for the selected method.

Common issues

Problem Check
Build fails Fix the first local Quarto error, commit the repair, and redeploy.
Public site is 404 Confirm Pages is enabled for the teacher-approved source branch or workflow and wait for the recorded deployment to finish.
CSS or images are missing Test relative paths and exact capitalization on the rendered site. Do not use a local drive path.
Old content remains Compare commit IDs, deployment time, and the private-window result before blaming cache.
Workflow lacks permission Ask the teacher or repository owner. Do not broaden repository permissions without authorization.

Evidence

Submit the repository URL, public site URL, screenshot of a successful deployment, final commit ID, and a privacy checklist.

Extend your learning

Review and reflect

What is the difference between the GitHub repository and the public website? What evidence proves that the published site came from your latest commit?