quarto convert: treat headers as sepate cells

[anandology]

Description

The ipynb files generated from qmd file doesn't have section headers as separate markdown cells, making it a bit difficult to work with the editing the notebook. Semantically, that doesn't sound right.

Let me explain with an example.

An Example

Consider a qmd file with the following text.

# Chapter 1

Introduction to chapter.

## Section 1.1

Something about section 1.1.

```{python}
code block 1
```

some thing more about section 1.1.

## Section 1.2

Something about section 1.2.

The Current Behavior

The generated ipynb file has a structure similar to what is shown below.

type: md
lines:
- "# Chapter 1"
- ""
- "Introduction to chapter."
- ""
- "## Section 1.1"
- ""
- "Something about section 1.1."
- ""
---
type: code
lines:
- "code block 1"
---
type: md
lines:
- "some thing more about section 1.1."
- ""
- "## Section 1.2"
- ""
- "Something about section 1.2."

That is a Jupyter notebook with three cells. One markdown cell, one code cell and another markdown cell.

The Expected Behavior

I would prefer it be split like the following with each header getting its own markdown cell.

type: md
lines:
  - "# Chapter 1"
---
type: md
lines:
  - ""
  - "Introduction to chapter."
  - ""
---
type: md
lines:
  - "## Section 1.1"
---
type: md
lines:
  - ""
  - "Something about section 1.1."
  - ""
---
type: code
lines:
- "code block 1"
---
type: md
lines:
  - ""
  - "some thing more about section 1.1."
  - ""
---
type: md
lines:
  - "## Section 1.2"
---
type: md
lines:
  - ""
  - "Something about section 1.2."

Discussion

As a teacher sharing jupyter notebooks with my students, I care about these details. I ended up hacking a small python script to convert qmd files to ipynb and I think it should be too hard to make changes to quarto qmd parser to handle this.

Also, I fell this is semantically the right way to split a markdown text into cells.

Any thoughts?

[anandology]

It looks like the way a lua extension sees the AST of the qmd file is similar what I have describe above.

https://quarto.org/docs/extensions/lua.html#native-format

[cscheid]

We want quarto convert to be minimal and obvious (and it already isn't in ways that I don't like, such as removing empty code cells). Your suggestion makes sense for your workflow but is likely to cause bug reports/requests in the other direction. And because of the "minimal and obvious" goal, we're unlikely to add options to quarto convert to allow both behaviors.

I appreciate your articulation, but I think my conclusion here is that we won't implement this.

[askras]

Hi, @anandology

The Jupytext tool can enhance your workflow:

• GitHub
• PyPI
• Docs

This tool automatically converts the file you’re editing into the formats you need (e.g., .ipynb, .md, .qmd, .py, etc.) every time you save it.

If you add the following to your pyproject.toml:

[tool.jupytext]  
formats = "ipynb,md,qmd"  

it will generate .ipynb, .md, and .qmd files.

When editing and saving .ipynb or .md files, the cell structure information is preserved.
The .qmd file is generated automatically but does not retain cell structure information.

WARNING!!! If you edit and save the .qmd file directly, the .ipynb and .md files will be overwritten automatically, resulting in permanent loss of cell structure information.

A downside of this approach is the need to manage three identical files (.ipynb, .md, .qmd), which may be inconvenient.

P.S. You can also set up automatic file conversion through the JupyterLab menu: navigate to File → Jupytext → Pair Notebook with .