jupyterlab_markdown_insert_content_extension

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
• Glyph picker - second tab in the same dialog with about 150 Unicode glyphs (stars, checkboxes, arrows, bars, shapes, box drawing, math, Greek, currency, typography), searchable by name, with recently used glyphs first and any character reachable by its code point
• 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 and Glyphs

1. Position the cursor where the symbol should go
2. Right-click and select Markdown Tools > Insert Symbol
3. Pick from the Emoji tab, or switch to the Glyphs tab
4. Search or browse, then click a symbol to insert it and close the dialog

Frequently used emoji are remembered between sessions and shown in a bar below the grid. The Glyphs tab lists the 16 most recently used glyphs first, under Recent.

In the Glyphs tab:

• The search matches plain names, and for some glyphs words from the official Unicode names - empty star and white star both find ☆
• A code point such as U+2605 or 2605 inserts that character, including characters outside the list
• The arrow keys move through the glyphs, and Enter inserts the one that has focus. Enter in the search box inserts the first result. The line under the grid names the glyph Enter will insert, and hovering a glyph shows its name as a tooltip
• Glyphs that also have an emoji form, such as ☑ and ▶, are inserted with the text presentation selector U+FE0E, so they do not render as colour emoji

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.