Contributing
You can contribute to this book by making small edits or writing entirely new chapters. From small to large, all contributions are welcome. If you are in need of specific information, you can skip ahead using the table of contents.
You need a GitHub account to contribute. You can create one directly on GitHub.
Suggesting edits
The easiest and quickest way to contribute to the book is make suggested edits. On each page you will find a button reading “Edit this page” (usually on the right).
When you click that, you will immediately be taken to GitHub to edit the text of that specific page. You may be prompted to create a fork (forking) in case these are your first edits.
Once you made your edits, you are ready to commit (save) your changes and submit your pull request, requesting those changes to be included in the handbook.
Adding a chapter
To add a new chapter, you need to create a new file ending in .qmd (e.g., chapters/example.qmd). You can do this by visiting the handbook page on GitHub and clicking Add file -> New file.
When you click this button you may be asked to fork the repository. This is not a problem so go ahead!
The chapter itself needs to be written in Markdown. Every chapter must contain a first level heading (e.g., # Heading), which will be the chapter title. Section headings are second level headings (e.g., ## Section).
After that, you are ready to submit your pull request! The reviewers will help you place the chapter in the right place of the book.1
Submit a pull request
Once you have made suggested changes, a pull request is the way for you to ask for your changes to be incorporated into the handbook. The people maintaining the handbook will review what you wrote, ask some questions, and accept or decline your contributions.
We recommend keeping your suggested changes small or limited in scope, and explaining why you are suggesting these changes. It is more likely your changes are included when you are fixing a typo or adding a paragraph, and less likely if you are revising the entire handbook. It is also more likely they are included if you explain why you are suggesting the changes, rather than dropping by and making edits without any context.
If you are adding a new chapter, it is definitely recommended to open an issue first to see whether there is a need for it (and maybe you’ll find collaborators!).
During the review process you may be asked to update your changes, or revisions may be added by the people maintaining the handbook. It is helpful if you keep an eye on your GitHub account to ensure timely responses to help the process along.
Writing text
The book is created using Markdown - you can get familiarized with the basic syntax on the Markdown website. The getting started quick items are:
# Heading level 1
## Heading level 2
### Heading level 3
You simply write text as you are used to. To make something *italic*, **bold**, or ***bold and italic***.
> this is how you add quotes
- or lists
- that can go on
- and onIf you want to add code, use references, create links, or footnotes - it is all possible. We will expand examples here based on your needs, so if you need help, let us know by reporting an issue!
GitHub
We use GitHub to create this website automatically, and to manage all the incoming updates. You do not need to know how it works entirely, but we want to help you understand some things so you are not confused.
Repository
A repository on GitHub is like a folder on your computer. This can be many things, depending on what files it contains.
When we mention a repository here, we mean that we want you to look at a specific folder. The repository for this website for example can be found on GitHub directly](https://github.com/ubvu/handbook-template). You will always be contributing to a repository, in order to contribute to the handbook.
Forking
A repository is owned by one or multiple people on GitHub. If you are not one of them, you can create a copy of the repository (folder) to make your edits in. This act of creating a copy is called “forking.”
When you create a copy, you do not have to worry about accidentally removing or destroying the handbook. Your changes are not reflected in the website until you submit a pull request.
If you are really enthusiastic and want to do it yourself: The chapter needs to be added to the chapters list in
_quarto.yml. You can find the chapters list around line 24 of that file.↩︎