Create Interactive Slideshows with Markdown and Python in Quarto

Code Cells

Python code is embedded using fenced code blocks with a {python} language tag:

1
```{python}
2
import matplotlib.pyplot as plt
3
plt.plot([1, 2, 3, 4])
4
```

When rendered, the code executes and the output (plots, tables, text) appears directly on the slide. The basic distinction is:

• ```{python} (no dot) — runs the code and displays output
• ```{.python} (with dot) — displays code only, without execution

The dot syntax is useful when demonstrating code examples without showing the output, similar to how documentation sites display code snippets.

Rendering

Quarto provides a CLI and a VS Code extension. The render command is straightforward:

1
quarto render slideshow.qmd

The VS Code extension adds a preview button for live rendering during editing, which speeds up iteration significantly.

Slide Numbers and Footers

The slide-number: true option displays slide numbers at the bottom-right of each slide. The footer option adds persistent footer text to every slide and supports Markdown syntax — links, formatting, and inline code all render correctly.

A per-slide footer override is also available by setting footer: in slide-level attributes, which is useful when a specific slide needs different attribution.

Self-Contained Files

Setting embed-resources: true bundles all CSS, JavaScript, images, and fonts into a single HTML file. This eliminates external dependencies and makes the presentation portable — it can be shared as one file and opened in any browser without an internet connection.

Note: embed-resources: true is incompatible with chalkboard: true. The chalkboard feature requires external scripts that cannot be embedded.

Line Highlighting

Code blocks support progressive line highlighting, which reveals lines step-by-step as the presenter advances the slide:

1
```{python highlight-lines=[4-5, 7, 10]}
2
import pandas as pd
3
import numpy as np
4
import matplotlib.pyplot as plt
5

6
df = pd.read_csv("data.csv")
7
df["total"] = df["a"] + df["b"]
8

9
plt.figure()
10
plt.plot(df["x"], df["total"])
11
plt.show()
12
```

The highlight-lines attribute accepts ranges (4-5) and individual lines (7), separated by commas. Each slide advance highlights the next group. Adding highlight-lines=[1-10] at the end of the list shows all lines unhighlighted for reference.

Echo and Output Location

The echo option controls whether the code itself is visible:

• echo: true — displays both the code and the output on the same slide
• echo: false (default) — hides the code, shows only the output

The output-location option controls where the output appears relative to the code:

1
```{python output-location: slide}
2
# Output appears on the NEXT slide at full size
3
```
4

5
```{python output-location: column}
6
# Code on left, output on right — side by side
7
```
8

9
```{python output-location: column-fragment}
10
# Output on right side, revealed after clicking
11
```
12

13
```{python output-location: false}
14
# Hide output entirely — show only code
15
```

The column-fragment option is particularly useful for teaching — the code is visible, and the output appears only when the presenter clicks, creating a natural pause for the audience to read the code first.

Figure Captions

Add captions below figures with the fig-cap option:

1
```{python fig-cap: "Revenue by Quarter"}
2
plt.bar(quarters, revenue)
3
plt.show()
4
```

Preventing Content Overflow

When plots or code blocks are large, they can overflow the slide boundaries. Wrapping code blocks in a <div> with a CSS class prevents this:

1
<div class="smaller">
2
```{python}
3
# Large plot code here

Without this wrapper, the content may not fit the slide and will be clipped or cause scrolling issues.

Supported Libraries

• matplotlib — Standard static plots. Renders as PNG/SVG images on slides.
• plotly — Interactive plots with zoom, hover tooltips, and pan support. The full interactivity is preserved in the HTML output.
• seaborn — Statistical visualizations built on matplotlib. Works identically to matplotlib in Quarto.
• folium — Interactive maps based on Leaflet.js. Renders as embedded, navigable maps on slides.

Interactive Plotly Example

Plotly charts are fully interactive in reveal.js output. The audience can zoom into specific regions, hover over data points to see values, and pan across the chart:

1
```{python output-location: slide}
2
import plotly.express as px
3
df = px.data.gapminder().query("year == 2007")
4
fig = px.scatter(df, x="gdpPercap", y="lifeExp", size="pop", color="continent")
5
fig.show()
6
```

Using output-location: slide here gives the plot a full-size slide, which is ideal for interactive charts that need space for zooming and hovering.

Tip: Use output-location: slide for large plots and interactive visualizations. Use output-location: column when the code is short and you want the audience to see both simultaneously.

Basic DataFrame Display

Simply referencing a DataFrame at the end of a code cell displays it on the slide:

1
```{python}
2
import pandas as pd
3
df = pd.read_csv("sales.csv")
4
df  # Display the DataFrame
5
```

This produces a basic HTML table. For large DataFrames, the output can overflow the slide.

Great Tables Library

The great_tables Python library generates styled, publication-ready tables. It is the recommended approach for professional presentations:

1
```{python}
2
from great_tables import GT
3
GT(df)
4
```

Great Tables produces tables with proper formatting, alignment, and styling that look significantly better than default pandas output.

Table Layout Options

Large tables need layout controls to fit on slides. These options are set as code cell attributes:

1
```{python scrollable: true width: 1800 margin: 0 scale: 2}
2
from great_tables import GT
3
GT(df)
4
```

The scrollable: true option is critical for wide tables — without it, the table can break the slide layout.

LaTeX Equations

Mathematical equations render directly in slides using standard LaTeX syntax:

1
::: {layout-ncol=2}
2
::: {.column-width="40%"}
3
$$ \int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2} $$
4
:::
5
::: {.column-width="60%"}
6
$$ = \text{rendered result} $$
7
:::
8
:::

Column layouts let you show the LaTeX source on one side and the rendered equation on the other, which is useful for teaching mathematical concepts.

Incremental Lists

List items can appear one at a time with the ::: incremental directive:

1
::: incremental
2
- First point appears immediately
3
- Second point appears on click
4
- Third point appears on click
5
:::

This keeps the audience focused on one point at a time rather than reading ahead through the entire list.

Fragments

Individual elements can be animated with fragment directives. Multiple animation types are available:

1
::: {.fragment type="fade-in"}
2
Content that fades in from transparent
3
:::
4

5
::: {.fragment type="fade-up"}
6
Content that slides up into view
7
:::
8

9
::: {.fragment type="fade-left"}
10
Content that slides in from the right
11
:::
12

13
::: {.fragment type="semi-out"}
14
Content that fades to semi-transparent
15
:::

Fragment Indexing and Absolute Positioning

Fragments support an index attribute that controls appearance order. Lower index values appear first, and elements without an index appear after all indexed elements:

1
![cat](images/cats/cat1.png){.fragment index=3 style="position:absolute; left:10%; width:200px; top:30%"}

Combining absolute positioning with fragment indexing enables precise control over when and where elements appear — useful for building dramatic reveal sequences.

Slide Backgrounds

Slides support multiple background types, set through slide-level attributes:

1
background-color: "#0000FF"
2
background-image: "milky-way.jpg"
3
background-video: "video.mp4"
4
background-iframe: "https://example.com"

Background images, videos, and even iframes add visual depth to slides. The iframe option is useful for embedding live web content or dashboards.

Slide Transitions

Transition effects between slides are configured globally:

1
format:
2
  revealjs:
3
    transition: concave

Available transitions include concave, zoom, fade, convex, and others. The default is none (no transition).

Tab Sets

Tabbed interfaces can be created within slides to organize content:

1
::: {.panel-tabset}
2
### Plot Tab
3
Plot content here
4

5
### Data Tab
6
Data table here
7
:::

This is useful when a slide needs to show multiple views of the same data — for example, a plot tab and a raw data tab side by side.

Chalkboard

The chalkboard feature lets the presenter draw and annotate directly on slides during the presentation:

1
format:
2
  revealjs:
3
    chalkboard: true

Press C to activate drawing mode. This is particularly useful for lectures and live explanations where handwritten annotations add value. The chalkboard is not available when embed-resources: true is set, since the drawing scripts cannot be embedded.

PDF Export

To export the presentation as a PDF:

1. Press E to enter overview mode
2. Right-click and select Print
3. Choose “Save as PDF” in the print dialog

This produces a PDF version of the entire presentation, useful for distributing to audiences who cannot view HTML files.

Tip: Use Alt + click to zoom into specific areas of a slide during a live presentation. This is effective for emphasizing details in complex plots or tables without creating separate slides.

Brand File Structure

A brand.yml file defines colors, logos, typography, and metadata:

1
colors:
2
  primary: "#0066CC"
3
  secondary: "#00AA44"
4
  background: "#FFFFFF"
5
  foreground: "#333333"
6

7
logo: "logos/company-logo.png"
8

9
typography:
10
  font-family: "Inter, sans-serif"
11
  heading-font-family: "Inter, sans-serif"
12

13
meta:
14
  author: "Company Name"

Automatic Detection

Naming the file _brand.yml (with the underscore prefix) triggers automatic detection. Quarto applies the brand to all .qmd files in the project directory without any explicit reference in the YAML front matter.

For explicit per-file control, reference the brand file directly:

1
format:
2
  revealjs:
3
    brand: brand.yml

What Brand Files Control

• Color palette — Primary, secondary, and accent colors across all slides
• Logo — Displayed on slides (position controlled by theme)
• Typography — Font families for body text and headings
• Consistency — All team members using the same _brand.yml produce visually consistent presentations

Note: The Quarto documentation includes LLM prompts for generating brand files. This makes it easy to produce a brand file from a verbal description of the desired style.

Adding Slide Format to Notebooks

Insert a YAML front matter cell at the top of the notebook:

1
---
2
format: revealjs
3
---

Then render from the terminal:

1
quarto render example.ipynb --execute

The --execute flag is important — it ensures all notebook cells run during rendering. Without it, cells may not execute and outputs will not appear in the slideshow.

Notebook Structure

A typical notebook-to-presentation flow:

1. Markdown cell: Title and introduction
2. Code cell: Library imports (e.g., import pandas as pd)
3. Markdown cell: Section header (## Analysis)
4. Code cell: Data loading and processing
5. Markdown cell: Section header (## Visualization)
6. Code cell: Plot with echo: true

All Quarto cell options work in notebooks — echo, output-location, highlight-lines, fig-cap, and table options are all supported.

Keeping YAML Separate

The YAML front matter should be in its own cell, separate from any code. Mixing YAML and code in the same cell can cause parsing issues.

Tip: This workflow is ideal for data science teams that already maintain analysis notebooks. Converting to a presentation requires only adding the format declaration — the analysis code, plots, and narrative remain unchanged.