Skip to content

Download Links and TOC Integration

The mkdocs-jupyter plugin provides seamless integration between notebook download links and table of contents generation. This feature enhances navigation and allows users to easily access source notebooks.

Configuration

The following settings control download links and TOC behavior:

plugins:
  - mkdocs-jupyter:
      include_source: true  # Enable download links
      toc_depth: 3         # TOC depth (1-6)
      enable_default_notebooks_toc: true  # Extract TOC from headings
      enable_default_jupyter_toc: true    # Jupyter-style TOC

How It Works

When include_source: true is set, mkdocs-jupyter automatically:

  1. Creates download links at the top of each notebook page
  2. Preserves original notebooks in the site output
  3. Maintains relative paths for easy access

TOC Extraction

The plugin extracts headings from notebooks and integrates them with MkDocs navigation:

  1. Markdown cells with headings (#, ##, etc.) become TOC entries
  2. Hierarchy preserved - nested headings create nested TOC items
  3. Automatic anchors - headings get URL-friendly IDs

Integration Features

Combined Navigation

The TOC and download links work together to provide:

  • Quick navigation - Jump to any section within the notebook
  • Easy access - Download source from any page
  • Context preservation - TOC shows notebook structure

Security Considerations

When implementing download links:

Access Control

Download links inherit the same access permissions as the page itself. For restricted content, ensure proper authentication is in place.

Best Practices

  1. Consistent Headings - Use clear, descriptive headings in notebooks
  2. Logical Structure - Organize content hierarchically
  3. TOC Depth - Set appropriate toc_depth (usually 2-3)
  4. File Organization - Keep notebooks in logical directories

Examples

Basic Implementation

# In your notebook's first cell:
# # My Analysis Notebook
#
# ## Introduction
# This notebook demonstrates...
#
# ## Data Preparation
# ### Loading Data
# ### Cleaning Steps

This structure generates: - A download link at the top - A TOC with proper nesting - Navigable sections

Advanced Features

You can control TOC behavior per notebook using cell tags:

# Cell tagged with 'hide-toc'
# This heading won't appear in TOC

Testing the Integration

To verify everything works:

  1. Check download links appear on notebook pages
  2. Verify TOC shows notebook structure
  3. Test navigation - clicking TOC items should scroll to sections
  4. Confirm downloads work and preserve formatting

Troubleshooting

Common issues and solutions:

Issue Solution
No download link Ensure include_source: true is set
Missing TOC entries Check heading syntax in markdown cells
Broken navigation Verify no duplicate heading IDs
Download fails Check file permissions and paths