PhD Students: Creating a website with Quarto

grad school advice
technical
quarto
Author

Damon C. Roberts

Published

September 29, 2022

You can find all of the source code for this site on my Github

Why have a website?

PhD students ought to have a website. There are numerous reasons why:

  1. Showcase your work, who you are, and what you’ve accomplished.
  2. Think of it as an extended CV that can communicate more information to potential employers about your work beyond what your CV might be able to communicate.
  3. Serve as an outlet for you to Blog and to publicly store other resources you might like to share with others.

But don’t take my word for it, APSA (the American Political Science Association, a large organization of political scientists) held a workshop at the 2022 conference discussing the “why” and “how” of professional websites.

How can I go about making one?

There are tons of options out there. Some are as simple as using a Weebly, Wordpress, or Google Sites. There are other options that offer a bit more customizability but might require a few more technical skills.

Out of all of these, my recommendation is to use Quarto. There are a number of reasons. Quarto is based on Markdown which is relatively easy to use. There are some start-up costs in terms of navigating setting up the site and to then publish the site, but it honestly isn’t anywhere near as hard as what it’d be to publish with Github pages (which I’ve done) or to make your own site from scratch. As it is free, and open source, it has the benefit of not costing you anything but the price of some of your time and for a custom domain name (if you purchase one). Another benefit is that getting used to using Quarto is highly recommended as it can be used to write manuscripts for your research as well. So becoming comfortable with it and all of its features can pay off in the long-run. Beyond its ability to create things like presentations, can render PDF documents for manuscripts, and websites, you can run and evaluate many different coding languages (such as R and Python). So it can let you do data analysis in one single document. That’s great!

Here are my practical steps for putting together an academic site for graduate students. I will put the disclaimer that what I did is driven by my particular needs and wants from a website.

Before you do any of these steps, first make sure that you’ve set up Quarto. I’m also assuming that you have some familiarity with IDE’s (e.g., RStudio, VSCode), and with working directories.

  1. Create a project

In a terminal, in RStudio or your chosen IDE, type:

quarto create-project website --type website

Note, you should make sure that your current working directory is set to a desired location. When you run this command, it will create a folder in your current working directory called website.

If you are on Windows, you might receive the following error:

Quarto: Error command not found

If you experience this, then you will want to add a .cmd suffix to the quarto command:

quarto.cmd create-project website --type website 
  1. Edit the _quarto.yml document to adjust site-wide features
  1. Start customizing your home page (index.qmd - I renamed mine to home_index.qmd)
  • Start off by writing an about me section
  1. Add extra pages or sections.
    • I personally like to keep things super organized by nesting folders. So I put all my extra, non-homepage, files in a sub-folder called section. I then create a home page for each section.
      • For example, I have a page on Teaching where I include Dropbox links to all of the PDF’s of my syllabi from courses that I’ve been the instructor of record for or have been a Teaching Assistant. Here’s my file structure for this page: website/sections/teaching/index.qmd
    • To create a new page:
      • create a new .qmd file titled index.qmd
      • Then include important metadata at the top of the file:

---
title: Title of page
---

# Section

Text
  1. Adding sections to the navbar
  • Go to your _quarto.yml page. There should already be a section that looks something like this:
website:
    navbar:
        background: primary
        search: true
        left:
            - index.qmd
  • If you did what I did to make my Teaching page (i.e., created a subfolder called section and a subfolder called teaching with a file called index.qmd), then you can add the page to the Navbar easily by adjusting the previous section of the _quarto.yml page to be:
website:
    navbar:
        background: primary
        search: true
        left:
            - index.qmd
            - sections/teaching/index.qmd
  1. Add your CV
  • You should make sure that you provide a shareable link from Google Drive or Dropbox so that people can access the most recent version of your CV.
  • You can do this by creating a section titled CV in your navbar and providing the sharable link to the file. For example, I have shared my CV with dropbox. I copied the Dropbox link and updated the navbar section of the _quarto.yml file to:
website:
    navbar:
        background: primary
        search: true
        left:
            - index.qmd
            - text: "CV"
              href: https://www.dropbox.com/s/ytbggop4iy2oq77/cv.pdf?dl=0
            - sections/teaching/index.qmd

Publishing the site

As I see it, you have two key options. However, the documentation provides information about more options and the steps to publish your site with each of them.

  1. Publish directly to netlify. Super simple just type
quarto.cmd publish netlify

You’ll then need to create an account with netlify (if you don’t already have one). It’ll then render the site and then push it to netlify. You can then add a custom domain and do some other customization about updating the site once it is published and live.

Here’s a oversimplified file tree

%%{init: {'theme':'base', 'themeVariables':{'primaryColor':'#ffffff', 'primaryBorderColor': '#000000'}}}%%

graph TD;
A[Working Directory] --> B[_quarto.yml]
A --> C[home_index.qmd]
A --> D[styles.css]
A --> E[sections]
E --> F[teaching]
F --> G[aching_index.qmd]
A --> H[_extensions]

Figure 1: Website file tree