Rendering code cells containing labels in .ipynb output

[PhilChodrow]

Description

I am puzzled by some behavior I observe when rendering to .ipynb. Possibly related to #12242?

I am aiming to quarto render (ideally, not quarto convert) a .qmd file into an .ipynb while preserving runnable code blocks. However, this seems to break for cells containing cross-referenced labels.

I am running

quarto render test.qmd --no-execute

Contents of test.qmd:

---
format: ipynb
title: Test
wrap: none
---

I expect this .qmd when rendered to ipynb to contain two Markdown and two code cells.

```{python}
#| label: fig-test
print("This renders to part of a Markdown cell.")
```

But instead I got a single Markdown cell. @fig-test is not being rendered as a code cell.

```{python}
print("This renders to a code cell.")
```

Expected Result

I was expecting/hoping the resulting .ipynb to contain four cells: the first and third Markdown, the second and fourth executable code blocks.

# Test

I expect this .qmd when rendered to ipynb to contain three Markdown and two code cells.

print("This renders to part of a Markdown cell.")

Figure 1

But instead I got a single Markdown cell. <a href="#fig-test" class="quarto-xref">Figure 1</a> is not being rendered as a code cell.

print("This renders to a code cell.")

Observed Result

The resulting .ipynb contains two cells, the first Markdown and the second an executable code block.

# Test

I expect this .qmd when rendered to ipynb to contain three Markdown and two code cells.

``` python
print("This renders to part of a Markdown cell.")
```

Figure 1

But instead I got a single Markdown cell. <a href="#fig-test" class="quarto-xref">Figure 1</a> is not being rendered as a code cell.

Followed by code cell

print("This renders to a code cell.")

Quarto version 1.8.25 on MacOS 15.1.

Thank you!

[mcanouil]

What do you expect a cross-reference to do in this context?
You asked for a cross-reference, so you get one as with any formats.

What is exactly the use case behind?

[PhilChodrow]

Hmmmmm, if I understand the limitations of the fenced divs correctly, conditional content would involve a lot of code duplication, right? I don't follow the cross-div syntax suggestion as it relates to the use case I have here.

Since it seems like this is very difficult to either explain or adjust from a user perspective, I guess I'll just work without figure cross-references in my application.

Thanks again for your time!

[mcanouil]

I don't follow the cross-div syntax suggestion as it relates to the use case I have here.

It relates as it renders, but you won't get a code cells as with cross-reference, the code becomes content.
Here you want code to be code and content as the same time.

This raises a lot of question, should the code still be evaluated in ipynb context? What should be the cross-reference. You seem to expect a cross-reference to be a cross-reference in all formats, but to be a regular code cell in ipynb format, is that correct?

Note that you don't have to duplicate code, there are extensions such as 'div reuse' (https://github.com/mcanouil/quarto-div-reuse).

---

Notes:

• This behaviour (code-cell in cross-reference is considered as static content) seems intentional for performance reasons in the current implementation.

• The issue affects both .qmd and .ipynb files when code blocks are inside figure divs with cross-references.

• A proper fix would require architectural changes to the filter pipeline to preserve execution context through the cross-reference processing phase.

• https://github.com/quarto-dev/quarto-cli/blob/6c8a9b110fcde62f166b86077195bb43ce5d3034/src/resources/filters/quarto-pre/parsefiguredivs.lua

[mcanouil]

By the way, your code only works if --no-execute is used, as the cross-reference to ipynb format will lead to a crash.

[mcanouil]

I have a workaround, but using the div syntax and execution:

---
title: Demo
format: ipynb
filters:
  - restore-cells.lua
---

I expect this .qmd when rendered to ipynb to contain two Markdown and two code cells.

::: {#fig-test}

```{python}
print("This renders to part of a Markdown cell.")
```

:::

Inline label:

```{python}
# | label: fig-test2
print("This renders to part of a Markdown cell.")
```

But instead I got a single Markdown cell. @fig-test is not being rendered as a code cell.

```{python}
print("This renders to a code cell.")
```

• restore-cells.lua

--- @module "restore-cells"
--- @license MIT
--- @copyright 2026 Mickaël Canouil
--- @author Mickaël Canouil
--- @version 1.0.0
--- @brief Restore cell structure for CodeBlocks inside cross-reference divs
--- @description Extracts cell Divs from nested wrapper Divs and wraps bare CodeBlocks
--- so Pandoc's ipynb writer sees them correctly as code cells.

-- Only run for ipynb output
if not quarto.doc.is_format("ipynb") then
  return {}
end

--- Check if a CodeBlock should be wrapped in a cell
--- @param block table
--- @return boolean
local function is_unwrapped_cell_code(block)
  if block.t ~= "CodeBlock" then
    return false
  end
  return block.classes:includes("cell-code")
end

--- Wrap a CodeBlock in a cell Div
--- @param codeblock pandoc.CodeBlock
--- @return pandoc.Div
local function wrap_in_cell(codeblock)
  return pandoc.Div(
    pandoc.Blocks({ codeblock }),
    pandoc.Attr("", { "cell" }, {})
  )
end

--- Check if a Div is a cell
--- @param block table
--- @return boolean
local function is_cell_div(block)
  return block.t == "Div" and block.classes:includes("cell")
end

--- Process blocks recursively
--- @param blocks pandoc.Blocks
--- @return pandoc.Blocks
local function process_blocks(blocks)
  local result = pandoc.Blocks({})

  for _, block in ipairs(blocks) do
    if is_unwrapped_cell_code(block) then
      -- Bare CodeBlock with cell-code class - wrap it
      result:insert(wrap_in_cell(block))
    elseif block.t == "Div" and not is_cell_div(block) and block.content then
      -- Non-cell Div - process content recursively and check for nested cells to extract
      local processed = process_blocks(block.content)

      -- Separate cells from other content
      local cells = pandoc.Blocks({})
      local other = pandoc.Blocks({})

      for _, inner in ipairs(processed) do
        if is_cell_div(inner) then
          cells:insert(inner)
        else
          other:insert(inner)
        end
      end

      -- If we found cells, extract them
      if #cells > 0 then
        if #other > 0 then
          block.content = other
          result:insert(block)
        end
        for _, cell in ipairs(cells) do
          result:insert(cell)
        end
      else
        block.content = processed
        result:insert(block)
      end
    else
      result:insert(block)
    end
  end

  return result
end

-- Main filter
return {
  {
    Pandoc = function(doc)
      doc.blocks = process_blocks(doc.blocks)
      return doc
    end
  }
}

[PhilChodrow]

Amazing, thank you! Confirmed that this filter works for me with the div syntax, which is sufficient for my use case. The pointer to the design considerations is also very helpful.

Something I'll note explicitly for anyone who happens to be reading this in the future: using the syntax

```{python}
#| label: fig-test
print("Hello")
```

causes Quarto to attempt to create a div to contain the figure, which forces us into the design tradeoffs mentioned in the links by @mcanouil in the post below. This makes sense since it's just an alternative to the

::: {#fig-test}
print("Hello")
:::

syntax, which I only realized through this discussion.

Thanks again!

[mcanouil]

FYI, the Lua filter chain crashing is by itself a bug as it shouldn't at least not badly.

• Crash when using inline #| label: fig-* syntax with format: ipynb #13956

[mcanouil]

About https://github.com/orgs/quarto-dev/discussions/13905#discussioncomment-15608073, there are no guarantees of anything, nor "support" for it.
It can break in any future updates of Quarto, can crash for many reasons, etc.
Using it means you are responsible of fixing issues that might arise in your setup.

[PhilChodrow]

Hello, I was just wondering whether there was anything that can be said to explain this behavior. I'm happy to try to achieve my use case with a Lua filter (and have tried a bit), but I'm stuck and confused on how exactly the presence of the label + cross reference leads to the behavior shown, so I don't really know what the filter should try to modify.

[mcanouil]

For reference, as design choices relates to:

• https://github.com/orgs/quarto-dev/discussions/13502
• Code cell inside Callout should still be runnable code cell when output if format: ipynb #13510