Open textbooks with Quarto and GitHub

Dorien Huijser
Neha Moopen
Kim Deckers

2024-05-16

Content

  • Introducing R, RStudio, and Quarto
  • Our very first Quarto book
  • ☕ BREAK
  • The git workflow
  • Host book on GitHub pages
  • ☕ BREAK
  • Interactivity options (demo)
  • Publishing and archiving

R, RStudio and Quarto

R and RStudio

R logo

Programming language

RStudio logo

Pretty interface to interact with R (and git, and Quarto)

The Rstudio interface

Quarto

“An open-source scientific and technical publishing system”

  • Documents with text and code (R, Python, bash, etc.).

  • Turn text documents (.qmd) into html, pdf, epub, docx and more. Code is automatically executed.

    Today: 💻 html (documents that can be hosted on the web)

  • Many output types: book, slides, blog, article, website, etc.

    Today: 📖 book

Our first Quarto book

Dora the explorer

KIOfficialArt, CC BY SA 3.0

Follow the steps here:

https://quarto.org/docs/books/#quick-start

Files

  • _quarto.yml: settings
  • index.qmd: title page/homepage
  • [chapters].qmd: other book chapters
  • references.bib: references to be used in the book
  • cover.png: book cover image

Markdown

In your chapters, you write in Markdown

Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. - Markdown Guide

  • Agnostic way of formatting text.
  • Can be automatically converted to specific outputs, such as html, pdf, etc.
  • Type literally, or use Visual Editor mode!

See https://www.markdownguide.org/cheat-sheet/

Embed multimedia

Embed an image: 
![penguins](https://allisonhorst.github.io/palmerpenguins/reference/figures/lter_penguins.png)

Embed an image:
penguins

Embed a video in Quarto:
{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}

See also Quarto documentation for videos

Embed a video in Quarto:

✍️ Make a change in your book

  1. In the _quarto.yml file:
    1. Change the title and authors
    2. Add to the _quarto.yml:
    project:
  type: book
  output-dir: docs
  2. In one of your chapters:
    1. Format some text
    2. Embed an image or video of your choice
  3. Render your book!

☕ BREAK 1

The git workflow

Git and GitHub

Git logo

  • Version control software
  • Versions of a file are stored as “commits” that can be reverted
  • Not necessarily online, can be on your personal laptop

GitHub logo

  • Website to store git-tracked files
  • Collaborate on files and make suggestions for improvement
  • Also allows hosting html files online (GitHub Pages)

Git workflow

flowchart LR
  A(fa:fa-pencil <b>Make change</b><br><i>Collect to be sent items</i><br><img src="https://images.pexels.com/photos/6068969/pexels-photo-6068969.jpeg"/>) --> B
  B(fa:fa-archive <b>Stage</b><br><i>Put in package</i><br><img src="https://live.staticflickr.com/1560/25069988352_98dd8f1c8d_b.jpg"/><br><code>git add your-edited-file</code>) --> C
  C(fa:fa-tag <b>Commit</b><br><i>Add packaging label</i><br><img src="https://live.staticflickr.com/65535/52177106715_98e603fdf5_b.jpg"/><br><code>git commit -m 'made x update'</code>) --> D
  D(fa:fa-paper-plane <b>Push</b><br><i>Send package</i><br><img src="https://upload.wikimedia.org/wikipedia/commons/2/22/PostNL_Pakket-_en_briefautomaat%2C_Almere_%282020%29_04.jpg"/><br><code>git push</code>)

✍️ Practice the git workflow

Do this once (together):

  1. In RStudio Terminal, type git init > ENTER

  2. Commit all changes:

    git add -A .
git commit -m "Initialize Quarto book"

Now practice (by yourself):

  1. Make a change in one of your chapters
  2. Add + commit the change

✍️ Put the Quarto book on GitHub

  1. Go to https://github.com/ and log into your account

  2. Create a new GitHub repository

    1. Use same name as your local Quarto book
    2. Initialize without README

  3. Connect your local git repository to the GitHub repository

    1. On GitHub, look for “…or push an existing repository from the command line”
    2. Copy the code into your RStudio Terminal > ENTER

  4. In RStudio, push all changes to GitHub:

    git push

  5. Refresh GitHub page: your files are now here!

See also https://utrechtuniversity.github.io/open-textbooks/get-started.html#make-your-project-a-git-repository

✍️ Put the book on GitHub pages

In the GitHub repository, go to:

  1. Settings
  2. “Code and automation” > “Pages”.
  3. “Build and deployment”
    1. Source: Deploy from a branch
    2. Branch: main
    3. Select folder: /docs
  4. Wait for a bit
  5. Navigate to https://yourusername.github.io/yourrepositoryname

Now, every time you push to GitHub, your edits will come on the website!

Bonus: Status, history, reverting

“What has been edited and staged?”

git status

“What has been changed in this file?”

git diff your-file

“What has been previously committed?”

git log

“UNDO, UNDO, UNDO!”

# Undo staging
git reset yourstagedfile

# Undo last commit
git revert HEAD

☕ BREAK 2

Interactivity

Possibilities discovered so far:

  • Images, videos, diagrams
  • Embed (public) H5P content
  • Simple exercises with {webexercises} R package
  • Tabsets to split content
  • Dropdowns to hide content (html)
  • Glossary with {glossary} R package
  • Discussions for book chapters

✍️ Documenting the book

Add in the GitHub repository:

If you add these directly in GitHub, also Pull your changes to your local folder!

git pull

✍️ Archiving the book

  1. Log into Zenodo (or Zenodo Sandbox)
  2. Link your Zenodo account to ORCID ánd GitHub account
  3. In Zenodo, go to Settings > GitHub, and “Flip the switch” of your to-be-archived repository.
  4. In GitHub, create a Release.
  5. Published!
    1. If needed, edit the Zenodo metadata.
    2. Add the DOI badge to the GitHub repository and the book.

Steps are outlined here with screenshots

YOU MADE IT!

Open textbooks for EduSupport @ UU