3  How do I…?

This page is intended as a FAQ/HowTo for some common questions that might come up when using this template for the first time.

Some example pages dedicated to common tasks and specific kinds of presentation are included later in the template.

3.1 …create a new page?

tl;dr
  1. Create a new plant text file
  2. Write Markdown content in your file
  3. Save your file as a .qmd file (with an appropriate filename)
  4. Add your filename to the _quarto.yml file in an appropriate place
  5. Commit your changes
  6. Push the changes to your repository

Assuming that you’re using RStudio, you need to create a new file to hold the Markdown for your page. I usually create a new text file (File -> New File -> Text File or click on the New File icon and select Text File). Write some content in the file and save it as a .qmd file with a meaningful filename (e.g. this file is called howto.qmd).

At this point, the file you just wrote could be rendered, but it won’t be linked as a page in the book. To link the file, open the _quarto.yml file and look for the section that starts:

# Define chapters and sections here
  # [E] CHAPTERS AND SECTIONS
  chapters:
    - index.qmd
    - intro.qmd

Then enter the name of your file in the appropriate place, e.g. in the early-section.qmd part, as a chapter following tutorial.qmd in the example below:

    - part: early-section.qmd
      chapters: 
        - tutorial.qmd
        - howto.qmd      # new page added at this line
Warning

The _quarto.yml file is written in a language called YAML (yet another markup language), and the syntax is important. If you follow the style of the file, you should be fine.

and then render the file.

Important

To ensure your changes are not lost, commit the changes to your repository (your .qmd file, the _quarto.yml file, and any supporting images or other files), and push them to GitHub.

3.2 …set a value once to be used everywhere?

Quarto supports global variables, values that are defined once in a document, and that can be referred to at any point by using a special sequence of characters called a shortcode. The variables are defined in the _variables.yml file, using the YAML markup language.

Tip

Global variables can be useful for defining details that might be repeated multiple times across your book:

  • administrative information, like contact emails and numbers
  • the academic year for a module presentation (saves searching for every mention in all pages)

To include the value held in a variable called myvar, you would define this in _variables.yml as:

myvar: "The value of the variable"

and use the shortcode:

{{< var myvar >}}

Variables can be named directly, as with myvar above, but they can also be grouped by category as category.variable combinations. For instance, if you wanted to define a set of telephone numbers for three rooms HW312, HW313, and HW314, you could give these the category phone, defining them as, e.g.:

phone:
  HW312: 01-234-657890
  HW313: 01-234-657891
  HW313: 01-234-657892

and use them with shortcode:

{{< var phone.HW313 >}}

This is global_variable: This is an example of a global variable.

This is category.value1: This is an example of a category.value variable.

This is category.value2: This is another example of a category.value variable.

This is `global_variable`: {{< var global_variable >}}.

This is `category.value1`: {{< var category.value1 >}}.

This is `category.value2`: {{< var category.value2 >}}.
# Example variables for the howto page
global_variable: "This is an example of a global variable"
category:
  value1: "This is an example of a `category.value` variable"
  value2: "This is another example of a `category.value` variable"