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 ...