Contributing to This Book
This chapter walks through the process of how to make changes and contribute to this book directly. While the focus is on writing your own markdown and contributing it via a pull request, please note that’s not the only way to contribute. If you have something to add but aren’t yet able to add a section directly, feel free to write your text in a Google Doc or similar and include it as a link in an issue on the book repo.
Prerequisites
To contribute to this guide directly, you need the following:
- A working knowledge of git and GitHub, in order to add your changes.
- A working knowledge of Markdown. Markdown is a pretty straightforward markup language, and the basics are pretty easy to learn – if you’ve ever sent texts in Slack or Discord, you’ve probably used some form of it before.
You’ll also need a program to edit the Markdown files in. While any text editor will work, the best options are probably one of the following:
- RStudio has a pretty good Markdown editor, with a lot of nice bells and whistles for working with Quarto. There are docs on using Quarto with RStudio on the Quarto website.
- VS Code also works great for Markdown, and has a Quarto extension directly supported by Posit. There are docs on using Quarto with VS Code on the Quarto website.
You don’t really need to know anything about Quarto or any of the processes involved in building the book itself. However, if you want to get particularly fancy with a chapter, everything mentioned in the Quarto documentation should work automatically with this book.
Contribution Workflow
If you’re using RStudio, open the lab-manual
project (either by double clicking the lab-manual.rproj
file or by switching to it in the IDE).
You should always make sure you’re working with the most recent version of the book. Running the commands below in a terminal (such as the one in RStudio’s Terminal tab) will make sure you’re on the primary (main
) branch of the book’s git repository, and that you’ve got the most up-to-date version:
git checkout main
git pull
We tend to use a branch-and-merge workflow with this project, meaning that most editing is done on a separate version of the book with the changes “merged” into the main book once they’re fully complete. To create a new branch, use the following command in a terminal, replacing your_branch_here
with a name that describes your changes:
git checkout -b your_branch_here
Now that you’re on a new branch of the book, you can go ahead and edit to your heart’s content! Each chapter of the book is contained within a single .qmd
file, which are organized into folders based on what section of the book they’re in. These .qmd
files are Markdown documents which are converted into this website automatically; changes to these documents will automatically be reflected in the final rendered version.
If you’re adding a new chapter, you’ll also need to add it to the table of contents by adding it to the _quarto.yml
file. Most of the time, you can copy and paste the entry for another chapter, change the file name to your new chapter’s file, and expect everything to work out. If you have any questions about how to get the structure you want, check out this section of the Quarto documentation.
To preview your changes in the rendered version, press the “Render Book” button in the “Build” tab in RStudio (or the equivalent button in VS Code). This will automatically render the website version of the book (as well as the PDF equivalent), which should then display either in your web browser or in a special pane of your editor. If it doesn’t, then open the index.html
file in the _book
folder on your computer to get the same preview.
Once you’re happy with your changes, you should push them up to GitHub. The following commands will push all of your changes up to a new branch on GitHub – don’t worry, this won’t mess up the live version of the book for everyone else:
git add .
git push -u
Once your changes are on GitHub, you’ll want to open a pull request. In the pull request, include any information about your changes that you think might be useful, and tag at least one person (by typing “@” and then their GitHub handle) to ask them to review your changes. If they don’t have any questions or concerns about your changes, they can merge your pull request, and your changes will now be live on the book for the whole lab to see!