1  Building From Scratch

These resources are intented to be used if you are building module resrouces from scratch and need to set up a new Quarto Project, GitHub Repository and Associated GitHub Pages to host the materials.

See the table of contents to the right of this page for a summary of the steps involved in this process. Ensure you have followed the System requirements and have set up your GitHub profile and linked it in RStudio as detailed in the Start Point section.

1.1 Step 1: Set up new Quarto Book Project in RStudio

We suggest using the Quarto Book format for hosting training materials - there are several other Quarto output styles that you can work with but this what has worked well for this style of content delivery.

  1. Open RStudio.
  2. Go to the menu: File → New Project... → New Directory → Quarto Book.
  3. Name the project and select the location where you want to save the project files on your computer. (I like to use a folder called github and all my repos exist in separate folders but pick what works for you!)
  4. Ensure the checkbox for Create a Git repository is selected (this initializes Git locally in the project).
  5. And also tick the checkbox for use renv with this project. This will create a local environment for the project and store all your package dependencies in an renv.lock file, this is an important aspect for hosting our site on gh-pages later on.
  6. Click Create Project.

RStudio will open up your new project. The Quarto Book project structure will include:

  • _quarto.yml: A configuration file where you can define the book’s structure, theme, output format, and other settings.

  • index.qmd: The landing page or introduction to the book. This file can serve as the cover page with a description of your project.

  • qmd files for chapters: A few example .qmd files will be provided as placeholders for different chapters, which you can edit or replace with your content.

  • An renv folder: This directory contains your project-specific package library, and an renv.lock file will be created to lock down package versions and dependencies, ensuring the project remains reproducible and code can be executed on publishing to our online portal.

1.2 Step 2: Stage initial commit to GitHub

Before linking this project to GitHub, we need to make sure the initial project files are committed to the local Git repository.

  • Head to the Terminal tab next to the console.

  • In the terminal, check which files are ready to be staged using:

    git status
  • This will show the files that have been modified or are new and need to be added to the repository. It will also tell us which branch we are working on in brackets. If this is the master branch lets change it to be called main.
git branch -m master main
  • To add all files to the staging area (the files you want to include in your commit - here this will just be our default Quarto Book Project files which is okay, run:
git add .

  • The . adds all the files in the current directory

  • After staging the files, you’ll need to commit them. The commit message should describe what changes or additions you’re committing.To commit the changes, use: The -m flag allows you to add a message in quotes (" ") describing the commit.

git commit -m "Initial commit for Quarto website"

1.3 Step 3 Push the local project to GitHub using usethis::use_github()

We now want to link our local repository to GitHub and specially we want it to be part of the PATH-Global-Health GitHub organisation. We can use the following code to do this, run this in your console:

usethis::use_github(
organisation = "PATH-Global-Health", 
visibility = "public"
)

This command will:

  • Create a new GitHub repository.
  • Link your local project to this repository.
  • Push the project files to GitHub.

This should then open up the repository automatically in you browser.

1.4 Step 4: Setting up gh-pages

Once our repository is on GitHub, we can configure the GitHub Pages site - which is where our module resources will be hosted. Use the usethis::use_github_pages() function to set the publishing branch for GitHub Pages.

To publish from the gh-pages branch, run:

usethis::use_github_pages(branch = "gh-pages")

If we head to our GitHub repository online we want to add some details to the repo page:

Head back to the <> Code tab and in the About section on the top right open the settings wheel ⚙️ - Under Website check the box next to: [x] “Use your GitHub Pages website” as shown in the image below.

In addition we can add a short description in this section as in the above image e.g. “MACEPA Data Fellows materials for the [insert module title]”.

1.5 Step 5: Automate Deployment with GitHub Actions

This is something I’ve found works best for me and my workstyle when creating these modules. Instead of ever rendering my work locally and then publishing this to GitHub I include a GitHub Action command so that when I commit and push changes to the repository GitHub will automatically render the new outputs to the gh-pages site.

Manually building and deploying our project every time we make a change can be time-consuming and prone to error. So by configuring GitHub Actions, we can automate the entire publishing process. Whenever we push changes to the repository (e.g., updated content, code adjustments), GitHub Actions will automatically trigger the workflow to build and deploy our site. Which saves us time and reduces manual effort. This also helps ensure that everyone is working on the most recent version of the materials, with automatic deployment occurring in the background.

1.5.1 Set up

More detials on setting up GitHub actions can be found here: https://quarto.org/docs/publishing/github-pages.html.

  1. In your Quarto project directory, create a folder called .github/worflows
  2. Inside .github/workflows/, create a file called quarto-publish.yml - You do this from within RStudio by heading to the files pane and into the workflows folder → new blank file → Text file and this opens up in R studio and then save this as quarto-publish.yml
  3. Add the following content to the quarto-publish.yml

on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Install R
        uses: r-lib/actions/setup-r@v2
        with:
          r-version: '4.2.0'

      - name: Install R Dependencies
        uses: r-lib/actions/setup-renv@v2
        with:
          cache-version: 1

      - name: Install TinyTeX
        run: |
          Rscript -e 'tinytex::install_tinytex(force = TRUE)'
          echo "PATH=$HOME/.TinyTeX/bin/x86_64-linux:$PATH" >> $GITHUB_ENV

      - name: Ensure TinyTeX Path
        run: echo "$HOME/.TinyTeX/bin/x86_64-linux" >> $GITHUB_PATH

      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  1. call renv::snapshot(), snapshot() updates the lockfile with metadata about the currently-used packages in the project library.

This quarto-publish.yml I have worked on standardising across the projects I’ve developed for the Data Fellows so far - should you have any issues please reach out to Hayley to help troubleshoot!

Other options for publishing content can be found here: https://quarto.org/docs/publishing/

1.6 Step 6 Push updates to GitHub

We can now push the all of the following changes to GitHub and test if the publishing action has worked - don’t worry that we haven’t changed any content yet we will get there!

Switch to the Terminal pane and run the following:

git add . 
git commit -m "deploying and testing github actions and publishing"  
git push

1.7 Step 7 Check build and status

Head to the repo and go to the ▶️ Actions Tab - we’re hoping to see something like this:

Which shows us out Build action was completed, worked correctly and the website page should be rendered! 🙂🎉

If you head back to the <>code tab and click the link we activated in the About section this should open up our github pages site and will hopefully currently be populated with Quartos book template!

If the build action failed we will see somthing like this:

If we click into this GitHub will give us a good indication of what exactly failed:

The error here is caused by incorrect indentation in the YAML file. YAML is strict about indentation, and in this instance the curhttps://quarto.org/docs/guide/rent _quarto.yml file, the chapters: key was incorrectly indented. We can correct this, commit and push the changes and our site was deployed correctly!

Often build errors are informative and can be fixed easily enough - if you’re struggling reach out to Hayley and we can always trouble shoot together!

1.8 Step 8 Adding content

Now we have all the set up out the way we can start adding our content and updating the themeing!

This step will be very context depenent on the type of materials we want to add to our modules so I have outlined some common steps across materials that have been built so far and we can always add more as we go.

The Quarto Guide is going to be super useful https://quarto.org/docs/guide/ especially if you’re new to working in Markdown - I won’t replicate the resources here and recommend using the Quarto guide as a reference point when writing in Quarto.

There is always the option in Quarto to use the visual editor - this simplifies the process of writing and formatting content in markdown formats and allows users to focus on writing without needing to remember markdown syntax, making it easier for beginners and those unfamiliar with code-based formatting. The Visual Editor provides an interface similar to popular word processors like Microsoft Word or Google Docs.

The Visual Editor includes toolbars with buttons for common formatting options such as:

  • Bold and italic text

  • Creating headings and subheadings

  • Adding bullet points or numbered lists

  • Inserting links, images, and tables

  • Adding callouts for notes, warnings, or tips

  • You can still insert and edit code chunks directly in the Visual Editor. These code chunks are executed as usual, and their outputs (tables, figures, etc.) are displayed inline, making it easier to integrate code into your documents.

To use the Visual Editor in RStudio or other supported IDEs:

  • Open any Quarto (.qmd) or markdown file in your project.

  • Click the “Visual” button in the top right corner of the editor pane to toggle between the standard markdown editor and the Visual Editor.

1.8.1 Understanding the _quarto.yml file

The _quarto.yml file is a configuration file that controls the structure and appearance of your Quarto project, such as the website’s title, menu, and theme.

For a Quarto book, the _quarto.yml file specifies the structure, appearance, and behavior of the book. Below is an example of what the structure might look like and what you will see when you open this initially in your project.


project:
  type: book

book:
  title: "My Quarto Book"
  author: "Author Name"
  chapters:
    - index.qmd
    - introduction.qmd
    - chapter1.qmd
    - chapter2.qmd

format:
  html:
    theme: cosmo
    toc: true
    number-sections: true
    css: styles.css

We want to start by modifying the title and author fields under book to what is relevant for the module (we can just delete the author line as it’s not needed here)

We can also add a subtitle that’s nice to include in all our topics like this:

book:
  title: Foundational Malaria Knowledge
  subtitle: MACEPA Data Fellowship - Training Materials

The chapters section defines the order of the chapters in your book. It links to the .qmd files that will become the different sections of the book:

book:
    chapters:
        - index.qmd           # Main page or introduction
        - introduction.qmd    # First chapter
        - chapter1.qmd        # Subsequent chapters
        - chapter2.qmd

You can add or remove chapter files as needed. Just make sure each file you list here exists in the project.

For some of our modules we have several topics within a module and sub topics within them so we can use the part as well as chapters to achieve something like this:

To do so you can set the _quarto.yml to something this:

  chapters:
  - index.qmd
  - part: topic1-intro.qmd
        chapters:
        - topic1a-history-malaria.qmd
        - topic1b-global-impact.qmd
        - topic1c-endemicity.qmd
  - part: topic2-intro.qmd
        chapters: 
        - topic2a-plasmodium-spp.qmd
        - topic2b-lifecycle.qmd
        - topic2c-immunity.qmd 
   - part: topic3-intro.qmd
        chapters: 
        - topic3a-anopheles-trans.qmd
        - topic3b-environment.qmd
        - topic3c-human-behaviour.qmd

In each of these instances the title that is in the .qmd file becomes the heading that is shown on the final website as shown in the image above.

Note

Once you start adding .qmd files with module content make sure to replace the defualt files and include these in the _quarto.yml to ensure the modules are displayed on the site. Often I start adding content to the templates and renaming the files before creating new .qmd files

1.8.2 Adding custom styling

We’ve already created custom PATH theming and I’ve saved all the necessary files in the data-fellows box folder under ‘quarto-theming’ Data fellowship program planning → Technical Content Organization → quarto-theming

Copy all of these into your root folder and add the following to your _quarto.yml file

format:
  html:
    theme:
    - cosmo
    - custom.scss
    template-partials: title-block.html
    css: include/webex.css
    include-after-body: include/webex.js
    embed-resources: true 
  pdf:
    documentclass: scrreprt
editor: visual

1.8.3 Embedding PDFs

If you have a slide deck to host on the website we first need to save this as a pdf and ensure it it then saved in the same root directory of our Quarto project.

You can use the following syntax to embed the pdfs inside a .qmd file replacing the file name with the associated file name of your file.

<iframe src="file-name.pdf" width="800" height="600">

</iframe>

1.8.4 Embedding YouTube Videos

If you want to include videos hosted on YouTube an easy was to achieve this is with the following syntax, replacing the link with that to the video of interest:

1.8.5 Interative Quizzes

You can use the webexercises package to produce quizes and is what I used in the Foundational Epi module

The documentation is a good place to start here and the source code in the Foundational Epi Module repository if you want to develop something similar!

1.8.6 Publishing content

Once you have created the necessary module content in .qmd files, have updated the _quarto.yml file with the correct references for each chapter we can again push out changes to github and check out our newly published site!

Remeber:

git add . 
git commit -m "commit message" 
git push

And it’s as simple as that!

1.9 Wrapping It All Together: Maintaining Your Quarto Project

By following these steps, you’ve built a robust workflow for creating, managing, and publishing your Quarto Book from scratch. Here are a few final tips to help you maintain and expand your project effectively:

  1. Iterating on Content Content updates:
    • As your project evolves, you’ll likely need to update chapters or add new ones. Remember, every time you modify a .qmd file or create a new one, ensure that the _quarto.yml file is updated accordingly. Push these changes to GitHub to automatically deploy updates.
    • Version control: Keep track of your content changes by writing clear commit messages. This makes it easy to refer back to previous versions if needed.
  2. Troubleshooting Common Issues:
    • Build failures: Sometimes, your GitHub Actions may fail due to misconfigurations or syntax errors (e.g., in the _quarto.yml file). GitHub provides detailed logs for failed builds in the Actions tab, which can help pinpoint the issue.
    • Rendering issues: If the published site doesn’t display content as expected, double-check that your .qmd files are properly linked in the _quarto.yml file and that all references (images, links, etc.) are correctly specified.
  3. Collaboration and Feedback Collaborative development:
    • If you’re working with a team on the resources, consider using GitHub’s collaborative features like Pull Requests to review changes before they’re merged into the main branch. This can help catch errors early and maintain consistency across the project.
  4. Ensure that your project dependencies (tracked by renv.lock) are up to date by regularly running renv::snapshot() after installing new R packages. This ensures that your environment remains consistent across different systems.