Quarto + GitHub Clinic

Contribute to open educational resources, onboarding docs, and much more

Welcome

This book is an example of a Quarto website that is published via GitHub — Quarto and GitHub are powerful workflows to create and share your work.

Quarto enables us to collaborate on documentation and tutorials — across Python and R languages and varied levels of coding expertise. It lets us share output in many ways, including websites. Importantly, it lets us write and share documentation/tutorials using the same tools we teach research teams for reproducible science.

Quarto enables contributions in R, Python, Observable, Julia, and more for outputs as html, PDF, Word, and more! Illustration by Allison Horst.

Quarto lets us build websites as a collection of files (.qmd, .ipynb, .rmd and others). Today we’ll focus on Quarto’s .qmd files, which are plain-text files that work nicely with GitHub workflows.

The ability for Quarto to streamline collaboration has been so cool and important for NASA Openscapes, so this tutorial will enable you to contribute to the main NASA Openscapes website as well as the NASA Earthdata Cloud Cookbook (both made with Quarto+GitHub.)

Our Plan today

We will learn workflows with Quarto + GitHub for contributing to open source documentation. We’ll cover this in 2 parts:

Part 1. Quarto Workflow: Use the 2i2c Openscapes JupyterHub as an editor: we will contribute to this Quarto site by editing a .qmd file and previewing the changes.

Part 2. GitHub Workflow: Clone the repository for this site, make a branch to work in, commit and push your edits to GitHub, make a pull request, review and merge a pull request, and communicate what you’re doing at each step.

This requires some setup. We’ll do this first, and discuss more as we go.

Prerequisites

To begin, you should have a GitHub account with access to the 2i2c Openscapes JupyterHub.