Share Notebooks: nbconvert or GitHub

You've spent hours cleaning data, building visualizations, and extracting insights in a Jupyter notebook — but when you share it, your colleague sees raw JSON, broken links, or a confusing mix of code and output. Sharing notebooks poorly undermines your analysis and wastes everyone's time. This lesson shows you two battle-tested ways to share notebooks with nbconvert or GitHub, so your work is clear, reproducible, and impressive.

The problem this lesson solves

Sharing a notebook isn't as simple as sending the .ipynb file. That file is a JSON document that only Jupyter renders properly. Non-technical stakeholders, managers, or clients often can't (or won't) open it. Even when they can, the default view mixes code, outputs, and markdown in a way that's hard to follow.

The core problem: your audience needs to see results, not your code's raw guts. You need a way to present your findings that's professional, accessible, and maintainable.

Core concept / mental model

Think of a notebook as a lab notebook: it contains your complete process — code, notes, experiments — but it's not meant for public consumption. Sharing a notebook requires transforming it into a medium your audience can consume: a static HTML report, a PDF, a slide deck, or a live webpage.

Two main tools help you do this:

• nbconvert — a command-line tool that converts .ipynb files into other formats (HTML, PDF, Markdown, etc.). It gives you control over the output.
• GitHub — a platform that renders notebooks natively in the browser. It gives you convenience and collaboration.

Think of nbconvert as your "print" button — it creates a static snapshot. GitHub is like a "share" button — it hosts your notebook so others can view and comment, without you worrying about file transfers.

How it works step by step

Step 1: Make your notebook presentable

Before you share, clean up your notebook:

• Use Markdown cells to explain your thought process (inputs, methods, conclusions).
• Hide the most complex code cells (use the hide_input tag in Jupyter) if they're not essential.
• Ensure all outputs are rendered (run all cells) so your notebook reflects the final state.

Step 2: Choose nbconvert for static reports

If you want a clean, standalone file that anyone can open, use nbconvert. It converts your notebook to HTML, PDF, Markdown, or even a slide show. The HTML output is ideal for email attachments or hosting on any static site.

Step 3: Choose GitHub for live, shareable notebooks

If you want a URL that anyone can view (and optionally comment on), push your notebook to a GitHub repository. GitHub automatically renders .ipynb files — including outputs and interactive widgets — in a readable format. You can also use GitHub Pages to host a polished version.

Step 4: Keep your shared version reproducible

Whichever method you choose, include a requirements.txt or environment.yml so others can recreate your environment. For GitHub, a README that directs viewers to the notebook and explains the data sources is a best practice.

Hands-on walkthrough

Example 1: Use nbconvert to create an HTML report

Let's start with a simple notebook that analyzes a small dataset. We'll convert it to a clean HTML file.

# analysis.ipynb (created in Jupyter)
# Cell 1: import libraries
import pandas as pd
import numpy as np

# Cell 2: create sample data
df = pd.DataFrame({'value': np.random.randn(100)})

# Cell 3: summary statistics
print(df.describe())

Run every cell, save, then open your terminal and run nbconvert:

jupyter nbconvert --to html analysis.ipynb

You'll get analysis.html in the same folder. It contains all the outputs, markdown, and code in a static page. Open it in any browser to verify. If you want to hide the code (keeping only outputs and markdown), use the --no-input flag:

jupyter nbconvert --to html --no-input analysis.ipynb

Expected output: A file named analysis.html, fully self-contained. When you open it, you'll see the code (or not, with --no-input) and the printed statistics exactly as they appeared in the notebook.

Example 2: Push a notebook to GitHub

If you have git and a GitHub account, sharing is one push away:

git init my-project
cd my-project
# copy your notebook into this folder
cp ~/notebooks/analysis.ipynb .
# add a README (optional but recommended)
echo "# My Analysis" > README.md
# commit and push
git add .
git commit -m "Add analysis notebook"
git remote add origin https://github.com/your-username/my-project.git
git push -u origin main

Now go to https://github.com/your-username/my-project, click on analysis.ipynb — GitHub renders it with outputs, tables, and plots. You can share that URL with anyone, and they can even comment on the notebook if you enable issues.

Example 3: Combine both — create a project report with GitHub Pages

For a polished, professional deliverable, you can use nbconvert to create an HTML report, then host it on GitHub Pages:

jupyter nbconvert --to html analysis.ipynb
mkdir -p docs
touch docs/.nojekyll
mv analysis.html docs/
git add docs
git commit -m "Add HTML report"
git push

Enable GitHub Pages in your repo settings (Source: branch main, folder /docs). Now your report is live at https://your-username.github.io/my-project/.

Compare options / when to choose what

Which to choose? If you need a static artifact (email, print), use nbconvert. If you want a live, version-controlled artifact that others can comment on, use GitHub. For the best of both worlds, use GitHub Pages with nbconvert-generated HTML.

Troubleshooting & edge cases

nbconvert not found

pip install nbconvert

Also ensure you're in the right virtual environment. If you use conda: conda install -c conda-forge nbconvert.

PDF conversion fails with missing LaTeX

Error: xelatex not found or PDF writer failed. Install a TeX distribution (e.g., sudo apt install texlive-xetex on Linux, or use the basictex installer on macOS). Or switch to HTML format — no LaTeX needed.

GitHub doesn't render interactive widgets (like Plotly)

By default, GitHub renders static outputs. For interactive plots, either embed an interactive version (using plotly and cufflinks) or use external services like Binder. To keep it simple, use Matplotlib static plots in your notebook for GitHub. You can also embed HTML output that's self-contained.

Notebook too large to push to GitHub

Data cleaning notebooks often accumulate huge outputs. Use Output cleaning before commit:

jupyter nbconvert --clear-output --inplace notebook.ipynb
git add notebook.ipynb
git commit -m "Clear outputs"

But remember: clearing outputs removes them from GitHub's preview. Better: keep outputs for the final push, or use --no-input to hide code but keep outputs.

What you learned & what's next

You've learned two ways to share notebooks with nbconvert or GitHub. You can now:

• Explain the core idea: transform notebooks into shareable formats.
• Use nbconvert to generate HTML, PDF, or slides.
• Push a notebook to GitHub for instant rendering and collaboration.
• Combine both for a GitHub Pages hosted report.

Every time you share a notebook, think about your audience: what do they need to see? Code? Results? Both? Choose nbconvert for static artifacts, GitHub for interaction, and GitHub Pages for a polished public presence.

What's next: In the next lesson, you'll explore Jupyter Notebook extensions and advanced tips for making your notebooks even more powerful — from code folding to variable inspection.