2  Workshop plan

To follow along in the workshop if you fall behind, we will complete the following steps.

2.1 Example book

For an example of the new book template, we will explore the new Fundamentals of Quantitative Analysis book. I have edited the first two chapters to use new Quarto features, so they can provide inspiration for what you can do with the book template.

2.2 Creating the book template

If you have not followed the preparation instructions yet, you need R/RStudio installed to your computer, the booktem package installed from Lisa’s github, and git/github desktop installed on your computer. I will be demonstrating how to use github desktop rather than the command line.

The first step is thinking about where you want your book folder stored on your computer, 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). You do not need to create a folder for the book itself as the function will do that for you, but you need somewhere for that folder to live.

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 a folder your book can live in, open RStudio and set your working directory to this folder, for example from the top menu Session >> set working directory >> Choose directory and navigate to this folder.

Once RStudio knows where you want your working directory, you can create the book using the following code in the console and editing accordingly before you run the code. Do not worry though, you can edit all of these later, but this will create the initial version.

# We first need to load the booktem library, assuming its installed properly
library(booktem)

create_book(path = "your_book_file_name", # If you set your working directory, you should not need to add the full path
            title = "My book title", # The main title of your book
            authors = list( # You need a new line for any additional author, or delete the author 2 line if you're solo
              c("Author 1 first name", "Author 1 last name", "Author 1 ORCiD"),
              c("Author 2 first name", "Author 2 last name", "Author 2 ORCiD"))
            )

Once you press run, you should get a bunch of progress messages from Setting up project.... Once it’s finished, your book will open in a new session and you will see the rendered version appear in your default internet browser.

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, description, author(s), and the licence. In the new Quarto book template, 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 key features in: project, book, bibliography, csl, and format.

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. R/ folder

The R/ folder is where you can save bits of R code that your book relies on. There is some code in here that Lisa has worked on to help with certain functionality, like how the glossary looks.

4. include/ folder

The include/ folder is a similar idea to R/. It has a bunch of files the book uses for formatting and any chapters would be able to access stuff here. For example, a .bib file for your references and a .csl file for the style of your references.

5. docs/ folder

The docs/ folder is where the rendered .html versions of your book will update to. The process behind creating books in Quarto is writing them in Markdown, then Markdown is converted to .html. When we add the book to github pages, this is the folder you point it to as the source for how it appears as a webpage.

6. Licence

By default, booktem gives the books a CC-BY-SA-4.0 licence. This is a Creative Commons licence which states people can adapt your materials but they must provide you with credit. You can learn more about different types of Creative Commons licences online. If you want to state a different licence depending on your materials, you can update the text in the Licence file and in the .yml.

7. Chapter files

By default, you get an example index.qmd and one chapter .qmd for an example. The example chapter has a bunch of advice on what to edit and features like I will demonstrate, 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

If you are converting a previous book to the new template, there is a handy little function rmd2qmd. This copies .Rmd files and renames them to .qmd. The function looks like this

rmd2qmd(from_path = "",  # file path where your .Rmd files are
        to_path = "") # file path where you want your new .qmd files to go

where you specify a file path to access the old .Rmd files and a file path to where you want the new .qmd files saving. Keep your working directory in mind as you will probably be starting from your book folder at this point. I usually save my old .Rmd files in a folder within the new book directory, then save the new .qmd files to the new book main directory.

8. 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.

Tip

The single best part of Quarto and the new book template is you can keep rendering and checking what your work looks like in the flesh. Previously, you had to render the whole book to check how it rendered, but now you can keep updating the browser to see what your changes look like.

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 folder, create a repository using this new folder, and then use the create_book() function to add the book file to. However, we started by creating the book first, so we need to create a repository for an existing folder without a git component.

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.

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

The other fields you can edit later, 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.

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.

Within Settings is the 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.

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, keeping 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. 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 next chapter on Quarto features and book conventions for inspiration / example code for the kind of features you can use.

Do not forget to make your own hex sticker for for extra panache!