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
The md2ipynb Claude skill is a specialized utility designed to bridge the gap between static documentation and interactive coding. It seamlessly converts Markdown files into Jupyter Notebooks (.ipynb) by intelligently parsing content delimiters, extracting Python and SQL code blocks into executable cells, and cleaning up YAML front matter. This tool is essential for developers and data scientists looking to transform tutorials, technical guides, or structured notes into functional, cell-based development environments.
Use Cases
- Educational Content Creation: Converting Markdown-based technical tutorials or blog posts into interactive Jupyter Notebooks for students to run and experiment with code directly.
- Documentation to Prototype: Transforming static project documentation and API examples into runnable notebooks to facilitate rapid prototyping and internal testing.
- Data Science Workflow Automation: Migrating structured research notes or SQL query collections from Markdown files into organized Jupyter cells for better data visualization and iterative analysis.
- Legacy Content Migration: Batch-converting older Markdown-based code repositories into modern, interactive notebook formats to improve code readability and maintainability.
| 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 ...