26  Editing the Manual

Modified

December 19, 2024

26.1 Overview

This guide is a Quarto Book hosted on the HerbVar Network’s Github site. Any HerbVar member can edit the manual, add new sections, or make suggestions for improvement either via pull request, posting an issue on the HerbVar Manual’s repository, or editing the manual directly.

26.2 How to Edit the Manual

26.2.1 Getting Started

Quarto is the next-generation of R Markdown. Like R Markdown it allows for rendering files in multiple formats (.pdf,.docx., .html) and it can be used to make websites, reports, and presentations, but it has the advantage of being able to run embeded code chunks in multiple languages (e.g., R, Python) and allowing users to execute code (i.e., for demonstrations) in the rendered quarto file. Users of Markdown / R Markown will recognize the structure and format of quarto files (.qmd), and the content of R Markdown files can be executed in .qmd files.

Tip

A tutorial on getting started with Quarto and RStudio can be found here. Posit (née ‘R Studio’) has also prepared an excellent Quarto Cheatsheet that will prove very helpful.

To edit the manual you will need a Github account and RStudio. The process for editing the Manual is:

  1. Install the quarto package
  2. Fork the Herbvar Manual’s Repository and clone it into your personal Github
  3. Edit files (or create a new ones)
  4. Commit and push the changes
  5. Submit a pull request with your suggested edits

Step 1. Open R Studio and install the quarto package using either the ‘install’ button on Rstudio or by executing the following command.

from the R Studio Command Line
install.packages("quarto")

Step 2. Fork the repository for the HerbVar Manual [repo link] from the HerbVar Organization Github into your personal Github account (tutorials here and here).

Step 3: Edit files (or create a new ones). You can format your text using markdown syntax (see this cheetsheet), but if you would prefer to edit text and simply leave formatting notes (e.g., “bold this”, species names in italics”) that’s fine too.

Step 4: Commit and push the changes using RStudio (or the command line if you feel the need to flex).

Step 5: Submit a pull request so the Manual’s ‘Administrators’ can review and incorporate your suggested edits. (tutorials: how to submit a pull request from a forked repo here, general introduction here and here.)

26.3 Publishing the Manual (Admins Only)

The admins of the repo can publish the book in HTML (to a Github pages site) and as a pdf (on the repo). There are three ways for a Admin to publish Quarto documents to GitHub Pages(see here):

  1. Render sites on their local machine to the docs directory, check the rendered site into GitHub, and then configure the GitHub repo to publish from the docs directory.

  2. Render on their local machine and then use the quarto publish command to publish content rendered on the local machine.

  3. Use a GitHub Action to automatically render files (a single Quarto document or a Quarto project) and publish the resulting content whenever a source code change (e.g., any edit of the manual) is pushed to the repository.

We are currently using Github Actions to automatically render and publish any time a change to the manual is committed and pushed to Github. However, if there is ever an issue with gh-action, or if you want to try the manual way of rendering/publishing, you can do the following: (1) Use the quarto render command from the Terminal to render all output formats (the output of your book will be written to the _book sub-directory of your book project), then (2) use the quarto publish gh-pages command to publish the locally rendered content online (more detailed instructions can be found here).

Rendering the manual:

from the Terminal
quarto render

Note that if you pass no arguments to quarto render as above, all formats will be rendered. You can instead render individual formats via the –to argument:

from the Terminal

quarto render           # render all formats
quarto render --to pdf  # render PDF format only

Publishing the manual:

from the Terminal
quarto publish gh-pages