Skillversitas

Sharing Notebooks via GitHub and NbViewer

Notebooks are shareable artifacts: a .ipynb is a file, so version control and static hosting work out of the box. The standard publishing path is GitHub - raw files render, and GitHub Pages (with the Jupyter Book or nbconvert approach) turns a repo into browsable HTML.

Publishing to GitHub

  1. Commit the notebook to a repository (with outputs cleared for clean diffs).
  2. GitHub renders .ipynb files in the browser with executed output - a quick preview for collaborators.
  3. Enable GitHub Pages for the repo to serve static HTML generated from the notebooks.
git init
jupyter nbconvert --to html --self-contained mynotebook.ipynb
git add . && git commit -m "publish notebook"

GitHub Pages with Static HTML

# build static site into docs/
mkdir -p docs
jupyter nbconvert --to html --self-contained --output-dir docs mynotebook.ipynb
git add docs && git commit -m "site" && git push

With GitHub Pages enabled, the site is served at yourusername.github.io/repo/. This is the simplest "hosted notebook" with no server.

NbViewer (Classic)

NbViewer (nbviewer.jupyter.org) was the canonical "paste a GitHub URL, get rendered HTML" service: give it a link to a public .ipynb and it renders the notebook with outputs. It serves as a lightweight share link for public repos.

Collaboration Patterns

  • Clear outputs before committing; run in CI or locally before pushing results.
  • Use jupytext to keep .py/.md twins alongside .ipynb for clean diffs on code-heavy notebooks.
  • Pin kernel and package requirements (environment.yml or requirements.txt) so a collaborator can reproduce the run.
  • For team servers, JupyterHub gives each person a kernel while sharing one codebase.

What to Share

  • Public: GitHub repo (renders) + GitHub Pages HTML for non-technical readers.
  • Internal: repo + a JupyterHub or self-hosted server with SSO.
  • One-off: exported standalone HTML (nbconvert --self-contained) emailed or uploaded anywhere.

Summary

Share notebooks by committing .ipynb files to GitHub (which renders them) and publishing rendered HTML via GitHub Pages or nbconvert --to html --self-contained; NbViewer-style services render public repo URLs on the fly. Pair sharing with cleared outputs, pinned environments, and jupytext twins for clean collaboration.