Quarto

Overview

Framework uses Quarto to render notebooks, documents, and presentations. When it creates a project, it writes _quarto.yml files that set rendering defaults and send rendered output to a separate folder. Python chunks in .qmd files run through Jupyter.

Quarto is a tool that a project can turn off. It is on for every project type except bare, and tools={"quarto": False} in new() creates a project without the _quarto.yml files. Such a project records quarto: false under tools in settings.yml. Its notebooks are Jupyter notebooks, so make_notebook() creates .ipynb files, and quarto_regenerate() refuses to run there. The New Project guide covers tools.

Render Folders

Framework keeps source files and rendered output apart. A .qmd file stays in its source folder, and the rendered HTML goes to a render folder. Rendered files can then be ignored, regenerated, or published without mixing them with the sources.

The render_dirs section of the settings maps each source folder to its render folder. These are the defaults.

Project type	Source folder	Render folder	Format
Standard	notebooks/	outputs/notebooks/	HTML
Standard	docs/	outputs/docs/	HTML
Privacy-sensitive	notebooks/	outputs/private/notebooks/	HTML
Privacy-sensitive	docs/	outputs/private/docs/	HTML
Course	slides/	rendered/slides/	reveal.js
Course	assignments/	rendered/assignments/	HTML
Course	course_docs/	rendered/course_docs/	HTML
Course	modules/	rendered/modules/	HTML
Presentation	project root	project root	reveal.js

Folders whose key contains slide render as reveal.js presentations, and the others render as HTML. In privacy-sensitive projects, rendered notebooks land in a private folder, because they can contain restricted data.

Generated Files

A project gets one _quarto.yml, at its root. Its output-dir is the folder the render folders share, such as outputs in a standard project. Quarto keeps each file's folder under it, so notebooks/exploration.qmd renders to outputs/notebooks/exploration.html.

vaccine-study/
├── _quarto.yml          # all settings; output-dir: outputs
├── notebooks/
│   └── exploration.qmd
├── docs/
└── outputs/
    └── notebooks/       # rendered notebooks appear here

# Auto-generated by Framework on 2026-11-01
# This file is yours to customize - Framework will not modify it after creation
# To regenerate: run framework.quarto_regenerate() (WARNING: overwrites!)

project:
  type: default
  output-dir: outputs

format:
  html:
    theme: default
    toc: true
    toc-depth: 3
    code-fold: false
    code-tools: false
    embed-resources: true
    highlight-style: github

A folder whose format differs from the root's gets a _metadata.yml with only its format, and it inherits everything else from the root. A course's slides/ gets one that renders its files as reveal.js. A render folder outside the shared output folder keeps its own _quarto.yml with a relative output-dir. A presentation renders in place, so its root file has no output-dir.

Framework writes these files once. Edit them freely, because Framework does not change them afterward unless you call quarto_regenerate().

Rendering Defaults

The values in the generated files come from the quarto section of the settings. Keys use underscores in the settings and hyphens in _quarto.yml.

quarto:
  html:
    theme: default
    embed_resources: true
    toc: true
    toc_depth: 3
    code_fold: false
    code_tools: false
    highlight_style: github
  revealjs:
    theme: default
    incremental: false
    slide_number: true
    transition: slide
    background_transition: fade
    controls: true
    progress: true
    center: true
    highlight_style: github

Changing this section does not change existing _quarto.yml files. Regenerate them to apply new values.

Regenerating

quarto_regenerate() rewrites the Quarto files from the project's settings. It removes the _quarto.yml and _metadata.yml files in the render folders, which also updates projects created with one _quarto.yml per folder. It overwrites manual edits, so it first copies the existing files into .quarto_backups/<timestamp>/.

import framework as fw

result = fw.quarto_regenerate(".")
result.regenerated
result.backup_location

Pass backup=False to skip the copy. quarto_generate_all() writes the files from explicit arguments and is what project creation uses.

Creating Quarto Files

make_notebook() and make_qmd() create notebooks, and make_presentation() creates reveal.js slides. The Notebooks and Scripts guide describes them.

Rendering

Quarto runs Python chunks with Jupyter, which must be installed in the environment that renders. Add it to the project once.

fw.package_add("jupyter")

Render from the terminal with the project's environment.

uv run quarto render notebooks/exploration.qmd

save_notebook() renders a notebook and saves the result in the notebooks output folder, where it is recorded in framework.db with the other outputs.

fw.save_notebook("notebooks/exploration.qmd")
fw.save_notebook("notebooks/exploration.qmd", name="exploration-2026-10", format="pdf")

The formats are html, pdf, and docx. HTML is rendered as one self-contained file unless you pass embed_resources=False. quarto_args passes extra arguments to quarto render. save_notebook() also renders Jupyter notebooks (.ipynb).

Publishing

publish_notebook() renders a notebook and uploads the result to a storage bucket or to Framework Cloud. The Publishing guide covers both.