# Notebook Setup Guide

URL: /docs/content/authoring/notebooks/setup/
Section: notebooks

--------------------------------------------------------------------------------

Notebook Setup Guide This guide walks you through adding Jupyter notebooks to your Bengal site as an end user. No conversion tools, no extra dependencies—just drop .ipynb files and build. 1Create or Export a NotebookCreate a notebook in Jupyter Lab, Jupyter Notebook, or VS Code. Save it as .ipynb (nbformat 4 or 5). Example: analysis.ipynb with a markdown cell and a Python code cell. 2Add It to Your ContentCopy 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. 3Buildbengal 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 .ipynb file (auto-generated) Share — LLM text, AI assistants 4(Optional) Add Binder or ColabTo let readers run your notebook in the cloud: Binder — Add binder_url in 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_url in frontmatter if needed. 5(Optional) Override MetadataNotebook metadata (kernel, title, etc.) flows from the .ipynb file. Override via frontmatter in a companion _index.md or in the notebook's own metadata (Jupyter conventions). Field Source Override title notebook.metadata.title or 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 from repo_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) .ipynb copy 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? Add binder_url in your section cascade or notebook frontmatter. Colab not showing? Add repo_url to [params] in bengal.toml or config/_default/params.yaml for auto-generation, or set colab_url explicitly in frontmatter/cascade. CI/CD: In GitHub Actions, repo_url and colab_branch are inferred automatically. Override with BENGALxPARAMSxREPO_URL or BENGALxPARAMSxCOLAB_BRANCH env vars (Hugo-style). Wrong nav order? Use weight in frontmatter (lower = higher in nav). Same as Markdown pages. Info Seealso Notebooks overview — What gets rendered, metadata, examples Code Blocks — Syntax highlighting for code cells Patitas — The parser that powers notebook conversion

--------------------------------------------------------------------------------

Metadata:
- Author: lbliii
- Word Count: 513
- Reading Time: 3 minutes