Cross-reference to custom cross-ref divs containing code-listing will cause misformed construction of listing if it contains an annotated code line

[Gewerd-Strauss]

I have:

• searched the issue tracker for similar issues
• installed the latest version of Quarto CLI
• formatted my issue following the Bug Reports guide

Bug description

When a custom reference type is set up to contain a code listing, and if that listing contains an annotated line, the listing output is malformed.

1. The codeblock itself is placed above the div's title-row; and the title-row is followed directly by the annotation-section.
2. Cross-refs will link to the div's title-row (correct).

---

Some additional observations not fully captured in compiled reprex:

• If an annotation line exists but no code-line is tagged for it, the cross-reference works correctly - but line-annotation fails. THe listings-block is assembled properly.
• If a code line is tagged, but its corresponding annotation does not exist, cross-reference fails (is replaced with ??), and the codeblock renders, but not as listing (and thus the listings caption is missing)
  (Note: I have not tested if this occurs in default listings as well, just noticed during this writeup)
• if both are configured 'correctly'; the issue as explained above occurs.

Further information can be found in the repository's README. .tex-intermediates are provided.

Steps to reproduce

Reprex, some additional details, and compiled outputs are found under https://github.com/Gewerd-Strauss/quarto-issue-cannot-crossref-to-custom-annotated-custom-listing

Actual behavior

Cross-referencing a custom cross-ref containing a validly-configured code-annotation results in the cross-referenced cell to be misorganised. The codeblock is placed above the listing caption line, the annotation is placed below the listing caption line. The hyperlink links to the caption line, below the codeblock and above the line annotations.

Expected behavior

Cross-referencing to a custom cross-ref containing an annotated code-block should not fail or misrender. The cross-reference should point to the start of the div, the codeblock itself should be placed properly, even if the layouting of the annotated block is modified.

Your environment

• Linux Mint 22.2 (Ubuntu 24.04 LTS)

• Vs Code version:

  gewerd-strauss@gewerdstrauss-B650E-AORUS-PRO-X-USB4:/mnt/data/Repositories/linux-only$ code --version
  1.127.0
  4fe60c8b1cdac1c4c174f2fb180d0d758272d713
  x64

Quarto check output

gewerd-strauss@gewerdstrauss-B650E-AORUS-PRO-X-USB4:/mnt/data/Repositories/linux-only$ quarto check
Quarto 1.10.14
[✓] Checking environment information...
      Quarto cache location: /home/gewerd-strauss/.cache/quarto
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.8.3: OK
      Dart Sass version 1.87.0: OK
      Deno version 2.7.14: OK
      Typst version 0.14.2: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.10.14
      Path: /opt/quarto/bin

[✓] Checking tools....................OK
      TinyTeX: v2026.04
      Chromium (deprecated): 869685
            (Run "quarto install chrome-headless-shell" to replace)
      Chrome Headless Shell: 150.0.7871.24
      VeraPDF: (not installed)

[✓] Checking LaTeX....................OK
      Using: TinyTex
      Path: /home/gewerd-strauss/.TinyTeX/bin/x86_64-linux
      Version: 2026

[✓] Checking Chrome Headless....................OK
      Using: Chrome Headless Shell installed by Quarto
      Path: /home/gewerd-strauss/.local/share/quarto/chrome-headless-shell/chrome-headless-shell-linux64/chrome-headless-shell
      Version: 150.0.7871.24

[✓] Checking basic markdown render....OK

[✓] Checking R installation...........OK
      Version: 4.6.1
      Path: /usr/lib/R
      LibPaths:
        - /home/gewerd-strauss/R/x86_64-pc-linux-gnu-library/4.6
        - /usr/local/lib/R/site-library
        - /usr/lib/R/site-library
        - /usr/lib/R/library
      knitr: 1.51
      rmarkdown: 2.31

[✓] Checking Knitr engine render......OK

[✓] Checking Python 3 installation....OK
      Version: 3.12.3
      Path: /usr/bin/python3
      Jupyter: 5.3.2
      Kernels: python3

[✓] Checking Jupyter engine render....OK

[✓] Checking Julia installation...
gewerd-strauss@gewerdstrauss-B650E-AORUS-PRO-X-USB4:/mnt/data/Repositories/linux-only$ 

(julia check does not print anything, not sure why)

[mcanouil]

Could you make your example simple? Not using all these custom LaTeX, etc.

I see you use Python code block, but use knitr inline syntax for options and at the same time mixing with YAML syntax.
Your example is quite heavy and from what you said, could fit in a very short example that could be shared alone as plain text here in this issue.

Concretely, lst is a special prefix as is fig, tbl, etc. In your example you are nesting several lst-.
You are mixing cross-ref syntax, nesting cross-refs, mixing engine syntax (R inline knitr), mixing code cells syntaxes, using keep-ipynb but you include an R cell which means knitr engine thus no Jupyter, the custom crossref is defined twice.

::: {#lst-code-faulty lst-cap-location="bottom"  lst-pos="H"}
```{python, label='lst-annotated-crossref4'}
#| lst-label: lst-test4

You said this works, but I wouldn't have bet anything on that in the first place.
All these mix of syntaxes are likely the issue.

[mcanouil]

I don't see obvious issue with a simple example not nesting three listing cross-ref labels.

---
format: pdf
crossref:
  custom:
    - kind: float
      key: mylst
      caption-location: bottom
      reference-prefix: Lst.
---

## default listing

::: {#lst-rcode}

```{.r}
x <- 1 # <1>
x
```

1. Assign a value to a variable `x` and print it.

R assignment and printing can be done using the following code

:::

## Custom listing

::: {#mylst-rcode2}

```{.r}
x <- 1 # <1>
x
```

1. Assign a value to a variable `x` and print it.

R assignment and printing can be done using the following code

:::

[mcanouil]

I believe the following is enough to show the link/structure issue:

---
format: pdf
keep-tex: true
crossref:
  custom:
    - kind: float
      key: mylst
      latex-env: mycodelisting
      caption-location: bottom
      reference-prefix: Lst.
      caption-prefix: Lst.
---

- @mylst-rcode

::: {#mylst-rcode}

```{.r}
x <- 1 # <1>
x
```

1. Assign a value to a variable `x` and print it.

R assignment and printing can be done using the following code

:::

This leads to an intermediate markdown that looks correct, but the produced LaTeX is not.
The code is in fact scaffold outside the cross-ref, thus why the link points to the annotation (which is inside the cross-ref.

\begin{document}


\begin{itemize}
\tightlist
\item
  Lst.~\ref{mylst-rcode}
\end{itemize}

\protect\phantomsection\label{annotated-cell-1}%
\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{x }\OtherTok{\textless{}{-}} \DecValTok{1} \hspace*{\fill}\NormalTok{\circled{1}}
\NormalTok{x}
\end{Highlighting}
\end{Shaded}

\begin{mycodelisting}

\centering{

\begin{description}
\tightlist
\item[\circled{1}]
Assign a value to a variable \texttt{x} and print it.
\end{description}

}

\caption{\label{mylst-rcode}R assignment and printing can be done using
the following code}

\end{mycodelisting}%




\end{document}

Note that this scaffolding issue is not specific to LaTeX, targeting HTML produces the same issue.

[Gewerd-Strauss]

I don't see obvious issue with a simple example not nesting three listing cross-ref labels.

I'm sorry for that; looking back this document was not properly constructed then. I have boiled it down using your suggested code, and have pushed changes to reprex.qmd. I can still recreate the issue on my end, in latex and HTML. Other outputs not tested.

---

Edit: Just refreshed after posting, you've found the same issue in the meantime. Nonetheless, I am sorry for the waste of your time.

[mcanouil]

Simple workaround to trigger the exemption rule in the Lua chain: reference-prefix: Listing.
More details on the issue in few minutes as there are several pieces at play here.

[mcanouil]

A custom crossref float (crossref.custom, kind: float) that wraps an annotated code block gets split on render: the code block is pulled out of the float, leaving only the annotation list and caption inside.
Happens in every format.

• After crossref numbering, a late filter lifts folded/annotated code blocks out of floats, so interactive code sits at document level rather than nested in a "figure".

  • quarto-cli/src/resources/filters/quarto-post/foldcode.lua

    Lines 75 to 89 in d678015

    	CodeBlock = function(block)
    	local folded_block, did_fold = render_folded_block(block)
    	local need_to_lift = did_fold or block.classes:includes("code-annotation-code")
    	if need_to_lift then
    	folded_block = _quarto.ast.make_scaffold(pandoc.Div, { folded_block } )
    	end
    	if block.classes:includes("code-annotation-code") then
    	prev_annotated_code_block_scaffold = folded_block
    	prev_annotated_code_block = block
    	else
    	prev_annotated_code_block_scaffold = nil
    	end
    	if need_to_lift then
    	blocks:insert(folded_block)
    	return {}

• That lift is skipped only for the built-in Listing category.
  A custom float's type is its reference-prefix (here Lst.), so it is not skipped, and its annotated code gets lifted out.

  • quarto-cli/src/resources/filters/quarto-post/foldcode.lua

    Lines 58 to 62 in d678015

    	FloatRefTarget = function(float, float_node)
    	-- we need to not lift code blocks from listing floats
    	if float.type == "Listing" then
    	return nil
    	end

• With a non-executable code block, the annotation list is a bare definition list, not wrapped in a cell-annotation div.
  The logic that drags the annotation along with the lifted code only matches cell-annotation divs, so the list is left orphaned inside the float while the code leaves.

  • quarto-cli/src/resources/filters/quarto-post/foldcode.lua

    Lines 94 to 112 in d678015

    	Div = function(div)
    	if not div.classes:includes("cell-annotation") then
    	return nil
    	end
    	local need_to_move_dl = false
    	_quarto.ast.walk(div, {
    	Span = function(span)
    	if (prev_annotated_code_block and
    	prev_annotated_code_block.identifier == span.attributes["data-code-cell"]) then
    	need_to_move_dl = true
    	end
    	end,
    	})
    	if need_to_move_dl then
    	assert(prev_annotated_code_block_scaffold)
    	prev_annotated_code_block_scaffold.content:insert(div)
    	return {}
    	end
    	end,

• An executable cell wraps its annotation in a cell-annotation div, so code + annotation move together and are not split.

  • quarto-cli/src/resources/filters/quarto-pre/code-annotation.lua

    Lines 544 to 554 in d678015

    	if codeAnnotations ~= constants.kCodeAnnotationStyleNone then
    	if pendingCodeCell ~= nil then
    	-- wrap the definition list in a cell
    	local dlDiv = pandoc.Div({dl}, pandoc.Attr("", {constants.kCellAnnotationClass, requireNonIncremental and constants.kNonIncremental or nil }))
    	if is_custom_node(pendingCodeCell) then
    	local custom = _quarto.ast.resolve_custom_data(pendingCodeCell) or pandoc.Div({}) -- won't happen but the Lua analyzer doesn't know it
    	custom.content:insert(2, dlDiv)
    	else
    	pendingCodeCell.content:insert(2, dlDiv)
    	end
    	flushPending()

  But they still land outside the custom float. Same root cause: the lift is not skipped for custom floats. Executable only avoids the orphaning, not the enclosure break.

[mcanouil]

So there are kind of two issues found here.

1. Only code inside a cross-ref div "Listing" stays within it.
2. Annotation does not stay together with code in all circumstances, i.e., non executable code.
   • Seems to be a more general issue where code-annotations do not always stick with the code it annotates: Shouldn't annotation list be scaffold with the code when `code-fold: true`? #14675