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:

Push notebook to main/develop branch

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

GitHub Actions automatically:
Converts the notebook to Markdown
Extracts images
Commits converted files
Pushes changes back
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:

Notebook metadata (if present)
First markdown cell starting with #
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]({{ site.baseurl }}/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:

Check browser console for MathJax errors
Verify equations use proper LaTeX syntax
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:

Interactive Widgets - Explore client-side rendering options
Notebook Metadata - Extract more detailed kernel/execution info
Version Control - Track notebook changes and show diffs
Search Integration - Index notebook content for site search
Code Folding - Collapsible code cells for long notebooks
Execution in Browser - JupyterLite integration for live execution
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:

✅ Docker environment with Python/nbconvert
✅ Conversion script with comprehensive options
✅ Dedicated notebook layout with Bootstrap 5
✅ Custom SCSS styling for notebooks
✅ Jekyll configuration for notebooks collection
✅ Makefile targets for manual control
✅ GitHub Actions for automatic conversion
✅ 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:

Congratulations! Your Jekyll site now supports Jupyter notebooks! 🎊

User guide: For setup and usage instructions, see Jupyter Notebook Integration in the user documentation.