Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jonjoncardoso/quarto-template-for-university-courses
Quarto-based template for designing websites of university courses.
https://github.com/jonjoncardoso/quarto-template-for-university-courses
higher-education markdown python quarto r reveal-js teaching-materials
Last synced: 2 months ago
JSON representation
Quarto-based template for designing websites of university courses.
- Host: GitHub
- URL: https://github.com/jonjoncardoso/quarto-template-for-university-courses
- Owner: jonjoncardoso
- License: gpl-3.0
- Created: 2023-03-13T18:17:21.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-03-15T15:35:02.000Z (over 1 year ago)
- Last Synced: 2024-02-04T07:10:23.592Z (5 months ago)
- Topics: higher-education, markdown, python, quarto, r, reveal-js, teaching-materials
- Language: Markdown
- Homepage:
- Size: 8.89 MB
- Stars: 54
- Watchers: 4
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Lists
- awesome-quarto - quarto-template-for-university-courses - A quarto-based GitHub repository template for designing university course websites. (Templates / Repository templates)
README
# 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](https://lse-dsi.github.io/DS105/) - Data for Data Science
- 
[LSE DS101](https://lse-dsi.github.io/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](https://quarto.org/docs/get-started/)
- Then read about [Quarto websites](https://quarto.org/docs/websites/)
- Check out also [Revealjs tutorial](https://quarto.org/docs/presentations/revealjs/) to learn how to create modern slides
- Then move on to learn about [Quarto projects](https://quarto.org/docs/projects/quarto-projects.html)
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](#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:
```bash
quarto preview . --render all --no-browser
```
# 🧰 Dev Setup
On top of the setup below, I also recommend you use [VSCode](https://code.visualstudio.com/Download) as your primary IDE.
🐍 The Python setup
## 🐍 The Python setup
1. Install [Python 3.8](python.org) or higher on your computer.
2. Install [anaconda](https://www.anaconda.com/products/individual) or [miniconda](https://docs.conda.io/en/latest/miniconda.html) on your computer.
3. Create a new `conda` environment:
```bash
conda create -y -n=venv-my-course python=3.10.8
```
Never worked with conda environments before? Take some time to read [their documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html).
💡 **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:
```bash
# 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
```bash
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:
```r
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](https://quarto.org/docs/getting-started/installation.html) on your computer.
2. Run the following command to start the website locally:
```bash
quarto preview . --render all --no-browser
```
This will read the instructions from `_quarto.yml` and render the website locally.
5. Open your browser and navigate to `http://localhost:/`. 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](https://quarto.org/docs/publishing/github-pages.html#publish-action).
💡 This template already comes with a GitHub workflow setup. You can find it in the [.github/workflows/publish.yml_](.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](https://github.com/jonjoncardoso/quarto-template-for-university-courses/discussions).
**🐞 Spotted any bugs?** Create a new [Issue](https://github.com/jonjoncardoso/quarto-template-for-university-courses/issues).
**🖼️ Want to show us your courses?** Share a link to your public page on the [discussions page](https://github.com/jonjoncardoso/quarto-template-for-university-courses/discussions) or write me an e-mail.