2  Getting started with a Quarto book

2.1 Create a Quarto book

Follow the Quickstart intstructions for Rstudio from the Quarto documentation to create an empty Quarto book.

2.2 Check the basic settings

Open the _quarto.yml file. Make sure it at least contains something like this:

project:
  type: book
  output-dir: docs              # When rendering, the html files will be 
                                # placed in the docs folder. The folder needs
                                # to be named docs in order for GitHub pages to work!

book:
  title: "YOUR BOOK TITLE"
  author: "YOUR NAME"           # Book authors: add a new row for each new author
  date: "YYYY/MM/DD"            # Date of the book, you can also use 
                                # last-modified, or today (without quotes)
  chapters:                     # Table of contents
  - index.qmd                   # Home page, should always be index.qmd
  - YOUR-CHAPTER-1.qmd          # Each chapter has its own .qmd file
  - part: "Title of this part"  # You can also introduce sections with subsections with "part"
    chapters: 
      - YOUR-CHAPTER-2.qmd
      - YOUR-CHAPTER-3.qmd
  - YOUR-CHAPTER-4.qmd

bibliography: references.bib  # If you want to use a reference manager, we'll come back to this later

format:                       # For open textbooks on the web, we only need html
  html:                       # It's also possible to add pdf, epub and docx if you want
    theme: cosmo              # Default styling, there are many others!

See the quarto-settings chapter for more customization options.

2.3 Make your project a git repository

  1. In RStudio, go to the Terminal (next to Console) and type git init. This will turn your project folder into a git repository.
  2. In the terminal, type git status. This will give you all uncommited changes you’ve made. To commit all these changes at once, type:
git add -A .
git commit -m "Initialize github textbook"
  1. In GitHub, create a new, empty repository
    1. For owner: choose where you want to create the repository (e.g., under your name or possibly under a GitHub organization).
    2. For Repository Name, it’s best to use the same name as you named your local Quarto book folder.
    3. Leave all other options empty for now.
    4. Click Create repository
  2. A new empty repository will now be created on GitHub. Now we want to connect this GitHub repository with the repository that you have already made on your local PC. To do so, copy the code that GitHub conveniently already gives you under or push an existing repository from the command line. For me this looks like this: Copy this code in the Terminal in Rstudio, and run it.
  3. Practice the git workflow of adding content, comitting the changes, and pushing the changes to GitHub. The basic steps are laid out in the Working with git chapter.

2.4 Host on GitHub pages

Now that you’ve pushed your basic book to GitHub, you need to tell GitHub to host the html files online.

  1. Navigate to your repository on GitHub (https://github.com/yourusername/yourrepositoryname).
  2. Go to the repository’s Settings Printscreen of repository page with Settings menu item highlighted
  3. Under “Code and automation” in the menu on the left, click “Pages”.
  4. Under ” Build and deployment”, select:
    1. Source: Deploy from a branch
    2. Branch: main
    3. Select folder: /docs
  5. Wait a few minutes while your website is being built.
  6. After a while, GitHub will tell you “Your site is live at yourusername.github.io/yourrepositoryname”!