Formats & Projects

Session 4

Saturday, the 7th of February, 2026
Mickaël CANOUIL, Ph.D. ORCID
Independent Contractor
Updated: Saturday, the 7th of February, 2026

Session Overview

Session 4: Formats & Projects

  • Quarto Projects
    • Project types and architecture: default, website, blog, manuscript, book.
    • Project type decision framework based on publishing goals.
    • Understanding project structure and configuration files.
  • Multiple Formats
    • Multi-format output optimisation with format-specific options.
    • Conditional content by format using content-visible/hidden classes.
    • Cross-format resource management and figure optimisation.
  • Advanced Project Features
    • Shared metadata and configuration with _metadata.yml.
    • Pre and post-render scripts for workflow automation.
    • Project profiles for different deployment scenarios.
    • Environment variables and resource management.
  • Quarto Projects
    • Project types and architecture: default, website, blog, manuscript, book.
    • Project type decision framework based on publishing goals.
    • Understanding project structure and configuration files.
  • Multiple Formats
    • Multi-format output optimisation with format-specific options.
    • Conditional content by format using content-visible/hidden classes.
    • Cross-format resource management and figure optimisation.
  • Advanced Project Features
    • Shared metadata and configuration with _metadata.yml.
    • Pre and post-render scripts for workflow automation.
    • Project profiles for different deployment scenarios.
    • Environment variables and resource management.

Session Objectives

This session explores Quarto’s project architecture and format ecosystem, covering project types, multi-format optimisation, and template systems for scalable workflows.

Learning Objectives

By the end of this session, participants will be able to:

  • Select appropriate project types for different publishing scenarios.
  • Configure multi-format outputs with format-specific optimisations.
  • Use template systems for rapid project initiation.
  • Implement collaborative workflows with proper project structure.
  • Understand format capabilities and limitations.

Quarto Projects

Project Types and Architecture

Recall the project types introduced in Session 1. Here we examine their configuration and architecture in more detail.

Bash
quarto create project
bash
 ? Type
 ❯ default
   website
   blog
   manuscript
   book
   confluence

Project Type Decision Framework

Choose your project type based on your publishing goals:

Scenario Project Type Key Features
Multiple unrelated documents default Flexible structure, shared metadata
Single research paper manuscript Academic formatting, citations, submission-ready
Public documentation/blog website/blog Navigation, search, responsive design
Long-form content book Cross-chapter references, multiple outputs

Default Project Structure

The most flexible option for diverse content:

yaml
project:
  title: "Default"

Website Projects

Optimised for web publishing:

yaml
project:
  type: website

website:
  title: "Website"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme:
      - cosmo
      - brand
    css: styles.css
    toc: true

Blog Projects (website + listing)

Designed for regular posts and updates:

yaml
project:
  type: website

website:
  description: "A blog built with Quarto"
  site-url: https://your-website-url.example.com # you must change this appropriately for RSS feeds to work properly
  title: "Blog"
  navbar:
    right:
      - about.qmd
      - icon: github
        href: https://github.com/
      - icon: bluesky
        href: https://bsky.app/
format:
  html:
    theme:
      - cosmo
      - brand
    css: styles.css

Manuscript Projects

Optimised for academic publishing:

yaml
project:
  type: manuscript

manuscript:
  article: index.qmd

format:
  html:
    comments:
      hypothesis: true
  docx: default
  jats: default

  # (other formats)
  # pdf: default

execute:
  freeze: true

Book Projects

For comprehensive, structured content:

yaml
project:
  type: book

book:
  title: "Book"
  author: "Norah Jones"
  date: "2/7/2026"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

bibliography: references.bib

format:
  html:
    theme:
      - cosmo
      - brand
  pdf:
    documentclass: scrreprt

Multiple Formats

Multi-Format Output Optimisation

Balance capability with compatibility by configuring format-specific options that leverage each output type’s strengths.

yaml
title: "Multi-Format Document"
2fig-width: 6
fig-height: 4
format:
  html:
1    theme: cosmo
    code-fold: true
    code-tools: true
    toc: true
    fig-width: 8
    fig-height: 6
  pdf:
    documentclass: article
    geometry: margin=1in
    fontsize: 11pt
    colorlinks: true
  typst:
    brand-mode: dark
  revealjs:
    brand-mode: dark
    fig-width: 10
    fig-height: 6
1
Setting format-specific options.
2
Setting shared and format-specific options.

Conditional Content by Format

Control what content appears in different output formats.

Key Classes

  • .content-visible - Show content only for specific formats.
  • .content-hidden - Hide content from specific formats.

Conditions

  • when-format / unless-format - Control visibility based on output format.
  • when-meta / unless-meta - Control visibility based on metadata.
  • when-profile / unless-profile - Control visibility based on profile.

Syntax

  • markdown
    ::: {.content-visible when-format="html"}
HTML-only content
:::
  • markdown
    [Typst/PDF only text]{.content-visible when-format="typst"}
  • markdown
    ```{.python .content-visible when-format="html"}
print("Only shows in HTML")
```
  • markdown
    ::: {.content-visible when-format="html"}
```{python}
print("Only shows in HTML but is evaluated in all formats")
```
:::

Cross-Format Resource Management

Optimise images and assets for different outputs:

yaml
format:
  html:
    fig-format: svg      # Vector graphics for web
    fig-dpi: 150
  pdf:
    fig-format: pdf      # Vector graphics for print
    fig-dpi: 300
  typst:
    fig-format: png      # Raster for compatibility
    fig-dpi: 150

Advanced Project Features

Shared Metadata and Configuration

Use _metadata.yml for common settings to be shared by documents in a directory:

subdirectory/_metadata.yml
format:
  html:
    theme: custom
execute:
  echo: false
  warning: false

Resource Management

Organise assets that needs to be copied to the output directory:

_quarto.yml
project:
  resources:
    - "data/*.csv"
    - "images/"
    - "!temp/"      # Exclude temporary files

Pre and Post Render Scripts

Automate workflows before and after rendering.

Configuration

_quarto.yml
project:
  pre-render: 
    - data-prep.py
    - generate-content.R
  post-render:
    - cleanup.sh
    - deploy.ts

Key Features

  • Scripts run from project root directory.
  • Re-computes metadata after pre-render (can generate new files).
  • Supports shell commands, Python, R, TypeScript, Lua.

Environment Variables Available

  • QUARTO_PROJECT_RENDER_ALL - “1” if rendering entire project.
  • QUARTO_PROJECT_OUTPUT_DIR - Output directory path.
  • QUARTO_PROJECT_INPUT_FILES - List of input files (pre-render).
  • QUARTO_PROJECT_OUTPUT_FILES - List of output files (post-render).

Conditional Execution Example

python
# Only run expensive operations on full renders
import os
if os.environ.get("QUARTO_PROJECT_RENDER_ALL") == "1":
    # Run expensive data processing
    process_large_dataset()

Environment Variables

Manage project environment variables with files and profiles:

  • _environment - Default environment variables for all renders.
  • _environment.local - Local overrides (auto-ignored by Git).
  • _environment-{profile} - Profile-specific variables.
  • _environment.required - Documentation of required variables.

Variables

Insert dynamic content with shortcodes:

  • {{< var variable_name >}} - From _variables.yml file.
  • {{< meta field_name >}} - From document YAML metadata.
  • {{< env ENV_VARIABLE >}} - From environment variables.

Markdown

markdown
- {{< meta title >}}
- {{< meta subtitle >}}

Output

  • Formats & Projects

  • Session 4

Project Profiles

Adapt projects for different scenarios with configuration variants.

What Are Profiles?

  • Different configurations for the same project (production, development, basic/advanced versions).

Configuration Files

  • _quarto.yml - Base configuration.
  • _quarto-{profile}.yml - Profile-specific config that merges with base.
  • _environment-{profile} - Profile-specific environment variables.

Activation

bash
# Environment variable
export QUARTO_PROFILE=production
quarto render

# Command line
quarto render --profile production

# Multiple profiles
quarto render --profile production,advanced

Content Targeting

markdown
::: {.content-visible when-profile="advanced"}
Advanced content only
:::

::: {.content-hidden unless-profile="basic"}
Hidden for basic profile
:::

Profile Groups & Defaults

yaml
profile:
  group: [basic, advanced]
  default: development

Hands-On Exercise: Building Your First Project

Exercise Overview

Objective: Transform your computational portfolio from Session 3 into a structured project and explore multiple output formats.

Example Code: Exercises

bash
tar -xzf "04-exercises.tar.gz" -C "04-formats-projects"

Part 1: Create a Project Structure

Convert your portfolio into a project:

Create a _quarto.yml file:

yaml
project:
 type: website

website:
 title: "My Learning Portfolio"
 navbar:
   left:
     - href: index.qmd
       text: Home
     - about.qmd

format:
 html:
   theme: cosmo
   toc: true

Create a _quarto.yml file:

yaml
project:
 title: "My Portfolio Collection"

format:
 html:
   theme: cosmo
   toc: true
 typst: default

Create a _quarto.yml file:

yaml
project:
 type: book

book:
 title: "My Quarto Journey"
 chapters:
   - index.qmd
   - portfolio.qmd
   - reflection.qmd

format:
 html:
   theme: cosmo

Part 2: Multi-Format Configuration

Add multiple output formats to your project:

Add to your _quarto.yml:

yaml
format:
 html:
   theme: cosmo
   code-fold: true
 typst:
   margin:
     top: 2cm
     bottom: 2cm
 docx: default

Add format-specific options:

yaml
format:
 html:
   theme: cosmo
   code-fold: true
   fig-width: 8
   fig-height: 6
 typst:
   fig-width: 6
   fig-height: 4
 pdf:
   geometry:
     - margin=1in
   fontsize: 11pt

Add slides to your outputs:

yaml
format:
 html: default
 revealjs:
   theme: dark
   fig-width: 10
   fig-height: 6

Part 3: Conditional Content

Add format-specific content to your documents:

Add to your content:

markdown
::: {.content-visible when-format="html"}
This interactive content only appears in HTML output.
:::

::: {.content-visible when-format="typst"}
This formatted text appears only in Typst/PDF output.
:::

::: {.content-hidden when-format="revealjs"}
This detailed content is hidden in presentations.
:::

Control code display:

markdown
```{python .content-visible when-format="html"}
# Interactive code for web
import plotly.express as px
# Create interactive plot
```

```{python .content-visible unless-format="html"}
# Static plot for print formats
import matplotlib.pyplot as plt
# Create static plot
```

Add dynamic text:

markdown
[[View the interactive version online](link-to-html)]{.content-visible when-format="typst"}

[*This is the web version with interactive features*]{.content-visible when-format="html"}

Part 4: Test Multiple Formats

Render your project in different formats:

Try rendering to specific formats:

bash
quarto render --to html
quarto render --to typst
quarto render --to docx

Render all configured formats:

bash
quarto render

Use preview for development:

bash
quarto preview

Part 5: Add Project Features

Enhance your project with additional features:

Create _metadata.yml:

yaml
author: "Your Name"
date: today
execute:
  echo: true
  warning: false

Add to _quarto.yml:

yaml
project:
  resources:
    - "data/"
    - "images/"
    - "*.csv"

Create _environment file:

txt
QUARTO_PYTHON=/path/to/python
API_KEY=your-key-here

Success Criteria

✅ You’ve successfully completed the exercise if you can:

  • Create a properly structured project with _quarto.yml.
  • Configure at least two different output formats.
  • Add format-specific content that shows/hides appropriately.
  • Successfully render your project to multiple formats.
  • Test that conditional content works correctly.
Back to top

Reuse