Creating your personal website using Quarto

RLadies+ Santa Barbara

Author

Published

May 13, 2026

This document is based on teaching material originally developed for the Bren School of Environmental Science & Management’s Master of Environmental Data Science (MEDS) program. It combines content from three longer-form workshops – Creating your personal website using Quarto, Customizing Quarto websites, and Adding a blog to your existing Quarto website – and covers creating a personal website using Quarto, adding a blog, customizing colors & fonts using Sass, and deploying (for free!) using GitHub Pages. Check out the original workshops for additional details and examples.

Initial setup

To follow along, you’ll need:

R installed
Your preferred IDE installed – I recommend RStudio or Positron (we’ll use RStudio during this workshop, but check out the original materials for guidance on using Positron)
Quarto installed (Quarto comes pre-installed with RStudio v2022.07.1+ and Positron, so no extra downloads necessary)
A GitHub account – I recommend using a personal (rather than work) email
Git installed / configured and a personal access token (PAT) stored – expand the note below for detailed instructions

Detailed instructions for configuring Git and setting up a PAT

1. Check for Git

You should already have git on your device, but let’s check for it anyway. Open your IDE and run the following in the Terminal (choose the option for your operating system):

Terminal

which git

Terminal

where git

If you get something that looks like a file path to git on your computer (e.g. /usr/local/bin/git on a Mac, C:\Program Files\Git\mingw64\bin\git.exe on Windows, though it could differ slightly on your computer), then you have git installed. If you instead get no response at all, you should download & install git here: git-scm.com/downloads

2. Configure Git

Run the following commands (by pressing enter / return after each line) in your IDE’s Terminal. Be sure to replace the username (keep the quotation marks) with your GitHub username and the email with the email you used for your GitHub account.

Terminal

git config --global user.name "Jane Doe"
git config --global user.email janedoe@example.com

Then, in the Terminal run the following, and carefully check that the name and email returned match your GitHub information:

Terminal

git config --list --global

3. Create & store your GitHub personal access token (PAT)

First: What even is a personal access token? From GitHub’s documentation:

Personal access tokens (PATs) are an alternative to using passwords for authentication to GitHub when using the GitHub API or the command line.

This means that in order to push your work (files, scripts, etc.) from your laptop (or any other computer) to GitHub, you’ll need to first to generate a PAT. Importantly, you’ll need to generate a PAT for each computer you wish to work from. For example, we will complete the following steps to create a PAT for your personal laptop, but you’ll also need to create a PAT if/when you choose to work on a second computer at home or on a server, etc. Good news is that you can follow these same steps when you’re ready to set up additional PATs on other machines. For now, let’s get a PAT for our personal laptop squared away:

Install the {usethis} package in R by running the following in your Console:

Console

install.packages(“usethis”)

Then, run the following in your Console:

Console

usethis::create_github_token()

Enter your GitHub password if/when prompted. You’ll be taken to a screen that looks like this:

Add a note in the Note field to describe which machine this PAT is being used for. For example, if you are generating a PAT for your laptop, you might choose to name it, My Personal Laptop.
Next, you’ll see a section called Select scopes with reasonable options already selected for you. You don’t need change anything. Scroll down to the bottom of that page and click the green Generate token button:

Copy the generated PAT to your clipboard
Head back to your IDE and run the following in the Console:

Console

gitcreds::gitcreds_set()

This will prompt you to paste the PAT you just copied from GitHub. Press return / enter to run. You should see something like this show up if all is well so far (you’ll have pasted your PAT where the example below says “REDACTED”):

In your Console, run:

Console

usethis::git_sitrep()

Does it return information about your connected GitHub account that looks something like below? Great! You’ve configured git and successfully stored your PAT.

Note: Setting an expiration date on personal access tokens is recommended in order to keep your information secure. GitHub will send you an email when it’s time to regenerate a token that’s about to expire. Follow the email prompts, then use gitcreds::gitcreds_set() to reset your token.

Create the scaffolding for your website

Create a new R project with some necessary website files. Start by opening up RStudio and clicking on the button in the top right corner. Select New Project…

Choose New Directory, then Quarto Website.

And finally, fill out the Directory name: field – this is the name of your R project, and will eventually become your remote (i.e. GitHub) repository name (Important: see note below re: naming!) – and choose where to save your directory to using the Browse button. I also recommend unchecking the Use visual markdown editor box, if selected (this just means you’re project will open with the Source editor, but you’ll still be able to toggle to the Visual editor, if desired). Click Create Project.

Name your project yourGitHubUsername.github.io if you plan to deploy using GitHub pages

Because we’ll be using GitHub pages to publish / host our websites, it’s recommended that you name your project yourGitHubUsername.github.io (you’re allowed one user website with the github.io suffix) – for example, the project / GitHub repository, which contains the code for my personal website, is named samanthacsik.github.io. Otherwise, name it something reasonable (this will become the slug for your site if publishing with GitHub pages, so choose carefully). I’m calling my project mysite just for tutorial purposes only – you should definitely give yours a more practical / creative name.

You should now see a folder called mysite (or whatever you named your Quarto project) with a series of files (_quarto.yml, about.qmd, index.qmd, styles.css) that provide the scaffolding for your website in the Files tab (in the bottom right panel in RStudio, if you haven’t altered the pane layout).

Take a quick tour of your website files

When you create a new Quarto website, a handful of files are generated by default:

index.qmd renders your website’s landing page. Whatever you add to this file will be the first content visitors see when they visit your site. Update the content of index.qmd (or any other website page) using markdown and / or HTML (you can mix and match both on the same page), add and execute code chunks and embed outputs, etc. Importantly, do not change the name of index.qmd – this is the default / expected name given to website landing / home pages. If you change the name of this file, you risk breaking your (eventual) deployment.
about.qmd is a regular ’ole website page. You’re able to change both the name of this file (e.g. change about.qmd to my-new-name.qmd) and / or the title of the file by updating its YAML – by default, the YAML only includes a title:

about.qmd

---
title: "About"
---

YAML is a human-readable data serialization language, which is commonly used for creating configuration files. Quarto recognizes lots of different YAML options for controlling the appearance and behavior of your individual website pages. YAML is always written at the top of a .qmd file and is denoted by a pair of “gates”, ---.

_quarto.yml is your website configuration file. Any document rendered within your project directory will automatically inherit the metadata defined in this project-level configuration file (though you can control metadata on a page-by-page basis by making edits to an individual page’s YAML, which will override any options specified in _quarto.yml). Importantly, this is where you define your website’s structure (e.g. your navbar, sidebar, footer, etc.). By default, your file should look similar to this:

_quarto.yml

project: 
  type: website

website:
  title: "mysite"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

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

styles.css is a stylesheet, where you can write CSS rules to alter the appearance of your website. We’ll actually create and use a different type of stylesheet (called a “sassy css file”, .scss) in just a little bit.

The following will appear after we preview our website and initialize our project as a git repository

The _site/ directory is where all of your rendered HTML (and other important) files live. When you render or preview your site (we’ll do this in the next step!), Quarto takes all of your .qmd files and converts them to .html files, and saves them to this folder (which is important because web browsers don’t know how to read .qmd files, but do know how to read .html files). We’re actually going to change the name of this folder once we configure our website for deployment, but _site is the default name that Quarto uses (we can leave as-is, for now). You don’t want to physically edit or move any files inside this directory (if you want to make a change to your website, update the .qmd or _quarto.yml file, then re-render).
.gitignore is a place where we can specify any files that we don’t want Git to track (i.e. that we want Git to ignore). This is not a “Quarto thing,” but rather a valuable file that lives inside git directories. One common use is to add any large data files that you don’t want to accidentally push to GitHub (GitHub isn’t designed to handle LARGE files).

Preview your very basic, but functional website by typing the following command in the Terminal:

Terminal

quarto preview

Your site preview should open up in your browser. Quit your preview by clicking the Stop button in the top right corner of your Terminal or by pressing Ctrl + C.

quarto preview makes it easy to quickly view iterative changes

Running quarto preview launches a preview of your website in a browser window. So long as you leave the preview running, it will update each time you make and save changes to website files (which makes iterating on your work really easy!).

Install the {usethis} package, if necessary. At this point you’ve created a directory (folder) with the website scaffolding files, but it’s not yet being tracked by git, nor is it connected to a remote repository on GitHub. We can use the {usethis} package to help us set this up. First, install the {usethis} package (if you don’t already have it). Do so by running the following in your console:

Console

install.packages("usethis")

{usethis} is an R package that facilitates interactive workflows for project creation and development

We’re using the {usethis} workflow here because it provides a lot of really helpful tooling (learn more in the documentation), including a couple wrapper functions to execute git commands – in other words, we’ll use some familiar-feeling R functions provided by {usethis} to execute some Git commands, rather than running those Git commands in the Terminal.

Initialize your R Project folder as a git repository using usethis::use_git(): To create a local git repository, run the following in your Console:

Console

usethis::use_git()

Choose yes when asked if it’s okay to commit any uncommitted files. If asked to restart R, choose yes. Once complete, you should see the Git tab appear in your top left pane in RStudio.

Notice the Git tab appear (here, in the top right pane) upon restarting RStudio.

What is a git repository?

When we initialize our R project, mysite/ (or yourGitHubUsername.github.io/), as a git repository using git init (or a wrapper function, such as usethis::use_git()), a hidden .git/ folder is created within that project folder. This hidden .git/ folder is the git repository. As you use git commands (or RStudio’s GUI buttons) to capture versions or “snapshots” of your work, those versions (and their associated metadata) get stored within the .git/ folder. This allows you to access and / or recover any previous versions of your work. If you delete .git/, you delete your project’s history. Here is an example website repository, represented visually:

Check the name of your default branch (the only branch you should have at the moment) – that is, the branch that all changes eventually get merged back into (if you’re building a website, this branch is typically the one you’ll want to deploy). There are multiple ways to check this – here are two easy options:

Click on the Git tab in the top right pane of RStudio. Next to the A white diamond with two purple squares, one directly above and one directly to the right, connected to the diamond by a line. symbol, you should see a dropdown menu that displays the name of your current branch.

Open RStudio’s Terminal window (next to the Console) and run either git branch (this prints all local branches and highlights the one that you’re currently on) or git status (the first printed line should say On branch <branch_name>).

If your current branch is named master, update the name to main. (If your branch is named main, you’re good to go! You can skip this step.) To update your default branch name, run the following in your Console:

Console

usethis::git_default_branch_rename(from = "master", to = "main")

Confirm that your branch name was updated to main by running git branch or git status in your Terminal. The above function only updates your default branch name for this respository. You’ll also want to update your git config file so that the default branch name of any future local git repository is automatically named main. To do so, run:

Console

usethis::use_git_config(init.defaultBranch = "main")

A git config file is a place to define your Git settings and preferences

This includes things like setting your user.name and user.email, which are used to identify the author of commits (you may have done this recently as part of the initial setup prior to this workshop). It’s also a place for us to permenently set the name of our default branch for all future git repositories. You can view the contents of your entire git config file by running the following command in your Terminal:

Terminal

git config --list

The racist “master” terminology for git branches motivates us to update our default branch to “main” instead

There is a push across platforms and software to update this historical default branch name from master to main. GitHub has already done so – creating a remote repository first results in a default branch named main. Depending on your version of Git and / or your configuration settings, however, you may need to update the name manually when creating a local git repository first (as we’re doing here).

Create an upstream remote repository (i.e. GitHub repo). So far, we’ve created a local git repository that contains the basic files needed to build our Quarto website. We’ve also created one commit (i.e. taken a “snapshot” of our work) in that local git respository. Now, we need to create a “remote” repository (i.e. a version of your project that is hosted on the internet) on GitHub. Run the following in your Console, which will open up your web browser to your new remote repository on GitHub – it should already have the same name as your local git repo / R project:

Console

usethis::use_github()

After running `usethis::use_github()` your browser window should open up to your new GitHub repository and look similar to the browser above.

Understanding the difference between Git vs. Github

Git is a version control software designed to manage the versioning and tracking of source code files and project history. It operates locally on your computer, allowing you to create repositories and track changes. It works directly with files on your computer, and is primarily used through a command line interface (e.g. Terminal, Git Bash). Some GUIs (Graphical User Interfaces), like RStudio, provide user-friendly buttons to execute git commands as well.

GitHub is a cloud-based hosting service that allows you to manage Git repositories – as Jenny Bryan describes in her book Happy Git and GitHub for the useR, hosting services like GitHub “provide a home for your Git-based projects on the internet.” GitHub provides us with the tools for storing, managing, and collaborating on git repositories. It also offers additional features on top of Git, like issue tracking, project management tools, code review, pull requests, and more.

The illustration below depicts how we use Git and GitHub together to version control our work locally (e.g. on our computer(s)), and send versions to and receive updates from a remote (i.e. GitHub) repository.

A basic git workflow represented as two islands, one with "local repo" and "working directory", and another with "remote repo." Bunnies move file boxes from the working directory to the staging area, then with Commit move them to the local repo. Bunnies in rowboats move changes from the local repo to the remote repo (labeled "PUSH") and from the remote repo to the working directory (labeled "PULL").

Illustration by Allison Horst

Build & publish your site with GitHub Pages

There are a lots of options to publish your website. We’ll use the GitHub Pages option, which allows you to publish a website from any GitHub repository (for free!). To do so, there are a few configuration steps:

Create a file named .nojekyll in your repository’s root directory (e.g. mysite/), which is required to disable some processing of HTML files that GitHub does by default. From RStudio’s Files pane, click New Blank File > Text File, then type .nojekyll > click OK (you can use the Text File option to create any file type).

.nojekyll files may (or may not, depending on your IDE) visibly appear in your directory

.nojekyll is a hidden file which may not visibly appear in your directory (e.g. if using RStudio). Regardless, you should see it show up as a file to track with git (e.g. under the Git tab in RStudio, or when you run git status in the command line). You can also view hidden files in Finder (Mac) using the keyboard shortcut Cmd + Shift + ., or follow these instructions for Windows 10 and 11.

Set the output-dir in your _quarto.yml file to docs. The output-dir is the directory (i.e. folder) where your rendered .html (and other important) files will automatically be saved to when you “Build” your website (see the next step!):

_quarto.yml

project:
  type: website
  output-dir: docs
  
# ~ additional metadata excluded for brevity ~

You can delete _site/ if it exists and if you’re publishing with GitHub Pages

If you previewed or built your site before setting output-dir to docs in _quarto.yml, you’ll notice a _site/ directory inside your repository – this is the default output directory name. Because GitHub Pages will expect a docs/ folder to deploy from, you can delete _site/ altogether (and push your deletion, if you’ve already committed / pushed _site/ to GitHub).

From the Files pane, check the box next to _site > click the Delete button

Render your website. Click on the Build tab, then Render Website. You should see your minimal, albeit functional, soon-to-be website appear in the Viewer pane. You can click on the button to open your file in your web browser. Note: your website is currently being hosted by your local machine, not at a searchable URL. We’ll get there soon though!

Always “Render Website” before pushing changes that you want to deploy!

Clicking Render Website in the Build tab (or running quarto render in the Terminal) is a necessary pre-deployment (and redeployment) step – it converts all .qmd files to .html and ensures that all website components are stitched together correctly. If you do not render your website before pushing your files, your changes will not deploy.

Note: Previewing your website is different than rendering your website. Previewing alone does not formally prepare all of your website files for deployment.

Send all of your website files from your local git repository to your remote GitHub repository. You can do this from RStudio’s Git tab, or via the command line:

Stage your files by checking all the boxes in the Git tab
Commit your files by clicking the Commit button, adding a commit message, then clicking Commit
Push your files to the remote repository (on GitHub) by clicking the Push button (with the green upward facing arrow)

Stage your files by running git add . in the Terminal (or stage files individually by running git add file-name)
Commit your files by running git commit -m "my commit message" in the Terminal
Push your files to the remote repository (on GitHub) by running git push in the Terminal

Configure GitHub pages to serve content from the “docs” directory by clicking on the Settings tab in the top menu bar, then the Pages tab from the left-hand menu bar. Make sure that Branch is set to main and that the selected folder is set to /docs. Click Save. Once deployed (this may take a few minutes), your website’s URL will appear inside a box at the top of the page (you may have to try refreshing a few times).

Your website’s URL will appear at the top of the page once you’ve configured GitHub pages to host your Quarto site

A hosted Quarto website (notice the URL)! Now time to customize and add content.

Check out the Actions tab on GitHub to view deployment status

See deployment status, time of each deployment, and how long it took to deploy each run. You can also find failed deployments here (yes, it does happen on occasion) and take action on fixing them.

Update your landing page

Our webiste might be deployed, but it’s not so personalized. Let’s work on making those important updates. Remember to spin up a preview (run quarto preview in the Terminal) to see your changes as we iterate.

Don’t mess with stuff in docs/

When you render your site, Quarto takes all your .qmd files, converts them to .html files (along with some other important stuff), and saves everything to your docs/ folder. Your site now deploys from this folder, so you really don’t want to mess with anything in here directly. Instead, make changes to your .qmd (and supporting, e.g. _quarto.yml) files, then rerender your site.

Add content to your landing page (index.qmd). index.html (which is built from index.qmd) is the page people will arrive at when navigating to your website – give this landing / home page a makeover by trying out some of the following:

Update the YAML title in your index.qmd file. Here, I changed mine from "mysite" to my name, "Samantha Shanny-Csik"
Delete the sample text and begin adding your own content – a great place to start is a short blurb introducing yourself!

My Quarto website home page, which now includes my name and some content, but isn’t super visually pleasing…

Do not change the name of index.qmd

This is the default / expected name given to website landing / home pages. If you change the name of this file, you risk breaking your deployment.

Arrange your landing page (index.qmd) using a pre-built template When the about option is added to a document’s YAML, a special template will be used to layout the content of that page. Choose from one of Quarto’s five built-in templates, each with a slightly different layout style. Some YAML options to play around with:

template: choose from Quarto’s built-in template options
image (note that this is a document-level option i.e. is not a sub-item of about): supply it the file path to your photo
image-width & image-shape: adjust your image’s size and shape (round, rounded, rectangle)
links: add buttons with links to your social media pages

index.qmd

---
title: "Samantha Shanny-Csik"
1image: images/headshot.jpeg
2toc: false
about: 
3  template: jolla
4  image-shape: round
  image-width: 17em
5  links:
    - text: LinkedIn
      href: https://www.linkedin.com/in/samanthacsik/
    - text: GitHub
      href: https://github.com/samanthacsik
    - text: Email
      href: mailto:scsik@ucsb.edu
---
        
# page content excluded for brevity ~

1: add a photo by supplying a relative file path & image name (here, headshot.jpeg lives in a folder called media/)
2: if you have a template / content with header text, you can remove “On this page” menu by setting toc: false
3: use a pre-built template (here, jolla) to update the layout of your landing page (or any page!)
4: set image shape (round, rounded, rectangle) & size
5: add button links to your favorite social media pages (e.g. LinkedIn, GitHub, and even your email – Note the mailto: that must precede of your email address, mailto:youremail.com)

Fun Tip: Install the Font Awesome Extension for Quarto to add free Font Awesome icons to your site! Be sure to check out the icon option when adding linked buttons to your About Page.

My Quarto website after updating my landing page with the built-in `jolla` template, adding an image, and linked buttons. Overall, a big improvement! However, our text is a bit squished in the center of the page – we’ll fix then in the next step.

Some additional configurations

Modify website appearance in _quarto.yml The _quarto.yml file is a configuration file – any document rendered within the project directory will automatically inherit the metadata defined within this file. Some easy updates that make a big difference:

_quarto.yml

project:
  type: website
  output-dir: docs

website:
1  title: "Sam Shanny-Csik"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme: cosmo
    css: styles.css
2    toc: true
3    page-layout: full

1: Your website title, which appears in your browser tab and in the top left corner of your website’s navbar (by default, it’s set to your repository name, which isn’t so pretty – change this!)
2: Note that the default toc: true here (in _quarto.yml) renders a navigation menu on all web pages by default (but you can override options on a page-by-page basis)
3: Set your page-layout to full so that your page content takes up more of the page width

My website with a new title (see top left corner) and with `page-layout` set to `full`, so that content doesn’t appear as squished in the middle of the page.

You aren’t required to have a title on index.qmd

Going for a more minimalist look? You can comment out (or remove) the title option from index.qmd.

Add additional pages to your website In the default Quarto website skeleton, there are two items in the navbar that appear as “Home” and “About.” Those navbar tabs link to two .html files (index.html and about.html) and are automatically rendered when when you Build to docs/. Adding a new page to your website requires two steps:

Create a new .qmd file and add any necessary YAML options, along with any content that you want to appear on that page. Here, I’m creating a new page titled “All of my favorite resources!” and saved it to my root directory as resources.qmd.

resources.qmd

---
title: "All my favorite resources!"
---

Update _quarto.yml by adding your new .qmd to the list of navbar pages. My website’s _quarto.yml file now looks like this:

_quarto.yml

project:
  type: website
  output-dir: docs

website:
  title: "Sam Csik"
  navbar:
   left:
     - href: index.qmd
       text: Home
     - about.qmd
1     - resources.qmd

format:
  html:
    theme: cosmo
    css: styles.css

1: A newly-added navbar page. Note: The page name, as it appears in the navbar of your website, will be the same as whatever is listed in the title field of that file’s YAML. For example, I have set title: "All my favorite resources!" in the YAML of resources.qmd – this is how it will appear in my website’s navbar. If you’d like to set the navbar name as something other than the page’s title, use the href and text options together (e.g. see how index.qmd is rendered as Home in my website’s navbar).

A newly added navbar page, titled “All of my favorite resources!”

A newly added navbar page, with an alternate navbar title (set using the `href` and `text` options together in `_quarto.yml`)

Add a blog

Your website is a great place to showcase your work, ideas, and writing in the form a blog. Let’s add one!

To add a blog to your website, you’ll need three things:

a folder to hold all of your individual blog posts – we’ll call ours blog/ (though the name is up to you)
a listing page, which lists all of your blog posts for viewers to browse and click through – this is a .qmd file that you’ll add to your website’s navbar by including it in _quarto.yml
blog posts! Your listing page will be blank until you actually add your first blog post

We’ll create these in the following steps.

Setup your listing page

Create a blog/ folder. Jump to your repo’s root directory and click on the new folder button in the Files pane. I’ll name mine blog/, though the name is up to you (keep in mind that this folder name will appear as part of your eventual blog post’s URL)
Create a listing page (i.e. a web page with content that is automatically generated from a list of documents – in this case, that would be a list of blog posts). Your listing page takes the form of a .qmd file that lives in your repository’s root directory (I’ll be calling mine blog.qmd and giving it the title “Blog” for demonstration purposes, though you can choose whatever file name and title you’d like).
Configure your listing page. Specify how you’d like your listing page to be arranged by updating the YAML section of blog.qmd. There are a variety of options that you can specify. Below are a few to get you started.

blog.qmd

---
title: "Blog"
listing: 
  contents: blog # this name must match the name of the folder you created in step #1; here, all Quarto docs in the `posts` directory will be included on your listing page
  type: grid # or `default` or `table`; each type has its own set of yaml options to include
  sort: "date desc" # can also sort on more than one field
  categories: true # allows you to sort posts by assigned categories 
---

Add your listing page to your website’s navbar. Visitors will have a difficult time finding your listing page if it’s not linked somewhere obvious. Update _quarto.yml with your new listing page to add it to your site’s navbar:

_quarto.yml

# ~ parts of `_quarto.yml` omitted for brevity ~

website:
  navbar:
    title: myWebsiteTitle
    right:
      - href: index.qmd
        text: Home
      - about.qmd
      - href: resources.qmd
        text: Resources
      - blog.qmd # add your listing page file to your navbar, just like you would any other new web page

Preview your website. You should see something that looks like this (we haven’t created any blog posts yet, so it’ll be empty for now):

Our listing page, which is currently empty since we haven’t yet added any blog posts.

Add a blog post

Create a folder inside blog/ to house your blog post. This folder name will become the slug for your published post, so name it something relevant, like a short description of what your blog post is about (make sure to separate words with hyphens or underscores, e.g. my-first-post).
Create an index.qmd file inside your new folder. Your file path should look something like this: mysite/blog/my-first-post/index.qmd. This file is your blog post. Write all your content here!

Why name your blog post file, index.qmd?

This is mostly important for maintaining short, clean URLs.

Let’s take this very blog post for example. The content that you’re reading right now is written to the file, samanthacsik.github.io/posts/2022-10-24-quarto-blogs/index.qmd (you can check it out on GitHub), and the resulting URL is https://samanthacsik.github.io/posts/2022-10-24-quarto-blogs/.

If I named my blog post file something like, my-blog-post.qmd (rather than index.qmd), the resulting URL would instead look like, https://samanthacsik.github.io/posts/2022-10-24-quarto-blogs/my-blog-post.html. This isn’t necessarily wrong, but it does result in a lengthier URL – and short URLs tend to be easier to remember.

Configure your blog post. You can add a variety of different options to the YAML section of index.qmd. Here are my go-to options:

blog/my-first-post/index.qmd

---
1title: "blog post title"
description: "blog post description (appears underneath the title in smaller text) which is included on the listing page"
2author:
  - name: Samantha Shanny-Csik
    url: https://samanthacsik.github.io/
    orcid: 0000-0002-5300-3075
    affiliation: R-Ladies Santa Barbara
    affiliation-url: https://www.meetup.com/rladies-santa-barbara/
date: 05-13-2026
3categories: [Quarto, R, R-Ladies]
4citation:
  url: https://samanthacsik.github.io/blog/my-first-post/
5image: preview-image.png
6draft: false
---

Here is where I will start writing my actual blog post content...

1: You should include a title, but don’t necessarily need a description (though I think these are nice to include!). These fields will appear on your listing page. You may also consider adding a subtitle.
2: You can include more than one author – see this post and source code as an example.
3: You may include as many self-defined categories as you’d like. Make sure that your spelling / capitalization / punctuation is consistent across blog posts should you apply the same categories to multiple posts.
4: Adding the citation option automatically generates both a BibTeX citation and reference for your blog post, and adds them to the bottom of your post.
5: Include an image to add as a preview image, which will appear on your listing page alongside your post. Your image should live inside your post’s subdirectory (e.g. mysite/blog/my-first-post/preview-image.png).
6: Set draft: true while you’re still working on your blog post to prevent it from showing up on your listing page, site map, or site search (it will still be available at a searchable URL). When you’re ready to publish, just remove draft: true from your YAML (or set to false), then render your post. Quarto v1.5.56 introduced draft banners, which will appear on any draft posts. You can also control how drafts are linked / rendered on your website using the draft-mode option. By default, any page set as a draft will not be linked or searchable. If you want your draft to still be searchable at it’s URL (helpful if you want to share a draft with someone, but don’t want it showing up on your listing page just yet), consider setting draft-mode to either unlinked or visible – check out the documentation for more information.

A grid-style listing page featuring one blog post with a preview image, title, three categories, description, author, and publishing date

An example draft blog post, with a banner-style title block. The draft notice will disappear and the blog post will appear on the listing page once `draft` is set to `false`.

Repeat steps 1-3 to add a new blog post

Congrats on creating your first blog post! When you’re ready to add another, repeat the steps above.

Update fonts & colors using Sass

We’ve come a long way, but our website could still use a bit more pizazz with a theme that reflects our own personality and style. There are a number of ways to update a Quarto website’s theme (e.g. colors, fonts). The (arguably) fastest and easiest way to get started is by defining some Sass variables in a .scss file (stylesheet), then linking to that stylesheet in your _quarto.yml metadata. The steps below offer a “quick start guide approach,” though I recommend checking out these workshop materials on customizing Quarto websites using Sass & CSS for a much more thorough / deeper dive.

Create a `.scss` stylesheet

Create a styles.scss file in your repo’s root directory (you can name it however you’d like).
Add the /*-- scss:defaults --*/ region decorator to the top of styles.scss (required by Quarto) – you’ll write all your Sass variables underneath this:

styles.scss

/*-- scss:defaults --*/

Update website colors

Define some color variables using the syntax, $variable-name: value; (you get to decide what these variable names are!). Here, we define three colors:

styles.scss

// Colors
$light-purple: #E7D1FF;
$dark-purple: #27004D;
$pink: #ff5b92;
$gray: #3B3B3B;

Use // for single line comments in .scss files

You may also create multi-line comments, which start with /* and end at the next */.

Use your color variables as values for Quarto’s Sass variables. Below, we specify only four, however there are a number of Sass variables which can be defined within SCSS files (find a list of them here):

styles.scss

/*-- scss:defaults --*/

// Colors
$light-purple: #E7D1FF;
$dark-purple: #27004D;
$pink: #ff5b92;
$gray: #3B3B3B;

// Sass vars
$navbar-bg: $dark-purple; 
$navbar-fg: $light-purple; 
$navbar-hl: $pink;
$body-bg: $light-purple;
$body-color: $gray; 
$link-color: $pink;

Your newly styled site should look similar to this (be sure to run `quarto preview` in the Terminal, if it’s not already running).

Update website fonts

Find a Google font family by browsing options at https://fonts.google.com/. There are so many options – click on the Filter button in the top left corner of the page to help narrow your choices. For this exercise, we’ll go with Elms Sans.

If you want to bold or italicize text, you need to select a font family that has those styles

Not all font families come in every style. For example, Elms Sans comes in a variety of weights (i.e. levels of boldness) and italic, while Sen comes in a variety of weights, but not italic. This means that if you import and use Sen, you will not be able to italicize text.

Select a Google font family(ies) by clicking the blue Get Font button in the top right corner of the page, which adds your font family to your “bag.” You can add as many font families to your bag as you’d like to import, though we’ll stick with just one (Nunito) for this exercise. Click Get embed code, then choose the @import radio button (beneath the Web menu option), which will provide your import code chunk. Copy everything between the <style> </style> tags (starting with @import and ending with ;) to your clipboard.

After adding Elms Sans to my ‘bag’ (by clicking the ‘Get Font’ button), we can ‘Get Embed Code’ to copy the import URL to our stylesheet

Import your Google font by pasting the import code into styles.scss (I always place this at the top of my stylesheet, beneath /*-- scss:defaults --*/):

styles.scss

/*-- scss:defaults --*/

// Import Google fonts
@import url('https://fonts.googleapis.com/css2?family=Elms+Sans:ital,wght@0,100..900;1,100..900&display=swap');

// Colors
$light-purple: #E7D1FF;
$dark-purple: #27004D;
$pink: #ff5b92;
$gray: #3B3B3B;

// Sass vars
$navbar-bg: $dark-purple; 
$navbar-fg: $light-purple; 
$navbar-hl: $pink;
$body-bg: $light-purple;
$body-color: $gray; 
$link-color: $pink;

Apply your font using the mainfont option in _quarto.yml – this is the easiest way to use a single font across your entire website:

project:
  # ~ additional YAML omitted for brevity ~

website:
  # ~ additional YAML omitted for brevity ~

format:
  html:
    theme: styles.scss
    toc: false
    page-layout: full
1    mainfont: Elms Sans

1: Be sure to spell the font family name exactly as it appears on Google Fonts

Our updated website, with Elms Sans applied.

You can totally import and use more than one Google font!

But this requires a bit more Sass and CSS. While we won’t get into that here, check out these workshop materials for guidance.

Apply your stylesheet

Apply your styles.scss stylesheet to your website using the theme option in _quarto.yml:

_quarto.yml

project:
   # ~ additional YAML omitted for brevity ~

website:
  # ~ additional YAML omitted for brevity ~
  
format:
  html:
1    theme: styles.scss
    toc: false
    page-layout: full

1: Apply your styles.scss stylesheet using the theme option

Comment out / remove css: styles.css from _quarto.yml

This tutorial doesn’t cover writing CSS, though you can (and should) write any CSS in your .scss file (rather than writing it in a separate .css file). I recommend removing styles.css from _quarto.yml. You can also delete styles.css from your repo (you can always create a new one if you decide you want / need a .css file in the future).

Redeploy your website changes

We’ve made lots of great changes, and now we need to publish them. Thankfully, this is fairly straightforward:

Render your website. You can do this by either navigating to the Build tab in RStudio and clicking the Render Website button, or running render quarto in your Terminal. This converts all .qmd files to .html and ensures that all website components are stitched together correctly. If you do not render your website before pushing your files, your changes will not deploy.
Push your files to GitHub. You can do so using the RStudio GUI buttons in the Git tab or via the Terminal.
Voila! Keep an eye on the GitHub Actions tab to see when your redeployed website is ready to view.

Working on branches is recommended!

Despite not practicing it here today, I almost always work on a branch when making changes to my website – this way I can safely test changes before deploying them to my live site. To create a branch:

Check that you’re on main by typing git branch into the RStudio Terminal. If you’re not on main, you can switch by running git checkout main.
Create a local git branch from main by running the following in your Terminal:

Command line / Terminal

git checkout -b my-new-branch

Push your new local branch to GitHub by running the following in your Terminal:

Command line / Terminal

git push -u origin my-new-branch

You’re now ready to work as normal! Once satisfied with your changes, you can git add, git commit -m "my commit message", and git push (or use the RStudio GUI buttons in the Git tab) your files. Open a pull request from GitHub and merge into main to integrate your changes (this step is important! Your site will not redeploy until your changes have been merged from your branch into main).