Turn Jupyter Notebooks into Reveal.js Slides: A Practical Guide

Why Convert a Notebook to Slides?

When you’re teaching a class or presenting at a conference, you often want to show code, plots, and markdown in a clean, slide‑style format. Re‑creating the same material in PowerPoint or Keynote is tedious and risks drift between the notebook and the slides. Jupyter’s nbconvert can export a notebook straight to a Reveal.js presentation, preserving live outputs and interactive widgets. The trick is to use the built‑in --to slides template, leverage cell tags to control slide visibility, and optionally drop in a custom theme to match your branding.

How nbconvert Turns Cells into Slides

The nbconvert tool ships with a slides template that wraps each cell in a <section> element understood by Reveal.js. By default:

• Markdown cells become slide headings and body text.
• Code cells appear as code blocks with their output (plots, tables, etc.) rendered below.
• Each cell becomes a separate slide unless the cell is tagged with skip or slide-only.

These tags let you keep a single source notebook while tailoring the exported presentation. For example, a cell tagged skip will be omitted from the slides, but still present in the notebook for reference.

Setting Up Your First Slide Export

Start with a minimal notebook (demo.ipynb):

%%writefile demo.ipynb
{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": ["# My Presentation"]
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": ["import matplotlib.pyplot as plt", "plt.plot([1,2,3], [4,5,6])", "plt.show()"]
    },
    {
      "cell_type": "markdown",
      "metadata": {"tags": ["skip"]},
      "source": ["This cell is hidden in slides."]
    }
  ],
  "metadata": {},
  "nbformat": 4,
  "nbformat_minor": 2
}

Run the export:

jupyter nbconvert --to slides demo.ipynb --output demo_slides

Check the generated demo_slides.slides.html in a browser. You should see two slides: one with the title, and one with the plotted figure. The tagged cell is omitted.

Customizing the Look and Feel

Reveal.js supports themes and custom CSS. Create a directory my_template with a custom.css file:

/* my_template/custom.css */
.reveal {
  background: #f5f5f5;
}
.reveal h1 {
  color: #2c3e50;
}

Tell nbconvert to use this template directory:

jupyter nbconvert --to slides demo.ipynb \
  --output demo_slides \
  --template my_template

The resulting presentation now uses your custom styles. If you want a full Reveal.js theme, copy an existing theme folder (e.g., reveal.js/dist/theme/solarized) into my_template and reference it in custom.css or via the --theme flag.

Trade‑Offs and Practical Limitations

• Large Output Cells: Dataframes, images, or plots that occupy many megabytes inflate the final HTML. This can slow down slide navigation, especially on mobile devices.
• Re‑Execution of Code: nbconvert re‑runs the notebook during export. If you rely on side‑effects (e.g., random number generation, live database queries), the slide outputs may differ from what you see in the notebook. Seed your random generators or use --execute=false if you want to preserve the current outputs.
• Magic Commands: Some IPython magics (like %timeit) produce output that is specific to the live kernel. When re‑executed, they may produce different timing results, which could mislead an audience.

Deploying the Slides

Once you have demo_slides.slides.html and its accompanying assets (Reveal.js, CSS, images), you can serve it in several ways:

1. Local Preview: python -m http.server 8000 and navigate to http://localhost:8000/demo_slides.slides.html.
2. Static Site Host: Upload the demo_slides folder to GitHub Pages, Netlify, or any static‑site provider. The presentation will be accessible via a simple URL.
3. Embedding: Include the demo_slides.slides.html in another web page using an <iframe> for a seamless experience.

Checklist before going live:

• Verify all slides appear as expected.
• Confirm that interactive widgets (if any) work in the exported file.
• Check that the custom CSS is applied.
• Test on the target device (desktop, laptop, tablet).

Conclusion: Turn Your Notebook into a Professional Talk

Using nbconvert --to slides gives you a lightweight, reproducible way to convert notebooks into Reveal.js presentations. Cell tags let you keep a single source while tailoring the output; a custom template directory gives you full control over branding. Keep an eye on output size and re‑execution side‑effects, and you’ll have a polished slide deck ready for any audience. Happy presenting!