Notebooks

Native Jupyter notebook support — drop .ipynb into content and build

2 min read 345 words

Bengal renders Jupyter notebooks (.ipynb) natively. Drop a notebook into your content directory and it builds as a page—no conversion step, no extra tooling.

Tip

New to notebooks? Follow the Setup Guide for a step-by-step walkthrough—add your first notebook, configure Download/Binder/Colab, and override metadata.

How It Works

  1. Addanalysis.ipynb to content/docs/(or any content section)
  2. Bengal discovers it via Patitasparse_notebook(zero dependencies, stdlib JSON)
  3. Cells become Markdown: markdown cells as-is, code cells as fenced blocks, outputs as HTML
  4. The page uses thenotebook/single.html template with download badge, kernel info, and optional Binder/Colab links (Colab auto-generated when repo_urlis set)

Example Notebooks

The notebooks below are live examples—they live in this docs site and render as pages.

Hello Notebook

Minimal demo: one markdown cell, one code cell with output.
Content Features

Markdown, code, math (E=mc^2), and outputs—the full pipeline.

What Gets Rendered

Cell Type Result
Markdown Rendered as Markdown (headings, lists, bold, math, etc.)
Code Fenced code block with syntax highlighting (Rosettes)
Code output (stream) <div class="nb-output"><pre>...</pre></div>— compact styling
Code output (execute_result) Text asnb-output, images as nb-output--image, HTML as nb-output--html
Code output (error) <div class="nb-output nb-output--error"><pre class="notebook-error">...</pre></div>

Metadata

Notebook metadata flows into page frontmatter:

  • title — fromnotebook.metadata.titleor filename stem
  • type —notebook(for template selection)
  • notebook.kernel_name — e.g.python3
  • notebook.cell_count — number of cells

Override in notebook metadata (Jupyter Book / JupyterLab conventions) or via cascade from section_index.md.

Requirements

  • nbformat 4 or 5 — Modern notebooks only
  • No nbformat dependency — Patitas parses JSON with stdlib; Bengal has zero extra deps for notebooks

Seealso

  • Code Blocks — Syntax highlighting for code cells
  • Math and LaTeX — Inline and block equations in markdown cells
  • Patitas — The parser that powers notebook conversion