Implementation:Eventual Inc Daft Convert Md To Notebook

Knowledge Sources	Eventual_Inc_Daft Jupyter Notebook Format
Domains	Documentation, Tooling
Last Updated	2026-02-08 14:00 GMT

Overview

Concrete tool for converting MkDocs-flavored Markdown documentation files into runnable Jupyter Notebook (.ipynb) files with optional Google Colab badges.

Description

The convert_md_to_notebook.py script parses Markdown files, extracts Python and Bash code blocks into executable notebook code cells, converts MkDocs-specific syntax (admonitions, icon references, relative links) into notebook-compatible HTML, and produces a standard Jupyter Notebook v4 JSON file. It also manages Colab badge insertion in both the generated notebook and the source Markdown.

Usage

Use this tool when generating Colab-ready notebooks from Daft documentation pages (e.g., quickstart guides, tutorials). Run it as a CLI tool or import `convert_md_to_notebook` as a library function.

Code Reference

Source Location

Repository: Eventual_Inc_Daft
File: tools/convert_md_to_notebook.py
Lines: 1-472

Signature

def convert_md_to_notebook(
    input_path: Path,
    output_path: Path | None = None,
    add_colab_badge: bool = True,
    branch: str = "main",
) -> Path:
    """Convert a markdown file to a Jupyter notebook.

    Args:
        input_path: Path to the input markdown file
        output_path: Path for output notebook (default: same name with .ipynb)
        add_colab_badge: Whether to add a Colab badge at the top
        branch: Git branch name for the Colab badge link (default: main)

    Returns:
        Path to the created notebook
    """

Import

from tools.convert_md_to_notebook import convert_md_to_notebook

I/O Contract

Inputs

Name	Type	Required	Description
input_path	Path	Yes	Path to the source Markdown file
output_path	Path or None	No	Destination path for the .ipynb file; defaults to same directory with .ipynb extension
add_colab_badge	bool	No	Whether to insert a Google Colab badge (default True)
branch	str	No	Git branch name used in the Colab badge URL (default "main")

Outputs

Name	Type	Description
return value	Path	Path to the generated Jupyter Notebook file
.ipynb file	File	Jupyter Notebook v4 JSON with code and markdown cells

Usage Examples

CLI Usage

# Convert quickstart.md to a notebook in the same directory
python tools/convert_md_to_notebook.py docs/quickstart.md

# Specify output path
python tools/convert_md_to_notebook.py docs/quickstart.md -o docs/notebooks/quickstart.ipynb

# Skip Colab badge
python tools/convert_md_to_notebook.py docs/quickstart.md --no-colab-badge

# Update source markdown badge and convert
python tools/convert_md_to_notebook.py docs/quickstart.md --update-source --branch feature-branch

Library Usage

from pathlib import Path
from tools.convert_md_to_notebook import convert_md_to_notebook

# Convert a markdown file to notebook
notebook_path = convert_md_to_notebook(
    input_path=Path("docs/quickstart.md"),
    output_path=Path("docs/notebooks/quickstart.ipynb"),
    add_colab_badge=True,
    branch="main",
)
print(f"Notebook written to: {notebook_path}")

Semantic Links

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment