Configuration Reference

Exact defaults, scope, precedence, and emitted behavior for quarto-gradio document metadata and cell options.

The gradio filter reads the merged Quarto metadata for each document and per-app attributes from #| gr-* options on a launch cell. Project _quarto.yml supplies defaults, directory _metadata.yml overrides project values, and page front matter has the highest metadata precedence.

Enable the filter for a project

Put the filter and browser-execution policy in _quarto.yml when every document in a project should inherit them:

_quarto.yml

filters:
  - gradio

execute:
  enabled: false

Document front matter can provide the same settings for one source file. execute.enabled: false prevents Quarto from running the Python cell in the build environment.

Complete document configuration

_quarto.yml or document front matter

gradio:
  cdn: "https://cdn.jsdelivr.net/npm/@gradio/lite"
  version: "5.45.0"
  requirements:
    - "plotly==5.24.1"
  attributes:
    theme: dark
    shared-worker: false
    playground: false
    layout: horizontal

Document keys

Key	Type	Default	Scope	Behavior
`gradio.cdn`	String	`https://cdn.jsdelivr.net/npm/@gradio/lite`	Rendered document	Runtime asset base URL
`gradio.version`	String	`5.45.0`	Rendered document	Appended to the default asset URL as `@5.45.0`
`gradio.requirements`	List of strings	Empty	Rendered document	Emitted in every app’s `<gradio-requirements>` element
`gradio.attributes`	Mapping	See below	Rendered document	Forwarded to every `<gradio-lite>` element

Setting gradio.cdn without gradio.version suppresses the default version suffix. The value must then point to an asset root containing dist/lite.js and dist/lite.css. Setting both produces <cdn>@<version>/dist/....

The extension’s compatibility bootstrap supports the exact default jsDelivr URL and version. A custom URL or version requires an independently verified runtime and package set.

Tested Gradio Lite attributes

Attribute	Values	Default	Effect
`theme`	`light`, `dark`	`dark`	Selects the app color mode
`shared-worker`	Boolean	`false`	Reuses one Pyodide worker across apps when true
`playground`	Boolean	`false`	Shows a Python editor and app preview when true
`layout`	`horizontal`, `vertical`	Runtime default	Arranges the editor and preview in a coding playground

The filter forwards other keys without validation. The frozen custom element also recognizes upstream attributes such as info, container, embed, initial-height, eager, auto-scroll, control-page-title, and app-mode. Those passthrough attributes belong to the archived Gradio Lite 5.45.0 contract and do not have project-specific compatibility tests. Consult the archived Gradio Lite guide for the upstream element model.

Cell options

Prefix a Gradio Lite attribute with gr- on the launch cell:

#| gr-theme: light
#| gr-playground: true
#| gr-layout: vertical
demo.launch()

The filter removes gr- and forwards the result to that app’s <gradio-lite> element. A cell option overrides the matching value in gradio.attributes.

gradio.cdn, gradio.version, and gradio.requirements have no cell-level form.

Standard Quarto cell options still apply. For example, #| echo: false hides the authored launch cell from the rendered page while the gradio filter still uses its source for the embedded app.

Boolean serialization

True values produce a bare HTML attribute. False values omit the attribute:

gradio:
  attributes:
    playground: true
    shared-worker: false

produces a <gradio-lite playground> element with no shared-worker attribute.

App requirements

Each list item is passed to Gradio Lite as a Python package requirement. Prefer exact pins:

gradio:
  requirements:
    - "plotly==5.24.1"

Requirement strings can use package specifiers or direct wheel URLs accepted by the frozen Pyodide and Micropip environment. Package availability, wheel compatibility, cross-origin access, and startup cost remain the author’s responsibility.

Read Install Python Packages for a complete example.

Supported formats

The documented source and output combinations are Quarto Markdown to HTML, Quarto Markdown to Reveal.js, and Jupyter notebooks to HTML. See Runtime and Trust for the evidence and compatibility boundary.