Using Quarto

Abstrave quarto theme

Practical guide to using Quarto with a custom theme
Author

Roy Francis

Published

05-Sep-2026

The custom template is a Quarto website project with html reports and revealjs presentation.

1 Get started

To download a starter template, run in the terminal:

bash
quarto use template royfrancis/abstrave

Install required extensions

bash
# adds fontawesome icons
quarto add --no-prompt quarto-ext/fontawesome
# adds 2 logo header to slides
quarto add --no-prompt royfrancis/quarto-revealjs-header
# adds pointer to slides
quarto add --no-prompt royfrancis/quarto-revealjs-pointer
# adds code output folding
quarto add --no-prompt mcanouil/quarto-collapse-output@1.4.0
# adds collapsible accordion component from bootstrap
quarto add --no-prompt royfrancis/quarto-accordion
# adds leaflet maps
quarto add --no-prompt royfrancis/quarto-leaflet
# adds profile images layout
quarto add --no-prompt royfrancis/quarto-team
# adds toastui schedule component
quarto add --no-prompt royfrancis/quarto-toastui

This creates a website template that you can modify as needed. The directory structure is as follows:

.
├── 404.md
├── assets/
├── _extensions/
├── home_about.qmd
├── home_contents.qmd
├── home_faq.qmd
├── home_precourse.qmd
├── home_schedule.qmd
├── home_syllabus.qmd
├── index.qmd
├── schedule.csv
├── _metadata.yml
├── _quarto.yml
├── reports/
└── slides/

2 Preview

Quarto allows for live preview of changes.

bash
quarto preview report.qmd
Warning

Preview will build all the files in the project. So, this might not be a good option if there are incomplete documents.

Note

Using freeze is a good way to speed up rendering as chunks are pre-computed and cached. This also allows you to render pages when the original environment/tools is not available.

3 Render

A quarto document can be rendered from the terminal as follows:

bash
# render full project (freeze works if enabled)
quarto render

# render specific file (freeze doesn't work for individual files even if enabled)
quarto render report.qmd

This will generate the output files in the docs/ directory as specified in _quarto.yml. The output format is determined by the YAML front matter of each qmd file. For example, format: html will generate an html file and format: revealjs will generate a revealjs presentation.

4 Settings

Start by updating the settings. The website/project settings are contained in the _quarto.yml file. A website is a quarto project. Projects are documented here and websites are documented here.

  • The output directory is set to docs; output-dir: docs
  • Change site-url to your intended destination
  • website: image sets the path to the opengraph seo image used as preview when sharing links
  • Navigation bar links are set under website: navbar. Add or remove as needed
  • Page footer settings are set under website: page-footer. Check license. Update as needed
  • HTML report settings are under format: html:
    • This is global settings for all html pages
    • Custom css styles are defined (assets/css/styles.scss)
    • Table of contents is enabled (toc: true)
    • Sections are automatically numbered (number-sections: true)
    • Code wraps down rather than scroll when wider than page width (code-overflow: wrap)
    • A default subtitle has been set
    • Last modified date is added to pages (date: last-modified)
    • A custom image for each report can be set when viewing as listing (image:)
    • Images can be clicked to open in a lightbox (lightbox: auto)
  • RevealJS slides settings are under format: revealjs
    • These are global settings for all revealjs slides
    • Custom css styles are defined (assets/css/slides.scss)
    • All items on a slide appear at once (incremental: false), override with .fragment class
    • Use ## to define slides (slide-level: 2)
    • Chalkboard for scribbling is enabled (chalkboard: true)
    • A custom image for each presentation can be set when viewing as listing (image:)
    • Set title slide graphic image (hero:)
    • Set title slide background image (title-slide-attributes: data-background-image:)
    • A default subtitle has been set
    • Adjust slide header logo image, size and link (header-logo-*)
  • execute settings
    • code chunks are executed (eval: true) and displayed (echo: true) by default
    • warnings and messages from chunks are disabled
    • freeze is an option available for projects that allow code chunks to be cached to speed up rendering
  • Add any arbitrary metadata in _metadata.yml and use it across the project as {{< meta metadata >}}. This is used for map information.
  • Custom extensions
    • Additional functionality through extensions
    • Filter extensions can be added globally in _quarto.yml or locally in individual qmd files
    • Add quarto version ({{< meta quarto_version >}}) or date/time ({{< meta current_year >}}), enabled through custom lua (assets/custom.lua)
    • Code output folding is enabled through the quarto-collapse-output extension. This is documented here
    • Accordions are enabled through the quarto-accordion extension. Use the shortcode {{< accordion name >}} to include an accordion in any qmd file. Accordions are documented here
    • Leaflet maps are enabled through the leaflet extension. Add map information as metadata in _metadata.yml and use the shortcode {{< leaflet mapname >}} to include the map in any qmd file. Leaflet maps are documented here
    • ToastUI schedule is enabled through the toastui extension. Add schedule information as metadata in _metadata.yml and use the shortcode {{< toastui schedule >}} to include the schedule in any qmd file. ToastUI schedule is documented here
    • RevealJS header with logos and pointer extensions are enabled for slides. Press q on slides to show the pointer and q again to hide it
    • If the extensions are not used, they can be removed from the project by running quarto remove extension-name
  • Add custom css under YAML for individual qmd files if needed: css: "styles.css"

5 Content

Now you can start adding content.

The starter template should render completely using quarto alone. You can add R or Python code chunks for example as needed.

  • The homepage is index.qmd
  • Files starting with home are essential pages linked in the top navigation menu. Remove or modify them as needed
  • home_schedule.qmd contains toastui schedule component which loads data from schedule.csv
  • home_contents.qmd contains a markdown table with links to reports and slides
  • home_about.qmd contains profiles of organizers and practical information like venue and map
  • home_faq.qmd contains an accordion example with frequently asked questions
  • home_syllabus.qmd shows tab panels
  • All reports are organised under reports/ as separate folders
  • All slides are organised under slides/ as separate folders
  • The index.qmd file in the root of reports/ and slides/ shows listing pages for all reports and slides respectively

6 Usage tips and conventions

  • Markdown basics are covered here
  • Use level 2 heading (##) as the highest level
  • Use quarto style chunk options; #| eval: false rather than `{r eval=FALSE}`
  • Qmds starting with _ such as _content.qmd are child documents and are not rendered alone
  • Child qmd files can be included by using {{< include _content.qmd >>}}. They do not work in .ipynb notebooks. Includes is documented here.
  • Dynamic variables can be defined in _variables.yml and used as {{< var variable >>}}. Dynamic variables are documented here.
  • Custom metadata can be defined in _metadata.yml and used as {{< meta metadata >>}}
  • When using R or Python, declare all libraries at the beginning of each document
  • Add a session info chunk at the end of qmd documents if code chunks are used. This is good practice to ensure reproducibility and help with debugging if needed. For R, use sessionInfo() or sessioninfo::session_info(). For Python, use import session_info; session_info.show()