jupyterlab_markdown_viewer_toc_fix
JupyterLab 4.x extension that fixes broken Table of Contents (TOC) navigation and anchor links in the Markdown Viewer.
Problem
JupyterLab's markdown viewer has broken TOC navigation and anchor links. Affects JupyterLab 4.0 through 4.4.10.
Symptoms:
- Clicking TOC panel items produces no scrolling
- In-document links like
[Go to Section](#section)don't navigate - URL navigation
file.md#sectionfails to scroll to target - Console shows "Heading element not found" errors
Root Cause - Attribute Selector Mismatch:
- JupyterLab's HTML sanitizer removes
idattributes for XSS protection - Headings get
data-jupyter-idattributes instead (default settingallowNamedProperties = false) - Navigation code queries for
idattributes that don't exist querySelector()returnsnulland scroll attempts fail silently- Example:
## Introductionrenders as<h2 data-jupyter-id="Introduction">but TOC queries[id="Introduction"]
Why Notebooks Work But Markdown Viewer Doesn't:
- Notebooks were fixed in August 2025 (commit c94607d591) with conditional attribute selectors
- Markdown viewer was not updated with the same fix
Secondary Issue - Case Mismatch:
- URL fragments are lowercase:
#performance-optimization - Attributes preserve Title-Case from headings:
data-jupyter-id="Performance-Optimization" - Direct string matching fails without case-insensitive comparison
Solution
Extension applies runtime patches to fix navigation without modifying JupyterLab core:
TOC Navigation Patch:
- Connects to markdown viewer's
activeHeadingChangedsignal - Uses conditional attribute selector (
data-jupyter-idvsid) based onsanitizer.allowNamedPropertiessetting - Properly awaits async heading ID resolution from markdown parser
- Scrolls to correct heading element with
scrollIntoView()
Fragment Navigation Patch:
- Intercepts
RenderedHTMLCommon.setFragment()prototype method - Queries both
#idand[data-jupyter-id]selectors with fallback chain - Handles JupyterLab router
routedsignal for in-app navigation - Listens to global
hashchangeevents for URL-based navigation
Case-Insensitive Fallback:
- Loops through all headings with
data-jupyter-idoridattributes - Compares lowercase versions of search term and attribute values
- Returns first match when direct selectors fail
- Resolves mismatch between lowercase URL fragments and Title-Case attributes
All patches include graceful fallbacks to original implementations if patching fails or elements cannot be found.
Install
pip install jupyterlab_markdown_viewer_toc_fix
Uninstall
pip uninstall jupyterlab_markdown_viewer_toc_fix
Development
# Clone and install dependencies
jlpm install
# Set up virtual environment
python -m venv .venv
source .venv/bin/activate
pip install -e .
# Link extension
jupyter labextension develop . --overwrite
# Build
jlpm build
# Watch mode (auto-rebuild on changes)
jlpm watch
Requirements
- JupyterLab >= 4.0.0
Metadata
Release files for jupyterlab-markdown-viewer-toc-fix 1.0.15
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| jupyterlab_markdown_viewer_toc_fix-1.0.15.tar.gz | 251.0 kB | Without provenance | Details for jupyterlab_markdown_viewer_toc_fix-1.0.15.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| jupyterlab_markdown_viewer_toc_fix-1.0.15-py3-none-any.whl | Python 3 | none | any | Details for jupyterlab_markdown_viewer_toc_fix-1.0.15-py3-none-any.whl |
Total release size: 268.8 kB
Release files / jupyterlab_markdown_viewer_toc_fix-1.0.15.tar.gz
| Download URL | jupyterlab_markdown_viewer_toc_fix-1.0.15.tar.gz |
|---|---|
| Size | 251.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2310bd6705cdc7ac9da4e82696db6f257183cf637c598c68e8fb568213722f09
|
|
BLAKE2b-256 checksum How to use checksums |
cdcf1a6910257baeea045242441deff338eff421fdaf27a67621dacc3c2784e0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.12
|
Release files / jupyterlab_markdown_viewer_toc_fix-1.0.15-py3-none-any.whl
| Download URL | jupyterlab_markdown_viewer_toc_fix-1.0.15-py3-none-any.whl |
|---|---|
| Size | 17.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cd679464778326906f6e75606b948de6c830b0075cdff8b72b76e895641eabeb
|
|
BLAKE2b-256 checksum How to use checksums |
69ecd82f85972bc813b4b1c99027aaa39edc20c91f845dceb95dccfe858549cf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.12
|
Security for jupyterlab-markdown-viewer-toc-fix 1.0.15
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.