10  Updating this document

The intention is that this document serve as a “living” lab manual that is constantly updated/adapted as necessary. To facilitate this, I have included the following basic guide. Updating the lab manual requires Git(Hub) and R(Studio) but I have written the guide with the intention that those with no prior experience can proceed without too much hassle. Note that although the basic steps will likely remain the same in the years to come, there may be minor deviations due to updates to the requisite software packages. For non-lab users that are interested in adapting this manual, I suggest using the Fay Lab’s manual (the original template) and their accompanying guide.

  1. Install the latest versions of R and RStudio/Posit

  2. Install the latest version of Quarto

  3. Install the latest version of Git and create an account on GitHub

  4. Request administrator access to the GitHub project for the lab manual via email (ericmah@uvic.ca)

  5. In RStudio, create a new project (“File” -> “New Project”), and select “Version Control”, and “Git”

  6. On the GitHub page, click the green “Code” button, navigate to the “Local” tab, and select “HTTPS”. Copy the link in the box below

  7. Paste this link into the “Repository URL” box in RStudio. When selecting a folder (subdirectory) for the project, it doesn’t matter where you put it, but you should avoid putting it in any cloud storage folders (Dropbox), as these can interfere with Git.

  8. Once you confirm, RStudio will clone the files to the local folder that you specified.

  9. You are now ready to edit the manual. A complete guide to formatting markdown files using Quarto is beyond the scope of this manual, but see this link for a comprehensive guide. Quarto has a visual editor UI that is quite similar to traditional word processors (e.g., Word). Below, I include a couple common changes that you might want to make:

    1. Adding a new page: The simplest way to do this is to create a new Quarto markdown (.qmd) document, or copying one of the existing markdown files (e.g., 01-introduction.qmd). To add the new page into the manual, open the “_quarto.yml” file, and add the new page to the “chapters” section near the bottom of the file in the position that you want it. It is recommended (but not required) that you update the names/numbers of the existing pages for any new order that you create.

    2. Editing existing pages: This is done simply by opening, changing, and saving the existing .qmd files. The landing page for the lab manual is the “index.qmd” file. See the formatting guide linked above for tips on formatting various kinds of content.

  10. Once you have made the desired changes, you will need to “push” them to GitHub. This can be done by navigating to the terminal (bottom-left box in RStudio) and inputting the following bolded commands (except anything in parentheses):

    1. git add –A

    2. git commit -m "Your message here" (In the quotations, enter a short message describing your changes) c

    3. git push (You may be prompted to enter your GitHub password here)

  11. Now that the changes have been made to the GitHub, you will need to sync them so that the website link updates as well. Go back to the manual GitHub page, click on “Settings”, and go to “Secrets”.

  12. Click on the “New repository secret” in the upper right

  13. You will be prompted to enter a “Name” for the secret. In this box, enter EMAIL

  14. In the “Value” box, enter the email associated with your GitHub account, and click “Add secret”

  15. Now, any time you commit changes to the manual, it should be updated on the live page. To verify this, you can go to the “Actions” tab on the manual GitHub page, click on the latest “pages-build-deployment” Action once it is completed (green check mark), and then navigate to the lab manual link shown in the “deploy” box

  16. That’s all! Remember to update the contact email(s) in step 4. of this guide to your own.