2  Building from an existing GitHub Repository

These resources are intended for users who are contributing to an existing project hosted on GitHub and want to collaborate on building or updating Quarto-based materials. You will learn how to clone the project, make changes locally, and collaborate with others via GitHub.

Hopefully you have previously run the steps in the Starting Point and are set up with GitHub - if not make sure you follow the steps set out there.

2.1 Step 1: Clone the Existing GitHub Repository

The first step to collaborating is to clone the GitHub repository to your local machine. This creates a copy of the project on your computer, allowing you to work with the files locally.

1. Locate the repository: Visit the GitHub page for the repository you wish to work on. You should see a green Code button on the repository’s main page.

2. Copy the repository URL: Click the Code button and copy the HTTPS URL. For example if you wanted to clone and work on this module:

https://github.com/PATH-Global-Health/quarto-module-dev.git

3. Clone the repository in RStudio
   • Open RStudio.
   • Go to File → New Project → Version Control → Git.
   • Paste the repository URL you copied earlier into the dialog box.
   • Choose where to store the project locally on your computer.
   • Click Create Project.

This will create a local copy of the repository that you can work on. You’ll see the project files in the RStudio Files pane.

2.2 Step 2: Familiarize YourSelf with the Project

Before making any changes, it’s important to understand the structure of the project and its current status.

• Explore the _quarto.yml file: This file defines the structure of the Quarto book (or website) and the order of chapters. Take a look to understand how the chapters are organized.

• Review existing content: Open and read through some of the .qmd files (Quarto markdown) to get a sense of the writing style, structure, and the materials that have already been added.

2.3 Step 3: Set up Your Local Environment

To work on this project, you may need to install the same R packages that the project uses. This is often managed through renv.

1. Activate renv: If the project is using renv, you will see an renv.lock file in the repository. To install the necessary packages, run the following command in the RStudio console renv::restore() This will install all the packages listed in the renv.lock file, ensuring your environment matches the one used by others working on the project.

2. If additional software is needed (like TinyTeX for PDF output) install these.

2.4 Step 4 Make Changes

Now that your environment is set up, you can start working on the project. Whether you’re fixing a bug, adding content, or improving the formatting, here’s how you can proceed:

1. If you are going to be the sole user of the repository now you don’t need to create a new branch - you can skip the next two steps.
2. Create a new branch: It’s good practice to create a new branch for your changes so that you don’t modify the main branch directly. To create a branch, run the following command in the Terminal tab in RStudio:

git checkout -b new-feature-branch

Replace new-feature-branch with a name that describes the changes you are making or perhaps your name for example.

3. Edit or add files: Make your changes to the .qmd files or other assets in the repository. For example, you might want to add a new chapter or modify existing content. As you edit files, save your changes in RStudio.

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.

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.

2.4.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

2.4.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

2.4.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> 

2.4.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:

2.4.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!

2.5 Step 5: Commit and Push your Changes - main branch

If your workflow involves making changes directly to the main branch, follow these steps to commit and push your changes.

1. Stage your changes: First, you need to add the modified files to the staging area. To see which files have been modified, run:

    git status

This command will list the files that have been added, changed, or deleted. Once you’re ready to stage them, run:

    git add .

The . adds all the changed files to the staging area. You can also stage individual files by replacing . with the filename.

2. Commit your changes: After staging your files, you’ll need to commit them to the repository with a descriptive message that explains the changes you made. Run the following command:

git commit -m "Your descriptive commit message here"

Make sure the commit message clearly states what changes you’ve made

3. Push your changes: Once you’ve committed your changes, push them to the main branch on GitHub by running:

    git push origin main

This command will send your local changes to the main branch of the remote GitHub repository. After pushing, your changes will immediately be reflected in the repository and if a [GitHub Action]Section 1.5 to publish has been set up this will automatically be reflected in the online site.

Important Notes:

• Working on the main branch: When working directly on the main branch, it’s important to ensure that your changes won’t disrupt the main project. This workflow is typically used for smaller updates or when a project does not follow a branch-based development model.

• Keep the main branch up to date: Before making any changes, ensure your local copy of the main branch is up to date by running: git pull origin main

• Collaboration caution: If other team members are working on the same repository, communicate to avoid conflicts. Making significant changes directly on the main branch could cause merge conflicts if others are working simultaneously.

2.6 Step 5: Commit and Push Your Changes - new branch

Once you’re happy with your changes, it’s time to commit and push them back to GitHub.

1. Stage your changes: In the Terminal, check which files have been modified: git status

2. Add the changes to staging: If the output looks correct, add your changes to the staging area git add .

3. Commit your changes: Write a meaningful commit message describing what you’ve changed: git commit -m "Added a new chapter on…"

4. Push your changes: Push your branch to GitHub git push origin new-feature-branch (change the name to the branch name you are working on)

2.7 Step 6: Create a Pull Request

Now that your changes are on GitHub, you need to create a Pull Request (PR) so that the repository maintainers can review and merge your work into the main branch.

1. Navigate to the repository on GitHub: Once there, GitHub will automatically suggest that you create a pull request for your new branch.

2. Open the Pull Request: Click the Compare & pull request button. In the PR description, explain what changes you’ve made and why.

3. Submit the Pull Request: Click Create pull request.

4. Once the PR is approved, it can be merged into the main branch by a maintainer.

2.8 Step 7: Keeping Your Fork or Local Repository Up-to-Date

If you are working on a forked repository or need to sync your local repository with the main branch, follow these steps:

1. Pull changes from the main repository: Run the following commands to fetch and merge changes from the upstream (original) repository:

git fetch origin 
git pull origin main 

2. Resolve any conflicts: If there are any merge conflicts, RStudio will show you the conflicting files, and you can resolve them before pushing the changes.