` delimiters into cells, extracts code blocks (python, sql) as code cells, and handles YAML front matter removal. Use when converting documentation, tutorials, or structured markdown into interactive Jupyter notebooks." license: MIT

Markdown to Jupyter Notebook Conversion

Overview

Convert markdown files to Jupyter notebooks with intelligent cell splitting:

• •Split by --- horizontal rules into separate cells
• •Extract fenced code blocks (python, sql) as code cells
• •Automatically remove YAML front matter

Quick Start

uvx --with nbformat python scripts/convert.py input.md output.ipynb

Conversion Rules

1. •YAML Front Matter: First ---...--- block at file start is removed
2. •Section Delimiters: --- splits content into separate markdown cells
3. •Code Blocks: Fenced code blocks become code cells:
   • •python, sql
4. •Other code blocks: Non-target languages and language-less blocks remain in markdown cell (not extracted)
5. •--- inside code blocks: Preserved, does not split

Example

Input:

---
title: Tutorial
---
---
# Introduction
Welcome!
```python
print("hello")

Data Query

SELECT * FROM users

Output notebook cells:
1. Markdown: `# Introduction\nWelcome!`
2. Code (python): `print("hello")`
3. Markdown: `# Data Query`
4. Code (sql): `SELECT * FROM users`

## CLI Options

```bash
uvx --with nbformat python scripts/convert.py <input.md> <output.ipynb> [options]

Options:
  --code-languages  Comma-separated languages for code cells
                    Default: python,sql

Edge Cases

• •Empty sections: Skipped
• •No --- in file: Entire file as single section, code blocks still extracted
• •--- in code blocks: Preserved as content, does not split
• •File without front matter: First content becomes first cell

Dependencies

Run with uvx to automatically handle dependencies:

uvx --with nbformat python scripts/convert.py ...