Notebook Setup Guide

Step-by-step guide to adding Jupyter notebooks to your Bengal site

3 min read 596 words

This guide walks you through adding Jupyter notebooks to your Bengal site as an end user. No conversion tools, no extra dependencies—just drop.ipynbfiles and build.

  1. 1

    Create or Export a Notebook

    Create a notebook in Jupyter Lab, Jupyter Notebook, or VS Code. Save it as.ipynb(nbformat 4 or 5).

    Example:analysis.ipynbwith a markdown cell and a Python code cell.

  2. 2

    Add It to Your Content

    Copy the notebook into any content directory. Bengal treats it like a Markdown page.

    content/
  docs/
    tutorials/
      analysis.ipynb    ← Add here

    Or nest it in a section:

    content/
  docs/
    guides/
      _index.md
      getting-started.ipynb
      advanced.ipynb

    The notebook will appear in the sidebar nav alongside other pages in that section.

  3. 3

    Build

    bengal build

    That's it. Bengal discovers the notebook, parses it via Patitas (stdlib JSON, no nbformat), and renders it as a page with:

    • Left sidebar — Same doc navigation as your other pages
    • Page hero — Breadcrumbs, title, metadata (kernel, cell count)
    • Content — Markdown cells as prose, code cells as fenced blocks with syntax highlighting, outputs as HTML
    • Right sidebar — Table of contents (from markdown headings), contextual graph
    • Download button — Links to the.ipynbfile (auto-generated)
    • Share — LLM text, AI assistants
  4. 4

    (Optional) Add Binder or Colab

    To let readers run your notebook in the cloud:

    Binder — Addbinder_urlin section cascade or notebook frontmatter:

    # Section cascade in content/docs/notebooks/_index.md
---
binder_url: https://mybinder.org/v2/gh/your-org/your-repo/main?filepath=content/docs/notebooks/
---

    Colab (auto-generated) — Add repo_url to [params] in bengal.toml (or config/_default/params.yaml):

    [params]
repo_url = "https://github.com/your-org/your-repo"
colab_branch = "main"   # optional, default: main
colab_path_prefix = "site"   # when site lives in repo subdirectory (e.g. site/content/...)

    The Colab button will appear on every notebook page. Override per-page with colab_urlin frontmatter if needed.

  5. 5

    (Optional) Override Metadata

    Notebook metadata (kernel, title, etc.) flows from the.ipynb file. Override via frontmatter in a companion _index.mdor in the notebook's own metadata (Jupyter conventions).

    Field Source Override
    title notebook.metadata.titleor filename title:in frontmatter
    description — description:in frontmatter
    download_url Auto from source download_url:(rare)
    binder_url — binder_url:in cascade
    colab_url Auto fromrepo_url + colab_branch colab_url:in cascade (overrides)

What You Get

Output Purpose
HTML page Rendered notebook with doc layout
index.txt LLM-friendly plain text (for AI, RAG)
index.json Structured data (search index)
.ipynbcopy Download link for readers

Notebooks are included in search, sitemaps, and the site index—same as regular docs.

Troubleshooting

Download button missing? The.ipynb is copied to output automatically. If the button doesn't appear, check that the page has a valid source_path(e.g. the notebook was discovered from your content dir).

Binder not showing? Addbinder_urlin your section cascade or notebook frontmatter.

Colab not showing? Addrepo_url to [params] in bengal.toml or config/_default/params.yaml for auto-generation, or set colab_urlexplicitly in frontmatter/cascade.

CI/CD: In GitHub Actions,repo_url and colab_branch are inferred automatically. Override with BENGALxPARAMSxREPO_URL or BENGALxPARAMSxCOLAB_BRANCHenv vars (Hugo-style).

Wrong nav order? Useweightin frontmatter (lower = higher in nav). Same as Markdown pages.

Seealso