Editing These Protocols with Quarto

Edit this page

---

The “Edit this page” link at the top of each page will direct you to the GitHub repository where you can directly make edits to the contents of each page.

You will need to know Markdown to understand how to format your edits! Here is a cheat sheet

Adding an image

Add images to the /img folder and use relative paths to source them. See the Kayak page for an example.

Adding a new page

Create a new .qmd file and give it an informative name without spaces:

.

.

Add your new page to the quarto.yml file where you want it to appear in the table of contents. But be careful to get the spacing right! Quarto is very picky about everything lining up correctly:

Check that your changes to the site rendered online!

After you commit your edits, check that they show up on the website! We have the site set up so that it will automatically render to html and publish, thanks to GitHub Actions. This process takes a few minutes, so your changes may not show up right away.

Some information that is useful to know for troubleshooting, if your edits don’t show up on the site: - The way that the GitHub Action works it to take commits on the main branch and build the .html files on the gh-pages branch - You can check that the Action completed by clicking on Actions button in the horizontal links at the top of the page - If you see a red X by the last commit, then you changes did not render properly into a website. You can click on the action to learn more about what went wrong.

Creating your Quarto website

If you would like to create your own Quarto website, go here. If you already have your Quarto website created and want to know more about how to build out your website, go here.

An in-depth Quarto tutorial exists here.

1. Download Quarto app
   • Quarto is an open-source publishing system that works with R Markdown to create high-quality articles, websites, or books
2. Connecting the Quarto app with R
   • Make sure you have the latest release of RStudio downloaded
   • Be sure that you have installed any packages that it prompts you to - If you’re using a mac, you may need to install XCode’s Command Line Tools before installing R packages to connect Quarto app with R - when installing R packages, if R asks whether to install some packages from source, you should enter ‘yes’
3. Download the Quarto document (.qmd), open it in RStudio, and click Render
   • When you render a Quarto document, knitr executes all of the code chunks and creates a new markdown (.md) document which includes the code and its output
   • The markdown file generated is then processed by pandoc, which creates the finished format
   • The Render button encapsulates these actions and executes them in the right order for you
4. Creating your Quarto website
   • To create a new website project within RStudio, use the New Project command and select Quarto Website
   • You may create a new directory or attach it to an existing directory
   • To attach the protocols website to the GitHub, we created a new website as a subdirectory of the main GitHub branch on GitHub Desktop

Structuring your Quarto website

• Your Quarto website should come with some basic, starter files:
  1. index.qmd: the home page for your Quarto website
  • This is a REQUIRED file which includes the preface, acknowledgements, etc.
  2. _quarto.yml: the contents of your Quarto website
  • This is where you will divide your website into sections…. and within sections, you can divide it further into contents

Publish your Quarto website to Github

Basically, what you will do is have a main branch on your site and publish the .qmd files from that branch as .html files on the gh-pages branch. GitHub will automatically read anything on the gh-pages branch and publish it to the web.

• overview here

• Create your website on your local machine and sync to github

• Create gh-pages branch on github

• On your machine or on github

  • Update your .gitignore
  • Add a .nojekyll file
  • add the “execute: freeze: auto” to the end of your .yml (see this webpage for example)
  • if you made the last edits on your machine, sync to the web with GitHub Desktop

• Next follow these instructions to:

  • On your computer - run quarto publish gh-pages locally, once
    • you will need to input your github token as a password instructions
    • make sure your token settings will grant access!
  • On your computer - sync to github with GitHub Desktop
  • On Github - in Actions section of your repository Settings - [ ] checking the Read and Write Permissions box under Workflow permissions per instructions - [ ] check “Allow github actions to create and approve pull requests”
  • On Github - add a publish.yml GitHub Action per instructions

If it works, you should be able to check the Actions and see pages render and publish when you make edits.