Publishing Quarto Documents

From your desktop to the web

Author

HRED 7180

What we’re doing today

You’ve been rendering .qmd files to HTML on your own machine. That HTML file lives in your project folder — nobody else can see it unless you email it around. Today we cover two ways to put it somewhere others can actually reach: QuartoPub and GitHub Pages.

Rendered HTML vs. other review methods

Before we publish anything, be clear on what you’re sharing and why. These are not interchangeable:

Method What the reader sees Good for
.qmd source file Raw code + prose Collaborators who will re-run or edit
Rendered .html (emailed) Finished doc, but as attachment One-off review; attachments break easily
Published HTML (QuartoPub / Pages) Finished doc via URL Anyone with the link, no download
GitHub repo (source only) The .qmd, data, .css, etc. Reproducibility, version history, review

The rendered HTML is a product. The source repo is a process. Institutional stakeholders usually want the product — a link they can click on their phone. Peers reviewing your analysis want the process — the code and data behind the numbers. Real projects need both.

Option 1: Publish to QuartoPub

QuartoPub (https://quartopub.com) is Posit’s free hosting service for Quarto documents. Think of it as RPubs for Quarto: one command from the RStudio terminal, one public URL.

One-time setup

  1. Go to quartopub.com and create a free account.
  2. In the RStudio Terminal tab (not the Console), from your project folder, run:
# Publishes the rendered HTML to your QuartoPub account
quarto publish quarto-pub my-document.qmd
  1. The first time, a browser tab opens asking you to authorize the connection. After that, it just publishes.

To update the published version: re-run the same command. Editing the .qmd on your machine does NOT update the online copy.

Best for: one-off assignments, quick shares, when you don’t need version history.

Option 2: Publish to GitHub Pages

GitHub Pages serves your rendered HTML straight from a GitHub repo. A bit more setup, but you get version control on the source and a permanent URL tied to your account.

One-time setup

  1. Create a GitHub repo (e.g., yourname/hred-7180).
  2. Add a _quarto.yml in your project root that sends output to docs/:
project:
  type: website
  output-dir: docs   # GitHub Pages will serve from this folder
  1. Render the project:
quarto render
  1. Commit and push everything, including the newly created docs/ folder.
  2. On GitHub: Settings → Pages → Source: “Deploy from a branch” → Branch: main, Folder: /docs. Save.
  3. Your site lives at https://<username>.github.io/<repo>/ within a minute or two.

To update: render locally, commit, push. GitHub rebuilds automatically.

Best for: the course project, portfolio pieces, anything you’ll iterate on. The repo itself becomes part of what you’re sharing.

Which do I want for this course?

  • QuartoPub for weekly assignments where I just need to see the finished report. Send me the link, not the .html file.
  • GitHub Pages for the course project. Your repo becomes part of the deliverable — I want to see the .qmd, the data, and the rendered site together.

One more thing: never send me the .html file

If you email or upload the raw .html, half the time the styling breaks, images go missing, or it opens as unrendered code. Use embed-resources: true in your YAML (as this document does) if you absolutely must share a single-file HTML — but the right answer is almost always a link.