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

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

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.
namemd2ipynb
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."
licenseMIT

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