2  Quarto books

In this chapter, you will learn how to create and edit the standard version of a Quarto book. This differs to the specific PsyTeachR template we cover in the next chapter. If you do not want additional features built in like interactive exercises and a glossary function, you may want a more streamlined version. The editing and rendering process is exactly the same, it is just the creation process and additional features which differ.

Intended learning outcomes

By the end of this chapter, you will be able to:

• Create and edit a standard Quarto book using RStudio.

• Publish your book using github pages.

2.1 Example book and Quarto documentation

For an example of the standard Quarto version, you can explore this very book on Dissemination using Quarto and Github Pages! If there is a feature you like, you can see the source code on github to adapt to your needs.

Your main source of information for this output is the Creating a Book section of the Quarto guide.

2.2 Creating a Quarto book

If you would like a video walkthrough of this chapter, you can follow the steps via YouTube:

If you have not followed the preparation instructions yet, you need R/RStudio and git/github desktop installed on your computer. I will be demonstrating how to use github desktop rather than the command line, as git could easily be it’s own workshop.

The first step is thinking about where you want your book folder stored on your computer for where all the files will live. I have a folder within Documents called git_repos where I store all my git repositories away from OneDrive (see below).

Do not create github repositories within OneDrive

We have not reached the github step yet, but as you think about where you want your folder for the book, please do not use a folder within OneDrive. Sometimes it works, but most of the time it causes chaos as OneDrive is trying to track changes, github is trying to track changes, which ends in them fighting over file permissions.

Once you have decided where your book will live, open RStudio and click File > New Project... > New Directory > Quarto book. This will be the process we follow for all the Quarto outputs and you see there are options for a range of documents like websites and blogs.

You will see a new window asking for you to specify:

• “Directory name:” - the name of the folder it will create, so keep it short and without spaces.

• “Create a project in the subdirectory of:” - click browse to navigate to the folder you want your book to live in. Creating the book will create a new folder within this directory, so you do not need to create a folder for the book yourself.

Click “Create project” and after a couple of seconds, it will open a new project window with the template in.

Congratulations, you have a book skeleton to work with!

2.3 Tour of the Quarto book template

1. _quarto.yml

We will start by exploring the _quarto.yml file where you can edit all the details for your book, like the title, author(s), and the licence. In Quarto books, this is also how you control the order of chapters.

What is a .yml file?

YAML / .yml are configuration files for programs which must follow specific formatting conventions.

Within the .yml file, I will highlight in the workshop key features such as: project, book, bibliography, csl, and format.

For presenting your book using github pages, edit the project from the standard first two lines:

project:
  type: book

To add a new third line:

project:
  type: book
  output-dir: docs

Be careful, indentation is important in .yml files. We do this as by default, it will create a folder called _book where the rendered .html files will live. For github pages though, it looks for a folder called docs, so this will streamline things later.

Add a license for your work

One important consideration is telling people how they can use your work. In the .yml, you can specify a license (see the License section of the documentation) and make this super clear in the footer of your output. I like to specify this using the following settings under website:

book:
  license: "CC BY-SA"
  page-footer: CC-BY-SA-4.0 (2025) James Bartlett

I usually apply a CC-BY-SA license from Creative Commons as one of the most permissive licenses for reusing work, but they must provide attribution. You can look at the Creative Commons site for different license options.

2. index.qmd

Index will be the opening page for the link to your book, so this will typically include an overview of what your book contains, who to contact for problems/questions etc.

3. Chapter files

By default, you get an example index.qmd and a few other example chapters like intro.qmd, summary.qmd, and references.qmd. The example chapters demonstrate some features of Quarto but you can delete this text or create your own files to start writing chapters.

You will need one level 1 header (# Chapter title) to start the file, and that will be the name of your chapter at the top of the page and in the table of contents.

Warning

Make sure you only use one level 1 header per chapter. If you try and add multiple within one file, it will think they are separate chapters and try and split them when it renders, making it look weird.

Once you start adding multiple chapters, remember to update the .yml file for the order you want them in your book.

Tip

Depending on what you want to include in your book and how complicated it becomes, you might want to separate chapters into different sections. The indentation can be frustrating, but you can add parts to the book: section of the .yml like:

book:
  chapters:
    - index.qmd
    - workshop_prep.qmd
    - part: "Writing Books"
      chapters:
        - quarto_books.qmd
        - psyteachr_template.qmd

4. references.bib

In the .yml, you can specify a BibTeX file (.bib) to add formatted citations and references. The template comes with an example for how a citation and its reference will look. A .bib file stored information for referencing like authors, the journal, the DOI etc. The Quarto file will take this information and present it as a citation. The Quarto features chapter explains how to use a .bib file to format citations and specify a specific citation style.

5. Rendering files

Once you have finished editing or you want to check how it looks, you need to click Render for Quarto to process the code and turn it into something pretty. Once you click Render once, you can open it up in the browser and keep checking as you make edits. When you want it to rerender, click Reload the page and it will show your new edits.

Caution

If you introduce an error, you will get an error and red box on the screen to highlight Quarto cannot render the book. If you look in the Background Jobs tab in the console below, you should get an error message for the source of the problem if you are unsure what you did wrong.

After an error, you will need to press Render again rather than just refreshing the browser.

These are the key components to make your book. Until this point, these edits all exist on your own computer. But now it is time to track your code using github and make your book accessible online via github pages.

2.4 Creating a github repository

Once you have a working barebones version of your book ready to go, it’s time to associate your book folder with a github repository and start some version control. If you want another resource, you can see the github documentation online.

In future, you could actually start with this part. You can create a new repository/folder with git enabled, and then add your folder when you created a project for the book files. However, we started by creating the book first, so we need to create a repository for an existing folder without a git component. When you are used to the process, you can work out which workflow suits you better.

In the github desktop application, click add >> Create a New Repository and complete the details.

Seriously, do not create github repositories within OneDrive

As a reminder, please do not use a folder within OneDrive for your github repository.

• Name: This will be the name of your repository on github, so call it something short but sensible. It makes sense to call this the same as your book folder wherever possible.

• Local path: Click Choose… and navigate to your book folder. You want the path to be the main folder your book lives in.

• Git Ignore: From the drop-down, select R. By default, git will version control every file but we do not need it to track everything. By selecting R, it will create a git ignore file which tells git which files or file types you do not want it to track.

Select the folder, do not double click

One mistake I make every now and again is opening the folder you want to create a github repository for, rather than just selecting the folder. If you open the folder when selecting the local path, it will create a repository within your folder as a subdirectory. This means it will only apply version control to a level below your main folder and not track the files you want to track.

I will demonstrate how to add a licence in another chapter, so click “Create Repository” when you are ready.

Your newly minted repository should be showing as the Current Repository. This exists on your computer, but it is still not available online. You need to click Publish repository, and that will push all of your files to github and be available online.

Before moving on, go back to RStudio and open up your new .gitignore file which should be visible in the Files pane. Scroll down and around line 42/43 it will say /docs. Delete the comment and /docs as we do want to track these files since they are important for showing your book as a webpage.

Once you save the changes, you will see your first example of version control as Github Desktop will show your edit and all the files within /docs it has now started tracking. Try a commit message saying something like “Track docs on github” and click “commit 1 file to main”. Finally, at the top of the window, click push to origin and your edits will make it to Github. I explain more about the committing and pushing process later in the chapter, but it was important to start tracking docs before we move on.

2.5 Navigating github and github pages

Now your files are available online, navigate to your github account and find your new repository.

I will provide a little overview in the workshop of key things to look out for and what each tab contains.

If you are only interested in using github to work on a book, the key tabs are Code and Settings. In Code, you will see all your files you published. These will all be the same as what you created on your computer. This is the idea behind version control and storing all your code/files like OneDrive.

In Settings, this is where you can edit things about your repository. If you plan on working on your book in a team, you can add collaborators by adding their github profile. They will then receive an email saying you have invited them to collaborate on their github repository. After they accept, they can pull the repository and start working on it too.

Warning

Working collaboratively is one of the main motivations behind git and github, but it can be tricky if you are unfamiliar with more advanced features like merging and clashes. Before you start editing the same repository with someone, I heavily recommend completing units 4 and 5 of the version control Moodle course provided by Maths and Stats.

Click on Settings for the next key section we need to get your book available online.

2.5.1 Publish to github pages

In Settings, navigate to Pages within Code and automation. Under Build and deployment, this will be set to none by default. You must click the drop down, choose Main and select /docs. You will remember /docs is where we store all the html versions of the book files, so you are pointing Github pages here as the source for your book.

When you press Save, this will start building your book. It will not be available immediately and will take a few minutes. When it is ready, at the top of the page, it will say “Your site is live at…” with your new URL you can click on and open. In the Actions tab, it will also show as a green tick when it has finished building.

Congratulations! After seeing your rendered book for the first time, this is the second most satisfying part as you can see everything is working.

Add shortcuts to your book

Once the site is live, I recommend adding the link to two places. First, save it as a browser shortcut so you can quickly access it outside of github. Second, return to the Code tab. Click the cog icon next to Above on the right side and tick to add your website from github pages. This will show the URL to your book on the Code tab for easy access from here.

Customise the URL

By default, the URL to your book will be your github username + .github.io + your repository name. If you want to get fancy, you can add a custom domain from within Settings and Pages if you have bought one. That is not something we are covering in this workshop or materials though.

Warning

If you try and push a change that contains an error and your book does not render, you will get a red cross in Actions saying your book did not build and you will receive an email warning you about it too. Just go back to the book files in RStudio and fix any errors you are getting before you push the updates again.

2.6 Commiting and pushing changes

At this point, you have everything you need for the book workflow. As you work on your book, you will go through the workflow of:

1. Open .RProj and edit your book in RStudio, either by editing your past progress or adding new files.

2. When you hit a milestone you want to record, in github desktop tick all file changes or specific files, and add a commit message (and longer description if necessary).

3. If you are continuing to work on the book, keep editing and committing.

4. When you are ready to push changes to github and github pages, push your commits.

Before we have time to start working on your newly minted books, I will end on a couple of warnings and tips.

Caution

Remember just committing changes will do nothing to your github repository and book link. You need to push those committed changes for them to be available on github and used to build the book in github pages. Likewise, editing the .qmd files and committing the changes to github will not change anything without first rendering your chapter/book. You edit the .qmd files but rendering creates the .html files that display as a website.

It takes a few minutes to rebuild, so do not worry if you do not immediately see the changes.

Reverting changes

One of the main features I use way too infrequently is reverting changes when something goes wrong. The idea behind version control is you save your work at specific milestones, where you can add commit messages that describe key changes you make. If you make a change that breaks something since your last commit, you can revert the changes to a previous version. To do this, go to github desktop, click History, and you will see all your commit history. Identify the last commit you want to revert to, right click on it, and select Revert Changes in Commit.

2.7 Start working on your own book!

Start working on your own book in the remaining time we have together.

See the final chapter on Useful Quarto and booktem features for inspiration / example code for the kind of features you can use.