Metadata-Version: 2.5
Name: jupyter-mkslides
Version: 0.1.2
Summary: nbconvert custom exporter that converts Jupyter notebooks to mkslides-compatible Markdown
Project-URL: Homepage, https://github.com/tsjshg/jupyter-mkslides
Project-URL: Repository, https://github.com/tsjshg/jupyter-mkslides
Project-URL: Issues, https://github.com/tsjshg/jupyter-mkslides/issues
Author-email: Shingo Tsuji <shingo.tsuji@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: jupyter,mkslides,nbconvert,presentation,reveal.js,slides
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.9
Requires-Dist: nbconvert>=7
Description-Content-Type: text/markdown

# jupyter-mkslides

An `nbconvert` custom exporter that converts Jupyter Notebooks (`.ipynb`) into
Markdown for [mkslides](https://github.com/MartenBE/mkslides).

## Installation

```bash
pip install jupyter-mkslides
```

## Usage

```bash
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:

```bash
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):

| slide_type | Result |
|---|---|
| `slide` | `---` inserted before the cell (new slide) |
| `subslide` | Same as `slide` (`---`) by default; optionally `-v-` (see below) |
| `fragment` | Appended to the previous slide |
| `notes` | Prefixed with `Note:` and turned into speaker notes of the previous slide |
| `skip` | Omitted from the output |
| unset / `-` | `---` inserted so that each cell becomes its own slide |

### 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:

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

and enable the vertical separator in your `mkslides.yml`:

```yaml
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:

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

---

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