Working with GitHub pages and Quarto to edit documentation

Using Quarto to write documentation in a GitHub repository

This documentation site is built using Quarto and hosted using GitHub Pages. The rationale for using this approach is summarised in Why Quarto.

How to contribute documentation

Edit in GitHub - for small changes

Here are the steps to make small edits directly in GitHub:

  1. Open the repository in github.com for this documentation site.
  2. Browse to the file
    • *.qmd files in your content folders.
  3. Click the pencil icon (“Edit this file”)
    • GitHub opens an in-browser editor for that file.
  4. Make the change and commit
    • Add a short commit message.
    • Either commit directly to the main branch (if allowed) or create a new branch and open a pull request.
  5. Approval of change and deployment
    • Your changes may need approval, which case a pull request will be set up and once approved the site will be automatically rebuilt.

Edit locally - for larger changes

One-time setup

  1. Clone the repository to your local machine
    • git clone https://github.com/Laboratory-of-Gene-Regulation-Oxford/bpe-doc.git or clone using vs code git extension.
  2. Set up your local environment
    • Follow any setup instructions specific to this repository.
  3. Install Quarto in vs-code
    • Download and install the vs-code Quarto extension

Making changes

  1. Open the repository in your local editor
    • Open the folder you cloned in your code editor (e.g., VS Code, RStudio).
  2. Edit the files
    • Make changes to the *.qmd files as needed.
  3. Preview your changes
    • Use Quarto’s preview features to see how your changes will look.
  4. Commit and push your changes
    • Use git to commit your changes with a descriptive message.
    • Push your changes to your fork or branch on GitHub.
  5. Create a pull request
    • Open a pull request on GitHub to propose your changes for review.
  6. Approval of change and deployment
    • Once your pull request is approved, the site will be automatically rebuilt and your changes will go live.

Quarto

Quarto enables you to weave together content and executable code into a finished document. To learn more about Quarto see https://quarto.org.