Quarto template for university courses

Image created with DALL·E. Prompt: 'octopus-like alien futuristic teacher, abstract award-winning material design favicon blue flat colours'

A template for developing university courses using Quarto.

Real Examples:

• LSE DS105 - Data for Data Science
• LSE DS101 - Fundamentals of Data Science

New to Quarto?

You will need to understand the basics of the following features of Quarto to make the most of this template. It's worth it!

• Check their initial tutorial
• Then read about Quarto websites
• Check out also Revealjs tutorial to learn how to create modern slides
• Then move on to learn about Quarto projects

There you go. You might be wondering how to put all of this to work. That is precisely why this template exists!

💡 How to use this template

On GitHub:

1. Click on the green button Use this template then Create a new repository.

2. Wait for GitHub to copy the files and run the initial setup (you will see this on the Actions tab).

Locally in your computer:

3. Clone your newly created repository to your computer.

4. Follow the instructions written below in the 🧰 Dev Setup section.

5. Skip the R or Python setup if you do not plan on working in one of these languages.

Start editing the files:

Here is a guide of the initial files you might want to modify to remove the sections that refer to the template, leaving only what is relevant to developing/updating the material of your course.

6. Start by editing the README.md file carefully.

   • Change the title
   • Remove some of the sections
   • Edit the Dev Setup instructions to cater to your needs.

7. Add your course code and course name to the web pages

   • If you are using VSCode, you can Ctrl + Shift + F (or ⌘ + Shift + F if you are on Mac) and replace all occurrences of MY_COURSE_CODE and MY_COURSE_NAME to the code and name of your course, respectively.
   • Or, you can manually edit those in the following files:
     • _quarto.yml
     • 2023/index.qmd
     • helpers/remove-nav.html

8. Then move on to _quarto.yml. Scan through this file to spot what you want to change. What pages do you want to keep or remove from your website?

9. Next, modify the content of index.qmd and start working properly on your content pages under 2023/*

10. Visualise your changes by running the Quarto website locally:

    quarto preview . --render all --no-browser

🧰 Dev Setup

On top of the setup below, I also recommend you use VSCode as your primary IDE.

🐍 The Python setup

🐍 The Python setup

1. Install Python 3.8 or higher on your computer.

2. Install anaconda or miniconda on your computer.

3. Create a new conda environment:

   conda create -y -n=venv-my-course python=3.10.8

   Never worked with conda environments before? Take some time to read their documentation.

   💡 Pro-tip: replace my-course with your course code. Say, for example, venv-ds105.

4. Activate the environment and make sure you have pip installed inside that environment:

   # the exact `activate` command will vary depending on your OS
   conda activate venv-my-course 

💡 Remember to activate this particular conda environment whenever you reopen VSCode/the terminal.

10. Install required libraries

pip install -r requirements.txt

Now, whenever you open a Jupyter Notebook, you should see the venv-my-course kernel available.

📊 The R setup

📊 The R setup

1. Open a terminal and navigate to the root of this repository.
2. Ensure you have R version 4.2.2 or higher
3. Open the R console in this same directory and install renv package:

   install.packages("renv")

4. Run renv::restore() to install all the packages needed for this project
5. Whenever you install a new R package, run renv::snapshot() to save it on your renv.

The Quarto setup

The Quarto setup

1. Install Quarto on your computer.

2. Run the following command to start the website locally:

   quarto preview . --render all --no-browser

   This will read the instructions from _quarto.yml and render the website locally.

3. Open your browser and navigate to http://localhost:<port>/. That's it!

🕸️ Publishing the website

🕸️ Publishing the website

I recommend you set up a GitHub Action for this. Just follow the instructions in the official Quarto instructions.

💡 This template already comes with a GitHub workflow setup. You can find it in the .github/workflows/publish.yml_ file. You just need to rename it to .github/workflows/publish.yml (remove the underscore at the end)

📟 Contact

✋ Questions? Suggestions? If you are not sure how to do something with the template or have a suggestion for a new feature, start a discussion.

🐞 Spotted any bugs? Create a new Issue.

🖼️ Want to show us your courses? Share a link to your public page on the discussions page or write me an e-mail.