Jupyter Notebook Integration for Jekyll

Overview

This implementation adds full Jupyter notebook support to the Zer0-Mistakes Jekyll theme with GitHub Pages compatibility. Notebooks are converted to Jekyll-compatible Markdown files during the build process, maintaining all formatting, code blocks, outputs, and mathematical equations.

🎯 Key Features

✅ GitHub Pages Compatible - Uses pre-build conversion (no custom plugins)
✅ Automated Conversion - GitHub Actions workflow converts notebooks on push
✅ Manual Control - Makefile targets for local conversion
✅ Rich Content Support - Code, equations, plots, tables, and images
✅ Responsive Design - Bootstrap 5 styling with mobile-first layout
✅ SEO Optimized - Proper front matter and Schema.org markup
✅ MathJax Integration - LaTeX equation rendering (already configured)

📁 Implementation Components

1. Docker Environment (docker/Dockerfile)

• Added Python 3, pip, and jupyter nbconvert
• Enables notebook conversion in containerized development

2. Conversion Script (scripts/convert-notebooks.sh)

• Converts .ipynb files to Jekyll Markdown
• Extracts images to assets/images/notebooks/
• Adds Jekyll front matter with metadata
• Supports dry-run, force, and list modes

3. Notebook Layout (_layouts/notebook.html)

• Extends default.html layout
• Displays metadata (author, date, kernel info)
• Includes navigation between notebooks
• Share buttons and download link
• Comment system integration

4. Notebook Styling (_sass/notebooks.scss)

• Code cell and output formatting
• Execution count display
• Table and image styling
• Responsive design for mobile
• Dark mode support

5. Jekyll Configuration (_config.yml)

• Collection defaults for notebooks
• Front matter defaults (layout, metadata)
• Proper permalink structure

6. Makefile Targets

• make convert-notebooks - Convert all notebooks
• make convert-notebooks-dry-run - Preview conversion
• make convert-notebooks-force - Force reconvert all
• make list-notebooks - List notebooks to convert
• make clean-notebooks - Remove converted files

7. GitHub Actions (.github/workflows/convert-notebooks.yml)

• Automatic conversion on push to main/develop
• Dry-run preview for pull requests
• Commits converted files back to repo
• Validates converted Markdown

🚀 Usage

Local Development

1. Add a Notebook

Place your .ipynb file in pages/_notebooks/:

cp my-notebook.ipynb pages/_notebooks/

2. Convert Notebook

# Preview what will be converted
make convert-notebooks-dry-run

# Convert the notebook
make convert-notebooks

# Or use the script directly
./scripts/convert-notebooks.sh

3. View Results

The converted Markdown file appears at:

• pages/_notebooks/my-notebook.md

Extracted images go to:

• assets/images/notebooks/my-notebook_files/

Docker Development

Rebuild Container with Python/Jupyter

docker-compose down
docker-compose up --build

Convert Notebooks in Container

docker-compose exec jekyll ./scripts/convert-notebooks.sh

Automatic Conversion (GitHub Actions)

When you push .ipynb files to GitHub:

1. Push notebook to main/develop branch

   git add pages/_notebooks/my-notebook.ipynb
   git commit -m "Add new notebook"
   git push
   

2. GitHub Actions automatically:
   • Converts the notebook to Markdown
   • Extracts images
   • Commits converted files
   • Pushes changes back
3. Jekyll builds the site with converted Markdown

Manual Force Reconversion

To reconvert all notebooks (useful after styling changes):

# Locally
make convert-notebooks-force

# Via GitHub Actions (manual trigger)
# Go to Actions > Convert Jupyter Notebooks > Run workflow
# Enable "force_reconvert" option

📝 Front Matter

Notebooks are converted with Jekyll front matter extracted from:

1. Notebook metadata (if present)
2. First markdown cell starting with #
3. Filename (as fallback)

Example generated front matter:

---
title: "My Notebook Title"
description: "Jupyter notebook"
layout: notebook
collection: notebooks
date: 2025-11-29T10:00:00.000Z
categories: [Notebooks]
tags: [jupyter, python]
comments: true
jupyter_metadata: true
lastmod: 2025-11-29T10:00:00.000Z
---

🎨 Customization

Modify Notebook Styling

Edit _sass/notebooks.scss to customize:

• Code cell colors
• Output area styling
• Table formatting
• Image display
• Mobile responsiveness

Change Conversion Behavior

Edit scripts/convert-notebooks.sh to modify:

• Front matter generation
• Image extraction directory
• Markdown formatting
• Error handling

Customize Layout

Edit _layouts/notebook.html to change:

• Metadata display
• Navigation structure
• Share buttons
• Related notebooks

📊 Test Notebook

A sample notebook is included at pages/_notebooks/test-notebook.ipynb demonstrating:

• ✅ Markdown formatting
• ✅ Python code execution
• ✅ LaTeX equations ($E = mc^2$)
• ✅ Matplotlib visualizations
• ✅ Pandas DataFrames
• ✅ Code output display

To test the full pipeline:

make convert-notebooks
# View the converted file at pages/_notebooks/test-notebook.md

🔧 Troubleshooting

Notebook Won’t Convert

Check dependencies:

python3 --version
python3 -c "import nbconvert" && echo "✓ nbconvert installed"

Install if missing:

pip3 install jupyter nbconvert

Images Not Displaying

Check image paths in converted Markdown:

grep -r "!\[" pages/_notebooks/*.md

Verify images exist:

ls -R assets/images/notebooks/

Fix paths if needed: The conversion script should use Jekyll-compatible paths:

![Image](/assets/images/notebooks/my-notebook_files/image.png)

Conversion Fails in Docker

Rebuild container with Python:

docker-compose down
docker-compose build --no-cache
docker-compose up

Check Python installation in container:

docker-compose exec jekyll python3 --version
docker-compose exec jekyll pip3 list | grep nbconvert

GitHub Actions Not Running

Check workflow triggers:

• Workflow only runs on changes to .ipynb files in pages/_notebooks/
• Or changes to scripts/convert-notebooks.sh
• Or changes to the workflow file itself

Manual trigger: Go to GitHub Actions > Convert Jupyter Notebooks > Run workflow

LaTeX Equations Not Rendering

MathJax is already configured in _includes/core/head.html

If equations don’t render:

1. Check browser console for MathJax errors
2. Verify equations use proper LaTeX syntax
3. Ensure MathJax script loads before content

📚 Additional Resources

nbconvert Documentation

• https://nbconvert.readthedocs.io/
• Markdown conversion options
• Custom templates

Jekyll Collections

• https://jekyllrb.com/docs/collections/
• Collection configuration
• Front matter defaults

MathJax Documentation

• https://www.mathjax.org/
• LaTeX syntax reference
• Configuration options

🔄 Future Enhancements

Potential improvements for future versions:

1. Interactive Widgets - Explore client-side rendering options
2. Notebook Metadata - Extract more detailed kernel/execution info
3. Version Control - Track notebook changes and show diffs
4. Search Integration - Index notebook content for site search
5. Code Folding - Collapsible code cells for long notebooks
6. Execution in Browser - JupyterLite integration for live execution
7. NBViewer Fallback - Link to NBViewer for complex notebooks

📄 Files Modified/Created

Created Files

• docker/Dockerfile (modified - added Python/nbconvert)
• scripts/convert-notebooks.sh
• _layouts/notebook.html
• _sass/notebooks.scss
• .github/workflows/convert-notebooks.yml
• pages/_notebooks/test-notebook.ipynb (sample content added)
• docs/JUPYTER_NOTEBOOKS.md (this file)

Modified Files

• _sass/custom.scss (imported notebooks.scss)
• _config.yml (added notebooks collection defaults)
• Makefile (added notebook conversion targets)

✅ Implementation Complete

All components are in place for full Jupyter notebook support:

1. ✅ Docker environment with Python/nbconvert
2. ✅ Conversion script with comprehensive options
3. ✅ Dedicated notebook layout with Bootstrap 5
4. ✅ Custom SCSS styling for notebooks
5. ✅ Jekyll configuration for notebooks collection
6. ✅ Makefile targets for manual control
7. ✅ GitHub Actions for automatic conversion
8. ✅ Test notebook with sample content

Next step: Push to GitHub to trigger the automated conversion workflow!

git add .
git commit -m "feat: add Jupyter notebook rendering support

- Add Python/nbconvert to Docker environment
- Create notebook conversion script with image extraction
- Add dedicated notebook layout extending default.html
- Implement notebook-specific SCSS styling
- Configure notebooks collection in Jekyll
- Add Makefile targets for manual conversion
- Set up GitHub Actions for automatic conversion
- Include test notebook with sample content

Supports GitHub Pages deployment via pre-build conversion"

git push origin main

🎉 Success Criteria

Your implementation is working correctly if:

• make convert-notebooks runs without errors
• Converted .md files appear in pages/_notebooks/
• Images are extracted to assets/images/notebooks/
• Front matter is properly formatted
• Local Jekyll server displays notebooks correctly
• MathJax renders LaTeX equations
• Code cells have proper syntax highlighting
• GitHub Actions workflow runs on push
• Converted files are committed back to repo
• GitHub Pages builds successfully

Congratulations! Your Jekyll site now supports Jupyter notebooks! 🎊