jupyterlab_markdown_insert_content_extension

[!TIP] This extension is part of the stellars_jupyterlab_extensions metapackage. Install all Stellars extensions at once: pip install stellars_jupyterlab_extensions

JupyterLab extension for inserting reusable content blocks into markdown files and notebook cells, starting with automatic table of contents generation.

Right-click in markdown editor or notebook cell to access the context menu:

Generated table of contents with hierarchical structure and working anchor links:

Configure TOC caption and maximum heading level through JupyterLab settings:

Features

• Context menu integration - right-click in markdown editors or notebook cells to access all tools via "Markdown Tools" submenu
• Table of contents generation - automatically extracts headings and creates hierarchical TOC with working anchor links
• TOC update support - regenerates existing TOC in place using markers (<!-- TOC:BEGIN --> and <!-- TOC:END -->)
• Per-TOC depth configuration - each TOC stores its depth in the marker (<!-- TOC:BEGIN DEPTH=3 -->) and preserves it across updates
• Heading exclusion - mark headings with <!-- TOC:IGNORE --> to exclude from TOC while preserving numbering
• Hierarchical heading numbering - add, remove, or update numbering on headings (1., 1.1., 1.1.2., etc.)
• GitHub alert boxes - insert > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING] or > [!CAUTION] blockquotes, wrapping the current selection when there is one
• Emoji picker - searchable emoji dialog that tracks frequently used emoji, with the dataset bundled so it works offline
• Configurable settings - customize TOC caption, maximum heading depth, numbering depth, and trailing dot style
• Code block filtering - excludes headings within fenced code blocks from TOC and numbering
• JupyterLab-compatible anchors - generates anchor IDs matching JupyterLab's format for reliable navigation
• Dual mode support - works in both markdown file editors and notebook markdown cells
• Cursor-aware insertion - inserts content at current cursor position
• Automatic TOC updates - TOC is updated automatically when heading numbering changes

Requirements

• JupyterLab >= 4.0.0

Install

pip install jupyterlab_markdown_insert_content_extension

Usage

Table of Contents

1. Open a markdown file or create a markdown cell in a notebook
2. Position cursor where you want the TOC inserted
3. Right-click and select Markdown Tools > Insert Table of Contents
4. TOC is generated with markers for future updates

To update an existing TOC:

• Right-click and select Markdown Tools > Update Table of Contents
• The TOC between markers will be regenerated

Heading Numbering

Add hierarchical numbering to your headings:

1. Right-click and select Markdown Tools > Add Heading Numbering
2. Headings become numbered: # Introduction -> # 1. Introduction

Other numbering commands:

• Remove Heading Numbering - strips all numbering from headings
• Update Heading Numbering - recalculates numbering and updates TOC

Alert Boxes

Insert a GitHub-style alert blockquote:

1. Optionally select the text that should become the alert body
2. Right-click and select Markdown Tools > Insert Alert > Note (or Tip, Important, Warning, Caution)

With no selection, a placeholder body is inserted:

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

Emoji

1. Position the cursor where the emoji should go
2. Right-click and select Markdown Tools > Insert Emoji
3. Search or browse, then click an emoji to insert it and close the dialog

Frequently used emoji are remembered between sessions and shown in a bar below the grid.

Configure Settings

Access settings through Settings -> Settings Editor -> Markdown Insert Content:

• TOC Caption - markdown content inserted before TOC list (default: **Table of Contents**)
• Maximum TOC Heading Level - deepest heading level to include in TOC (1-6, default: 3)
• Maximum Numbering Level - deepest heading level to number (1-6, default: 3)
• Trailing Dot in Numbering - add trailing dot after numbers (default: enabled, e.g., 1.2. vs 1.2)

Settings apply immediately without restart.

Uninstall

pip uninstall jupyterlab_markdown_insert_content_extension

Development

Development install

# Clone repository
git clone https://github.com/stellarshenson/jupyterlab_markdown_insert_content_extension.git
cd jupyterlab_markdown_insert_content_extension

# Set up virtual environment
python -m venv .venv
source .venv/bin/activate
pip install --editable "."

# Link extension with JupyterLab
jupyter labextension develop . --overwrite

# Build extension
jlpm install
jlpm build

Development workflow

# Watch mode - automatically rebuilds on changes
jlpm watch

# In another terminal, run JupyterLab
jupyter lab

Refresh JupyterLab after changes to load updated extension.

Development uninstall

pip uninstall jupyterlab_markdown_insert_content_extension
jupyter labextension list  # Find labextensions folder
# Remove symlink from labextensions folder

Testing

Frontend tests:

jlpm test

Integration tests: See ui-tests/README.md for Playwright integration tests.

Packaging

See RELEASE.md for release process.