Skip to content

notebook-viewer-guide.md

Latest commit

 

History

History
221 lines (174 loc) · 5.93 KB

notebook-viewer-guide.md

File metadata and controls

221 lines (174 loc) · 5.93 KB

Jupyter Notebook Viewing Guide for GitHub Pages

The Problem: Why Raw JSON Shows Up

When you host Jupyter notebooks (.ipynb files) on GitHub Pages, visitors see raw JSON instead of rendered notebooks because:

  1. GitHub.com vs GitHub Pages: GitHub's website has special rendering for .ipynb files, but GitHub Pages is just a static file server
  2. JSON Format: Notebooks are JSON files containing code, markdown, and outputs - browsers don't know how to render this nicely
  3. No Dynamic Processing: GitHub Pages can't run Python/JavaScript to convert notebooks on-the-fly

The Solutions

Option 1: External Rendering (nbviewer.org)

Best for: Quick sharing, no setup required

[View Notebook](https://nbviewer.org/github/username/repository/blob/main/path/notebook.ipynb)

Pros:

  • No conversion needed
  • Always up-to-date
  • Perfect rendering

Cons:

  • External dependency
  • Requires internet
  • Not customizable

Option 2: Convert to HTML (Recommended for Portfolios)

Best for: Professional portfolios, custom styling, self-hosted solutions

Pros:

  • Complete control over styling
  • Fast loading
  • Works offline
  • SEO friendly
  • Professional appearance

Cons:

  • Requires conversion process
  • Larger file sizes
  • Need to update when notebooks change

Why HTML Conversion is Ideal for Your Portfolio

  1. Professional Presentation

    • Clean, consistent styling
    • Custom CSS for branding
    • Better typography and layout

  2. Performance Benefits

    • Faster loading than raw notebooks
    • Better mobile experience
    • Optimized for web viewing

  3. SEO and Accessibility

    • Search engines can index content
    • Screen readers can navigate properly
    • Better semantic structure

  4. Portfolio Integration

    • Seamless integration with your existing index.html
    • Consistent navigation and branding
    • Easy to link between projects

Using the Conversion Script

Prerequisites

pip install nbconvert

Basic Usage

python convert_notebooks_to_html.py

What It Does

  1. Finds all notebooks in your repository
  2. Converts each to HTML maintaining directory structure
  3. Generates an index page with organized links
  4. Extracts titles from notebook metadata or content
  5. Creates navigation between original and HTML versions

Output Structure

html_notebooks/
├── Data_Analysis/
│   ├── automobile-data-wrangling-cleaning.html
│   ├── car-price-model-development.html
│   └── ...
├── ML/
│   ├── Classification/
│   │   └── ...
│   └── Regression/
│       └── ...
└── ...
notebook_index.html  # Generated index page

Integrating with Your Portfolio

1. Update Your Main Index

Add links to the HTML versions in your existing index.html:

<div class="notebook-section">
    <h2>📊 Data Science Notebooks</h2>
    <p><a href="notebook_index.html">View All Notebooks (HTML)</a></p>
    
    <!-- Featured notebooks -->
    <div class="featured-notebooks">
        <a href="html_notebooks/Data_Analysis/car-price-model-development.html">
            Car Price Prediction Model
        </a>
        <a href="html_notebooks/Capstone_Data_Science_SpaceY/spacex-machine-learning-prediction.html">
            SpaceX Launch Prediction
        </a>
    </div>
</div>

2. Automated Updates

For automatic conversion on each commit, create .github/workflows/convert-notebooks.yml:

name: Convert Notebooks to HTML

on:
  push:
    paths:
      - '**/*.ipynb'
  workflow_dispatch:

jobs:
  convert:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
          
      - name: Install dependencies
        run: |
          pip install nbconvert
          
      - name: Convert notebooks
        run: python convert_notebooks_to_html.py
        
      - name: Commit HTML files
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add html_notebooks/ notebook_index.html
          git commit -m "Auto-update notebook HTML versions" || exit 0
          git push

Best Practices

1. Keep Both Versions

  • Original .ipynb: For development and collaboration
  • HTML version: For public viewing and portfolios

2. Organize Clearly

  • Use descriptive titles in notebooks
  • Maintain consistent directory structure
  • Add README files for context

3. Custom Styling

  • Modify the CSS in the conversion script
  • Match your portfolio's branding
  • Ensure mobile responsiveness

4. Performance Optimization

  • Use relative links where possible
  • Optimize images in notebooks
  • Consider lazy loading for large notebooks

Troubleshooting

Common Issues

  1. nbconvert not found: Install with pip install nbconvert
  2. Conversion fails: Check for syntax errors in notebooks
  3. Missing outputs: Re-run notebooks before conversion
  4. Large files: Consider splitting complex notebooks

Error Recovery

If conversion fails for specific notebooks:

  1. Check the error message in the script output
  2. Manually fix problematic notebooks
  3. Re-run the conversion script

Alternative Approaches

1. Jupyter Book

For more complex documentation:

pip install jupyter-book
jupyter-book build .

2. Voilà Dashboards

For interactive presentations:

pip install voila
voila notebook.ipynb --no-browser

3. Custom Static Site Generators

  • Hugo: With notebook plugins
  • Jekyll: GitHub Pages native
  • Sphinx: Python documentation standard

Conclusion

Converting notebooks to HTML provides the best experience for portfolio visitors while maintaining the flexibility of Jupyter notebooks for development. The conversion script automates this process and creates a professional presentation of your data science work.