10 Rendering

The content of a Quarto book is written in .qmd files or Jupyter notebooks (.ipynb). Quarto was made to convert these files, using the settings (_quarto.yml), into commonly used formats. Quarto can convert documents into HTML files (which can in turn be hosted on a website), PDF, but also Epub, OpenOffice and Microsoft Word.

10.1 How to render

You specify to which format you want to convert the files in the _quarto.yml file. An example:
```
format:
  html:
    theme: cosmo
    css: custom-styling.css
```

If you use RStudio, you can simply click the Render button at the top of the page: Render button in RStudio
If you use the terminal, you type:

# render project in current directory
quarto render

# or: render project in the directory 'mybook'
quarto render mybook

By default, quarto will build the files (html, pdf, docx, etc.) in a folder called _book. If you updated the _quarto.yml file, that folder will be named docs instead.

10.2 Previewing

You can also preview your book while writing it. In RStudio, you can tick “Render on save” and then the preview will update whenever you save a new change in the document. Render on Save button in RStudio

Alternatively, you can type in the terminal:

# preview project in current directory
quarto preview

# preview project in the directory 'mybook'
quarto preview mybook

10.3 Automated rendering on GitHub

It is also possible to have GitHub Actions render the files to the correct format and publish HTML files to a GitHub Pages website.

Just for your overview, here are the 2 ways to publish with GitHub Pages that we discussed here:

Render the book to a docs folder and set the GitHub repository so that it uses the docs folder as the basis for the GitHub pages website.
Add a publish.yml file to the GitHub repository (in the folder .github/workflows/) and set the GitHub repository so that it uses the GitHub Action to publish the GitHub pages website.

The Quarto website explains how to make automatic rendering and publishing possible. You may need to play a bit with the paths and branches that the Action uses to render and publish. Here is an example of a publish.yml from one of our own workshops.