jupyter-mkslides

An nbconvert custom exporter that converts Jupyter Notebooks (.ipynb) into Markdown for mkslides.

Installation

pip install jupyter-mkslides

Usage

jupyter nbconvert --to mkslides presentation.ipynb

This generates presentation.md along with presentation_files/, which contains the extracted image outputs. The generated Markdown can be fed directly to mkslides. Pass the directory containing the Markdown, not the .md file itself:

mkslides serve .
# or
mkslides build .

When mkslides is given a single .md file, it copies only its own default assets into the output site, so presentation_files/ and any other images referenced from the Markdown (e.g. <img src="photo.jpg"> in a Markdown cell) will not be found. Passing the directory copies everything in it, so keep the Markdown and its images in a dedicated slides folder rather than running mkslides from a project root (which would copy .venv and the like too).

Cell metadata handling

Each cell is converted according to its metadata.slideshow.slide_type (set via the Slideshow toolbar in Jupyter):

Turning subslides into vertical slides

The default mkslides (reveal.js) configuration has no vertical slide separator, so subslide cells are output as regular slide breaks (---) by default. To use vertical slides, pass the option at conversion time:

jupyter nbconvert --to mkslides --MkSlidesExporter.subslide_as_vertical=True presentation.ipynb

and enable the vertical separator in your mkslides.yml:

slides:
  separator_vertical: '^\s*-v-\s*$'

Image outputs of code cells (image/png, etc.) are saved to {notebook name}_files/ by nbconvert's standard ExtractOutputPreprocessor and linked as ![png](...).

HTML outputs (DataFrame tables, etc.)

text/html outputs such as pandas/polars DataFrame tables are wrapped in a single <small> element so they fit on a slide. Any <small> tags already present in the output (polars emits one around its shape: line) are removed so the content is not shrunk twice. To keep the HTML untouched:

jupyter nbconvert --to mkslides --MkSlidesExporter.html_output_small=False presentation.ipynb

日本語版は README_ja.md を参照してください。