md2ipynb
"Convert markdown files to Jupyter notebooks (.ipynb). Splits markdown by `---` 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."
When & Why to Use This Skill
This Claude skill automates the conversion of Markdown files into interactive Jupyter Notebooks (.ipynb). It intelligently parses content using horizontal rule delimiters and extracts Python or SQL code blocks into executable cells while handling YAML front matter removal. It is designed to streamline the transition from static documentation to interactive, runnable environments, making it an essential utility for developers, data scientists, and technical writers.
Use Cases
- Tutorial Conversion: Transform static markdown-based technical tutorials into interactive Jupyter Notebooks to provide a hands-on learning experience.
- Data Science Workflow: Quickly migrate documented data analysis steps and SQL queries from markdown files into executable notebooks for immediate testing and visualization.
- Educational Content Creation: Convert structured course notes and markdown-based coding exercises into interactive study guides and practice sets for students.
- Documentation Portability: Turn project READMEs or API documentation containing code snippets into runnable notebooks for faster developer onboarding and experimentation.
| name | md2ipynb |
|---|---|
| description | "Convert markdown files to Jupyter notebooks (.ipynb). Splits markdown by `---` 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
- YAML Front Matter: First
---...---block at file start is removed - Section Delimiters:
---splits content into separate markdown cells - Code Blocks: Fenced code blocks become code cells:
python,sql
- Other code blocks: Non-target languages and language-less blocks remain in markdown cell (not extracted)
---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 ...