Skip to content

Jupyter Notebook Integration

The Zer0-Mistakes theme provides full Jupyter notebook support with GitHub Pages compatibility through automated pre-build conversion.

The Notebooks collection landing page: a category sidebar, a difficulty filter, and notebook cards rendered like the rest of the site

Overview

Key features:

  • GitHub Pages Compatible: Uses pre-build conversion (no custom plugins)
  • Automated Conversion: GitHub Actions workflow on push
  • Rich Content: Code, equations, plots, tables, images
  • Responsive Design: Bootstrap 5 styling

How It Works

graph LR
    A[.ipynb File] --> B[nbconvert]
    B --> C[Markdown + Images]
    C --> D[Jekyll Build]
    D --> E[HTML Page]
  1. Notebooks stored in pages/_notebooks/
  2. Conversion script runs during build
  3. Markdown files generated with front matter
  4. Images extracted to assets/images/notebooks/
  5. Jekyll renders final HTML

Quick Start

Add a Notebook

  1. Place .ipynb file in pages/_notebooks/:
pages/_notebooks/
├── data-analysis.ipynb
└── machine-learning-intro.ipynb
  1. Convert notebooks:
# Using Docker
docker-compose exec jekyll ./scripts/convert-notebooks.sh

# Or locally (requires nbconvert)
./scripts/convert-notebooks.sh
  1. View at /notebooks/your-notebook-name/

Conversion Script

Basic Usage

# Convert all notebooks
./scripts/convert-notebooks.sh

# Dry run (preview only)
./scripts/convert-notebooks.sh --dry-run

# Force reconvert all
./scripts/convert-notebooks.sh --force

# List notebooks
./scripts/convert-notebooks.sh --list

What It Does

  1. Finds .ipynb files in pages/_notebooks/
  2. Runs jupyter nbconvert --to markdown
  3. Extracts images to assets/images/notebooks/
  4. Adds Jekyll front matter
  5. Creates collection entry

Notebook Layout

Notebooks use a specialized layout:

# _config.yml
defaults:
  - scope:
      path: "pages/_notebooks"
      type: "notebooks"
    values:
      layout: "notebook"
      permalink: /notebooks/:basename/

Layout Features

  • Metadata display (author, date, kernel)
  • Navigation between notebooks
  • Download link to original .ipynb
  • Comment integration
  • Responsive tables and images

Styling

Code Cells

/* Input cells */
.notebook-input {
  background: var(--bs-code-bg);
  border-left: 3px solid var(--bs-primary);
  padding: 1rem;
}

/* Output cells */
.notebook-output {
  background: var(--bs-light);
  border-left: 3px solid var(--bs-success);
  padding: 1rem;
}

/* Execution count */
.notebook-prompt {
  color: var(--bs-secondary);
  font-family: monospace;
}

Tables

/* Dataframe tables */
.notebook-table {
  overflow-x: auto;
}

.notebook-table table {
  border-collapse: collapse;
  width: 100%;
}

Images

/* Plot outputs */
.notebook-image img {
  max-width: 100%;
  height: auto;
}

MathJax Integration

Equations render automatically:

Inline Math:

The equation $E = mc^2$ is famous.

Block Math:

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

GitHub Actions

Automated Conversion

# .github/workflows/convert-notebooks.yml
on:
  push:
    paths:
      - 'pages/_notebooks/**/*.ipynb'

jobs:
  convert:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Convert notebooks
        run: ./scripts/convert-notebooks.sh
      - name: Commit changes
        run: |
          git add pages/_notebooks/*.md assets/images/notebooks/
          git commit -m "Convert notebooks" || true
          git push

Configuration

Jekyll Config

# _config.yml
collections:
  notebooks:
    output: true
    permalink: /notebooks/:basename/

defaults:
  - scope:
      type: notebooks
    values:
      layout: notebook
      mathjax: true
      toc: true

Makefile Targets

# Convert all notebooks
convert-notebooks:
 ./scripts/convert-notebooks.sh

# Preview conversion
convert-notebooks-dry-run:
 ./scripts/convert-notebooks.sh --dry-run

Troubleshooting

Conversion Fails

  1. Check nbconvert is installed:
pip install nbconvert
  1. Verify notebook is valid JSON
  2. Check for special characters in path

Images Not Showing

  1. Verify images extracted to assets/images/notebooks/
  2. Check image paths in generated Markdown
  3. Rebuild Jekyll site

Math Not Rendering

  1. Ensure mathjax: true in front matter
  2. Check MathJax script loaded
  3. Verify equation syntax

Tables Overflow

Add responsive wrapper:

<div class="table-responsive">
  {{ table_content }}
</div>

Technical Reference

For implementation details (Docker conversion pipeline, nbconvert config, SCSS styling, GitHub Actions workflow):

See also

  • [[Features]]
  • [[Mermaid Diagrams]]
  • [[MathJax Math]]