Notebook Extension

webifier.notebook registers content renderers for .ipynb and notebook=... links. When Webifier discovers a notebook link, it converts the notebook with nbconvert, extracts the notebook body, post-processes links/assets, and writes a sibling HTML page.

config:
  webifier:
    extensions:
      site:
        uses: webifier.standard
      notebook:
        uses: webifier.notebook

The notebook source stays in your repository. Webifier renders a static HTML page around it, preserving the site header/footer, page navigation, optional comments, shared code styling, and local assets.

Notebook rendering is intentionally close to the normal content-page flow:

1. Webifier reads the .ipynb.
2. It extracts optional page data from a first-cell YAML preface and from a sibling page.yml.
3. It converts the notebook with nbconvert.
4. It extracts the notebook body from the exported HTML.
5. It post-processes local images, videos, iframes, scripts, and links.
6. It writes a content page that uses the same Webifier chrome as Markdown pages.

This means notebooks can sit beside Markdown pages and YAML pages without needing a separate publishing path.

A notebook can define page data in the first Markdown cell. If the cell contains only a YAML page preface, Webifier removes that cell from the rendered notebook.

---
title: Tiny Notebook Example
nav: false
header:
  title: Tiny Notebook Example
  description: Rendered from a notebook.
---

If the preface cell has only page data, it is removed from the rendered notebook so readers do not see configuration. If the cell has a page preface followed by Markdown, the page preface is removed and the remaining Markdown still renders.

Common keys:

• title: page title and header text.
• nav: override or disable inherited navigation.
• footer: override or disable inherited footer.
• config: page-local generation controls; this key is not rendered.
• comments: page-level comments settings when comments are enabled.

Any other first-cell page preface key is treated like a normal Webifier section and is rendered after the notebook body.

Renderer controls should be grouped under config:

---
title: Training Curves
config:
  notebook:
    colab: true
    toc: true
  content_pages:
    toc: true

authors:
  kind: people
  content:
    - name: Grace Hopper
      role: Author
---

config.notebook is consumed by the notebook extension, config.content_pages is consumed by the standard content-page shell, and authors renders after the notebook body.

notebook_example:
  label: Notebook
  content: |
    Open the [tiny notebook](notebook=pages/user-guide/extensions/examples/tiny-notebook.ipynb).

Open the tiny notebook.

The tiny notebook linked above renders as a normal Webifier content page. It keeps the output of the notebook, gets the same code styling as Markdown pages, and can participate in page navigation and comments.

If Webifier is run with a repository name, notebook pages can include a Google Colab URL pointing to the source notebook in the repository. The standard bundled assets include a small Colab badge image for this workflow. Colab links are enabled by default for notebooks when --repo-full-name is available.

webify --repo-full-name owner/repo --baseurl /repo

Disable the badge for one notebook in the first Markdown cell:

---
title: Local-only Notebook
config:
  notebook:
    colab: false
---

Or set the site-wide notebook default on the extension instance:

config:
  webifier:
    extensions:
      notebook:
        uses: webifier.notebook
        colab: false
        toc: true

Notebook outputs are rendered from the saved notebook state. Webifier does not execute notebooks during the build by default. Commit the notebook with the outputs you want to publish.

Local output assets and local paths inside rendered HTML are copied into the generated site. Remote URLs are left remote. Rich HTML output is preserved, including tables and iframe output, but remote iframe embeds depend on the remote site allowing third-party embedding. For long-term reliability, prefer checked-in local assets or local HTML snapshots over fragile third-party iframe URLs.

The standard content page can build a collapsible table of contents from headings in notebook Markdown cells. Notebook content pages get this TOC by default when they have enough headings. That works best when notebooks use normal heading levels and do not also contain a hand-written table of contents cell.

Disable it for one notebook in the first Markdown cell:

---
title: Tiny Notebook
config:
  notebook:
    toc: false
---

Or use explicit content-page controls:

---
title: Tiny Notebook
config:
  notebook:
    toc: true
    cleanup: true
---

Recommended notebook cleanup before publishing:

• Put page data in the first Markdown cell as a YAML page preface.
• Remove duplicate manual title cells when the Webifier page title already names the page.
• Remove hand-written table-of-contents cells and let Webifier generate one.
• Keep headings separated from previous prose with a blank line in the notebook source.
• Commit outputs intentionally; Webifier publishes what is saved.

Notebook page configuration uses the same config contract as Markdown pages. Put this in the first Markdown cell:

---
title: Model Diagnostics
config:
  notebook:
    colab: false
    toc: true
  content_pages:
    toc: true
    cleanup: true

authors:
  kind: people
  content:
    - name: Katherine Johnson
      role: Author
comments:
  kind: comments
  label: false
---

The notebook extension consumes config.notebook, including notebook page controls such as colab, toc, and cleanup. The standard content-page shell still consumes config.content_pages as the lower-level shared content-page controls. The authors and comments blocks are rendered after the converted notebook output.

Site defaults and page overrides compose naturally:

# root site config
notebook:
  colab: true
  toc: true

---
title: Private Notebook
config:
  notebook:
    colab: false
---

Enable the extension:

config:
  webifier:
    extensions:
      site:
        uses: webifier.standard
      notebook:
        uses: webifier.notebook

Link notebooks from Markdown or YAML content:

[Rendered notebook](notebook=notebooks/example.ipynb)

Optional sibling page data:

notebooks/example/
  index.ipynb
  page.yml

Replace notebook behavior by registering a later content renderer for .ipynb or notebook with override: true. That is the right place to add project-specific execution, cell filtering, alternate exporters, or custom notebook templates.

config:
  webifier:
    extensions:
      notebook:
        uses: webifier.notebook
      lab_notebook:
        uses: my_lab.notebook
        override: true