10:00
2024-08-28
Understand the purpose of and benefits of a lab group handbook
Gain a basic understanding of what Quarto can do
Get set up using GitHub if you aren’t already
Create a repository from a template on GitHub
Edit Quarto markdown documents and YAML configurations to customize your group’s handbook
From Tendler et al. (2023):
Communicates lab ethos
Normalizes and communicates expectations
Improves equity among lab members
Streamlines and standardizes onboarding and offboarding
Many different ways to organize this information
Other good lab handbooks:
“An open-source scientific and technical publishing system”
The successor to RMarkdown (but don’t worry if you’ve never used RMarkdown!)
Combines prose, code, and code output into a variety of output formats
A platform for sharing files (often code)
Enables collaboration via git, a version-control tool
Automated deployment of rendered Quarto book to the web
Controlled way of merging edits and contributions to your book
It is a time investment to learn these tools
Useful in academia and highly transferable skills (Braga et al. 2023)
Example uses:
Collaboration (on code, data, manuscripts, etc.)
Setting up a course website
Goal: get RStudio set up to work with git and GitHub
A central place for all the lab’s projects
Allow you to manage team members access
When a member leaves your lab, their code stays in the lab organization
Tip
Learn more about GitHub organizations and how to create one: https://docs.github.com/en/organizations
Click the “+” button in the upper right and choose “New Organization”
Choose a plan (the free plan is likely all you need)
Follow the prompts to create your organization
Go to our template on GitHub and click the “Use Template” button
(Optional) choose your newly-created GitHub organization under “Owner”
Give your repo a name, e.g. “scott-lab-handbook”
Next you need to clone your repository locally, so you can work on it on your computer
In your repo on GitHub, click the green “< > Code” button, copy the url
In RStudio, new project > from version control > paste url
Edit the README, commit, push, and check GitHub
Run quarto preview
in the terminal to see a live preview of your lab handbook!
10:00
myreport.qmd
--- title: "My Report" author: "Eric Scott" format: html: toc: true --- ```{r} #| label: load-packages #| include: false library(tidyverse) library(gapminder) ``` ## Data My data source is the [gapminder](https://www.gapminder.org/) dataset. ```{r} head(gapminder) ```
--- title: "My Report" author: "Eric Scott" format: html: toc: true --- ```{r} #| label: load-packages #| include: false library(tidyverse) library(gapminder) ``` ## Data My data source is the [gapminder](https://www.gapminder.org/) dataset. ```{r} head(gapminder) ```
--- title: "My Report" author: "Eric Scott" format: html: toc: true --- ```{r} #| label: load-packages #| include: false library(tidyverse) library(gapminder) ``` ## Data My data source is the [gapminder](https://www.gapminder.org/) dataset. ```{r} head(gapminder) ```
--- title: "My Report" author: "Eric Scott" format: html: toc: true --- ```{r} #| label: load-packages #| include: false library(tidyverse) library(gapminder) ``` ## Data My data source is the [gapminder](https://www.gapminder.org/) dataset. ```{r} head(gapminder) ```
--- title: "My Report" author: "Eric Scott" format: html: toc: true --- ```{r} #| label: load-packages #| include: false library(tidyverse) library(gapminder) ``` ## Data My data source is the [gapminder](https://www.gapminder.org/) dataset. ```{r} head(gapminder) ```
--- title: "My Report" author: "Eric Scott" format: html: toc: true --- ```{r} #| label: load-packages #| include: false library(tidyverse) library(gapminder) ``` ## Data My data source is the [gapminder](https://www.gapminder.org/) dataset. ```{r} head(gapminder) ```
--- title: "My Report" author: "Eric Scott" format: html: toc: true --- ```{r} #| label: load-packages #| include: false library(tidyverse) library(gapminder) ``` ## Data My data source is the [gapminder](https://www.gapminder.org/) dataset. ```{r} head(gapminder) ```
Markdown is a “markup language” that let’s you write plain text to indicate formatting. For example:
**bold text**
becomes bold text
~~strikethrough~~
becomes strikethrough
$E = mc^2$
becomes \(E = mc^2\)
[link](https://www.google.com)
becomes link
`code()`
becomes code()
Check Help > Markdown quick reference in RStudio
Makes editing Quarto documents a lot like editing a Word doc
Explore creating sections, lists, tables, images, callouts, and references
Open the “add anything” menu with
Save changes, practice commit & push
Note
You don’t need to use shortcodes, but there are some already in the template.
Shortcodes look like {{< something something >}}
and get replaced on render with something (text, icons, videos, etc. depending on the shortcode)
For an example, see contributing.qmd
Some shortcodes are built-in (like the meta
shortcode) and some are from extensions (like the fa
shortcode)
YAML works with nested key: value
pairs.
Nesting is indicated with indentation
Use _quarto.yml
to configure your book including adding new chapters and controlling chapter order.
Tip
Indentation is a common source of frustration with YAML—the wrong number of spaces can completely break things.
Create a new .qmd file
Give it a title with a level 1 header (# Title
)
Add that chapter to _quarto.yml
(Optionally) link to it in other chapters with [link text](filename.qmd)
In README.md
In _quarto.yml
book: title:
book: repo-url
book: author:
book: date:
chapters:
In code-of-conduct.qmd
GROUP_NAME
, PI_NAME
, and PI_EMAIL
In content (all .qmd files)
.callout-important
boxes—these are just prompts to give ideas for contentIn the terminal…
quarto preview
processquarto render
quarto publish gh-pages
After manually publishing this first time, you should (🤞) be able to just push changes to GitHub and it will automatically re-publish your book!
This happens because of a GitHub action included in .github/
Try another round of edit, save, commit, push and then check the “Actions” tab of your GitHub repository.
Quarto.org, especially the section on books.
The #quarto channel on UA Data Science Slack