5  Websites and blogs

In this chapter, you will learn how to create professional websites and/or blogs using Quarto. For academics, an online presence is critical but often overlooked. From early career researchers to experienced academics, you will benefit from people being able find out more about you, such as your publications, talks, and contact information. You might think the technical barrier is too high to maintain your own website, but there are plenty of tools out there to make it easy. The combination of Quarto and Github Pages is a free example of this which you can maintain yourself alongside the other outputs I covered in this book. This chapter rolls websites and blogs into one as the general principles are the same, where blogs are just a specialised form of website to present individual posts on the index page.

5.1 Example websites and Quarto documentation

For an example of a Quarto website, you can explore the UK Conference on Teaching Statistics website which I helped to create and maintain. If there is a feature you like, you can see the source code on github to adapt to your needs.

For other examples, Solomon Kurz - a psychology researcher who writes about programming / stats - posted on BlueSky about academic websites. The thread has over 40 replies, so you can explore how other people have used Quarto or similar tools:

Your main source of information for this output is the Creating a Website and Creating a Blog sections of the Quarto guide.

5.2 Creating a Quarto website or blog

If you have not followed the preparation instructions yet, you need R/RStudio and git/github desktop installed on your computer. I will be demonstrating how to use github desktop rather than the command line, as git could easily be it’s own workshop.

The first step is thinking about where you want your website folder stored on your computer for where all the files will live. I have a folder within Documents called git_repos where I store all my git repositories away from OneDrive (see below).

Do not create github repositories within OneDrive

We have not reached the github step yet, but as you think about where you want your folder for the website, please do not use a folder within OneDrive. Sometimes it works, but most of the time it causes chaos as OneDrive is trying to track changes, github is trying to track changes, which ends in them fighting over file permissions.

Once you have decided where your website will live, open RStudio and click File > New Project... > New Directory > Quarto Website for a website, or File > New Project... > New Directory > Quarto Blog for a blog.

Regardless of whether you want to create a website or a blog, you will see a new window asking for you to specify:

  • “Directory name:” - the name of the folder it will create, so keep it short and without spaces.

  • “Create a project in the subdirectory of:” - click browse to navigate to the folder you want your website/blog to live in. Creating the website/blog will create a new folder within this directory, so you do not need to create a folder yourself.

Click “Create project” and after a couple of seconds, it will open a new project window with the template in. Congratulations, you have a website/blog skeleton to work with!

Although there is a lot of overlap between the two outputs, I have split the tour into a website section and a blog section as there are a couple of key distinctions to highlight. So, you can navigate to the one most relevant to you at this point.

5.3 Tour of the Quarto website template

  1. _quarto.yml

We will start by exploring the _quarto.yml file where you can edit all the details for your website, like the title, licence, theme, and any styling. In Quarto websites, this is also how you control the number and order of pages in the navigation bar.

What is a .yml file?

YAML / .yml are configuration files for programs which must follow specific formatting conventions.

Within the .yml file, I will highlight in the workshop key features such as: title, navbar, and format.

Adding new pages to your website

By default, your website will have the main index and an about page in the navigation bar. To add more pages, simply create new .qmd files in the directory (including at least a title in the YAML) and specify where you want them in the .yml file.

For presenting your website using github pages, edit the project from the standard first two lines:

project:
  type: website

To add a new third line:

project:
  type: website
  output-dir: docs

Be careful, indentation is important in .yml files. We do this as by default, it will create a folder called _site where the rendered .html files will live. For Github Pages though, it looks for a folder called docs, so this will streamline things later.

Adding Google analytics

If you want to track how many people view your website and access other kinds of analytics, you can add a Google analytics key into the .yml options.

You would add it into the website: section like:

website:
  google-analytics: "UA-XXXXXXXX"

There are additional options like turning on a cookies warning if you are using this feature to tell people you are tracking user activity on your website, so I recommend reading the Quarto documentation for these features.

Add a license for your work

One important consideration is telling people how they can use your work. In the .yml, you can specify a license (see the License section of the documentation) and make this super clear in the footer of your output. I like to specify this using the following settings under website:

website:
  license: "CC BY-SA"
  page-footer: CC-BY-SA-4.0 (2025) James Bartlett

I usually apply a CC-BY-SA license from Creative Commons as one of the most permissive licenses for reusing work, but they must provide attribution. You can look at the Creative Commons site for different license options.

  1. index.qmd

The index file will be the opening page to your website, so imagine it as a kind of home page. You can edit the title which may or may not be the same as your overall website title. Everything below the YAML section will be rendered as a regular .qmd file, so think about what you want to present to people.

  1. About.qmd

By default, you get an about page which is meant to describe you or your website. You might include information like your social media profiles and how best to contact you.

Add about page formatting

As you will see in the blog section, the about page in a Quarto blog can include several default templates. Weirdly, this is not activated in the website template, but you can use the same code in the YAML section.

The standard about page will look like:

---
title: "About"
---

But you can specify about as a section to add this formatting and preset link options such as github:

---
title: "About"
about:
  template: jolla
  links:
    - icon: github
      text: Github
      href: https://github.com
---
  1. Custom css styling

The only other file remaining in the template is styles.css. In this workshop, we are not exploring css (cascading style sheets), but this is essentially how you can customise the look of html pages. If you are not totally happy with the preset themes, you can explore how to edit the css styling on the CSS Styles Quarto documentation.

  1. Rendering files

Once you have finished editing each page and you want to check how it looks, you need to click Render for Quarto to process the code and turn it into something pretty. Once you click Render, you can open it up in the browser and keep checking as you make edits.

Caution

If you introduce an error, you will get an error and red box on the screen to highlight Quarto cannot render the book. If you look in the Background Jobs tab in the console below, you should get an error message for the source of the problem if you are unsure what you did wrong.

These are the key components to make your website. Until this point, these edits all exist on your own computer. But now it is time to track your code using github and make your website accessible online via github pages. Skip ahead to the creating a github repository section if you do not want to read about blogs.

5.4 Tour of the Quarto blog template

  1. _quarto.yml

We will start by exploring the _quarto.yml file where you can edit all the details for your blog, like the title, author(s), and the licence. In Quarto websites, this is also how you control the number and order of pages in the navigation bar.

What is a .yml file?

YAML / .yml are configuration files for programs which must follow specific formatting conventions.

Within the .yml file, I will highlight in the workshop key features such as: title, navbar, and format.

Adding new pages to your website

By default, your website will have the main index and an about page in the navigation bar. To add more pages, simply create new .qmd files in the directory (including at least a title in the YAML) and specify where you want them in the .yml file.

For presenting your blog using github pages, edit the project from the standard first two lines:

project:
  type: website

To add a new third line:

project:
  type: website
  output-dir: docs

Be careful, indentation is important in .yml files. We do this as by default, it will create a folder called _site where the rendered .html files will live. For github pages though, it looks for a folder called docs, so this will streamline things later.

Adding Google analytics

If you want to track how many people view your website and access other kinds of analytics, you can add a Google analytics key into the .yml options.

You would add it into the website: section like:

website:
  google-analytics: "UA-XXXXXXXX"

There are additional options like turning on a cookies warning if you are using this feature to tell people you are tracking user activity on your website, so I recommend reading the Quarto documentation for these features.

Add a license for your work

One important consideration is telling people how they can use your work. In the .yml, you can specify a license (see the License section of the documentation) and make this super clear in the footer of your output. I like to specify this using the following settings under website:

website:
  license: "CC BY-SA"
  page-footer: CC-BY-SA-4.0 (2025) James Bartlett

I usually apply a CC-BY-SA license from Creative Commons as one of the most permissive licenses for reusing work, but they must provide attribution. You can look at the Creative Commons site for different license options.

  1. index.qmd

For a blog, there is not too much to edit here. An index file will be the opening page to your blog, but it’s main function here is to display a preview of all your blog posts. Below the YAML which controls the title and listings, you can add text, code, and/or images like a normal .qmd file, but following this will be a list of blog posts in descending date order.

  1. About.qmd

By default, you get an about page which is meant to describe you and provide key contact information, such as your social media profiles.

About pages have a special template with a few presets which you can learn about in the Quarto documentation. The default will be “jolla”, but you can change it to another template that suits your needs.

Otherwise, anything below the initial YAML section will be formatted like a regular .qmd file for text, code, images etc.

  1. The posts folder

By default, you get two example posts to show how they should be structured. In index.qmd, part of the YAML specified contents: posts. This means it is using the contents of the posts folder to generate the blog posts.

If you click on the posts folder, you will see each post lives in its own folder. To create a new post, you would create a new folder with a short but informative name. Within that folder, there is another index.qmd file and any supporting files such as images. Each post needs its own index file and the YAML at the top controls the title, author, date, and any categories. Editing these will customise the look of the post in the preview on your home page and the top of your blog post when you open it.

  1. Custom css styling

The only other file remaining in the template is styles.css. In this workshop, we are not exploring css (cascading style sheets), but this is essentially how you can customise the look of html pages. If you are not totally happy with the preset themes, you can explore how to edit the css styling on the CSS Styles Quarto documentation.

  1. Rendering files

Once you have finished editing each page or post and you want to check how it looks, you need to click Render for Quarto to process the code and turn it into something pretty. Once you click Render, you can open it up in the browser and keep checking as you make edits.

Caution

If you introduce an error, you will get an error and red box on the screen to highlight Quarto cannot render the book. If you look in the Background Jobs tab in the console below, you should get an error message for the source of the problem if you are unsure what you did wrong.

These are the key components to make your blog. Until this point, these edits all exist on your own computer. But now it is time to track your code using github and make your blog accessible online via github pages.

5.5 Creating a github repository

Once you have a working barebones version of your website ready to go, it’s time to associate your website folder with a github repository and start some version control. If you want another resource, you can see the github documentation online.

In future, you could actually start with this part. You can create a new repository/folder with git enabled, and then add your R Project files for your output within this folder. However, we started by creating the website first, so we need to create a repository for an existing folder without a git component.

In the github desktop application, click add >> Create a New Repository and complete the details.

Your github username as your website URL

Unless you want to buy a custom URL, the typical format for the link will be yourusername + github.io/ + your repository name. For a website or blog, you can take advantage of a feature where every profile receives one site through Github Pages. You can create a repository called yourusername + github.io (e.g., bartlettje.github.io) and this will be the URL of your site, rather than another repo appended to the end. You only get one per github account though, so it’s best to use it on a website and blog where you’re likely to only have one.

  • Name: This will be the name of your repository on github, so call it something short but sensible.

  • Local path: Click Choose… and navigate to your website folder. You want the path to be the main folder your website lives in.

Select the folder, do not double click

One mistake I make every now and again is opening the folder you want to create a github repository for, rather than just selecting the folder. If you open the folder when selecting the local path, it will create a repository within your folder as a subdirectory. This means it will only apply version control to a level below your main folder and not track the files you want to track.

The other fields you can edit later, so click Create Repository when you are ready.

Your newly minted repository should be showing as the Current Repository. This exists on your computer, but it is still not available online. You need to click Publish repository, and that will push all of your files to github and be available online.

5.7 Commiting and pushing changes

At this point, you have everything you need for the website workflow. As you work on your website, you will go through the workflow of:

  1. Open .RProj and edit your website in RStudio, either by editing your past progress or adding new files.

  2. When you hit a milestone you want to record, in github desktop tick all file changes or specific files, and add a commit message (and longer description if necessary).

  3. If you are continuing to work on the website, keep editing and committing.

  4. When you are ready to push changes to github and Github Pages, push your commits.

Before we have time to start working on your newly minted website, I will end on a couple of warnings and tips.

Caution

Remember just committing changes will do nothing to your github repository and website link. You need to push those committed changes for them to be available on github and used to build the website in github pages. Likewise, you can edit the code in your .qmd file but not render those edits into the formatted html files. It takes a few minutes to rebuild, so do not worry if you do not immediately see the changes.

Reverting changes

One of the main features I use way too infrequently is reverting changes when something goes wrong. The idea behind version control is you save your work at specific milestones, where you can add commit messages that describe key changes you make. If you make a change that breaks something since your last commit, you can revert the changes to a previous version. To do this, go to github desktop, click History, and you will see all your commit history. Identify the last commit you want to revert to, right click on it, and select Revert Changes in Commit.

5.8 Start working on your own website!

Start working on your own book in the remaining time we have together.

See the final chapter on Quarto features and book conventions for inspiration / example code for the kind of features you can use.