[FEATURE] NotebookEdit: support creating raw cells (cell_type: "raw")

Open 💬 0 comments Opened Jun 19, 2026 by bkowshik

Summary

NotebookEdit's cell_type parameter is an enum of ["code", "markdown"]. There is no way to create a raw cell, which is a first-class nbformat cell type and the one Quarto / Jupyter Book use to carry document front matter (YAML) inside an .ipynb.

Motivation

When authoring a Quarto site from notebooks, each notebook needs a leading raw cell holding --- … --- front matter (title, description, date, categories) so it lists and renders correctly. Today there is no in-tool way to produce that cell — you have to drop to a script or hand-edit the notebook JSON, which defeats the purpose of having a notebook-editing tool.

For accuracy: a markdown cell containing the same YAML also happens to render correctly in Quarto, because Pandoc parses a leading YAML block as document metadata. But raw is the documented, supported cell type for this, and it avoids the markdown cell rendering as a stray ---/text block in Jupyter, Colab, and GitHub's notebook viewers.

Current behavior

Calling NotebookEdit with cell_type: "raw" is rejected because "raw" is not a valid enum value. The only workaround is editing the .ipynb JSON outside the tool (e.g. a small Python script that inserts {"cell_type": "raw", "metadata": {}, "source": [...]} at the top of cells).

Proposed change

  • Add "raw" to the cell_type enum for both insert and replace.
  • Create raw cells with metadata: {} and list-form source (the latter also addresses the array-vs-string inconsistency reported in #49132).
  • (Optional, later) allow an optional raw_mimetype (e.g. text/html, text/latex) for non-front-matter raw cells. Not needed for the front-matter case, which uses empty metadata.

Why it's low-risk

It is an additive third enum value reusing the existing cell model; the common (front-matter) case needs no new fields, and there is no change to existing code / markdown behavior.

Related

  • #49132 — NotebookEdit writes source as a single string instead of a JSON array (a raw-cell implementation should emit list-form source for consistency).

View original on GitHub ↗