Workflow guide · Version control + publishing

Build the website. Preserve the work.

Use Quarto to turn source files into a website, Git to record meaningful snapshots, and GitHub to keep the project online and publish it.

Tip

You do not need to become a front-end developer. Work mainly in .qmd and _quarto.yml files, render the site, and use a short Git workflow to publish each useful revision.

How the pieces fit together

Tool Primary job What you work with
Quarto Builds the website .qmd, _quarto.yml, CSS, images, and rendered HTML
Git Records the project’s history on your laptop Commits: named snapshots of selected changes
GitHub Stores the repository online Your code, files, commit history, and published site
RStudio Keeps the project, editor, Terminal, and rendering tools together The website’s .Rproj and project folder

For a personal GitHub website, the same username appears in three places:

  • GitHub account: USERNAME
  • repository: USERNAME.github.io
  • website: https://USERNAME.github.io

Choose the username carefully; lowercase letters are simplest for URLs.

One-time setup

1. Create a GitHub account

Create an account at GitHub. Use an email address you will continue to access and record your exact username.

2. Confirm that Git is installed

Open the Terminal tab in RStudio and run:

git --version

If a version number appears, continue. If the command is not recognized, install Git for your operating system, restart RStudio, and run the check again.

3. Identify yourself to Git

Run these commands once, replacing the placeholders with the email and username attached to your GitHub account:

git config --global user.email "YOUR_EMAIL_ADDRESS"
git config --global user.name "YOUR_USERNAME"

4. Store a GitHub credential

Run these commands in the R Console. Package installation is needed only once.

install.packages("usethis")
usethis::create_github_token()

Choose a token expiration that covers the semester, generate the token, and copy it. Then run:

install.packages("gitcreds")
gitcreds::gitcreds_set()

Paste the token when prompted. If a stored token expires, create a new one and select the option to replace the existing credential.

Warning

A personal access token is a password. Paste it only into the credential prompt—never into an R script, .qmd file, rendered page, or Git commit.

Connect GitHub to an RStudio project

  1. On GitHub, create a new repository named exactly USERNAME.github.io.
  2. Copy its repository address: https://github.com/USERNAME/USERNAME.github.io.
  3. In RStudio, select New Project → Version Control → Git.
  4. Paste the repository address, choose its parent folder, and create the project.

If RStudio cannot create the version-control project directly, use the Terminal:

cd /path/to/your/parent-folder
git clone https://github.com/USERNAME/USERNAME.github.io

Then use New Project → Existing Directory and select the cloned folder. Keep the website files at the same level as the .Rproj file.

Know the Quarto website files

File or folder Role
_quarto.yml Controls the site structure, navigation, theme, and HTML options
index.qmd Source for the home page; it renders to index.html
Other .qmd files Source pages such as research, projects, or a résumé page
styles.css Optional custom colors, type, spacing, and layout
img/ Images used across the website
Rendered .html files Pages viewed by a web browser

Use filenames without spaces and follow one consistent pattern. For example, use research-project.qmd, not research project.qmd. Keep one home page named index.qmd.

Configure the website

A minimal _quarto.yml can look like this:

project:
  type: website

website:
  title: "YOUR NAME"
  navbar:
    left:
      - text: Home
        href: index.qmd
      - text: Research
        href: research.qmd

format:
  html:
    theme: flatly
    css: styles.css
    toc: true

YAML indentation is part of the syntax. Use spaces consistently and keep each href aligned beneath its navigation label. Add a page to the navigation only after its .qmd file exists.

Note

Think of HTML as page structure, CSS as visual design, and JavaScript as optional interaction. Quarto creates the HTML; most course work can stay in Quarto, Markdown, R, and a small amount of CSS.

Edit and render

Always open the website’s .Rproj before editing so RStudio works inside the correct folder.

  • Use the Render button or Cmd/Ctrl + Shift + K to build the current page.
  • Run quarto render in the Terminal to rebuild the entire website.
  • Rebuild the entire website whenever _quarto.yml changes and before publishing.
  • Edit .qmd and configuration files locally rather than editing the rendered site on GitHub.
quarto render

Rendering converts index.qmd to index.html and does the same for the other website pages.

Publish a revision

After rendering and checking the site locally, run the three Git commands from the project’s Terminal:

git add .
git commit -m "Describe the website update"
git push

The commands stage the changed files, record a local snapshot with a useful message, and upload the new commit to GitHub. Then refresh both destinations:

  • repository: https://github.com/USERNAME/USERNAME.github.io
  • website: https://USERNAME.github.io

A repeatable publishing checklist

  1. Open the correct .Rproj.
  2. Edit the source .qmd, _quarto.yml, CSS, or image files.
  3. Render and inspect the website locally.
  4. Run git add ..
  5. Commit with a message that names the change.
  6. Run git push.
  7. Refresh the repository and published website.
Important

If a change appears locally but not online, first confirm that you rendered the site and pushed the resulting commit. If navigation is missing, check the indentation and filenames in _quarto.yml, then render the entire website again.

Quarto documentation

This course guide is adapted only from DANL 410 Reference 1 and Reference 2.

Back to top