quarto-dev / quarto-dev/quarto-cli

Cross reference divs in includes do not render correctly in manuscript projects

Open
#13,974 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug manuscript
Dominant language
JavaScript
Stars
6k
Forks
458
Avg merge
1d 9h
Merged PRs (30d)
41

Description

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

In a manuscript project consisting of multiple files that are included in index.qmd, floats (figures, tables) in cross-reference divs are not rendered correctly. The content of the floats themselves are rendered, but not labeled and the caption seems to be included as body text.

If I render the project to HTML, Quarto crashes, but this seems to be a known bug in manuscript projects. Therefore, the examples below will only render to PDF.

Steps to reproduce

1. Create files

_quarto.yml:

project:
  type: manuscript
  output-dir: _manuscript

output-file: manuscript.pdf

execute: 
  echo: false

manuscript:
  article: index.qmd

format:
  # (other formats)
  pdf: default

index.qmd:

---
title: include-div-mwe
---

## Section
This is a simple placeholder for the manuscript's main document [@knuth84].
This is a figure defined in `index.qmd`: @fig-in-index

::: {#fig-in-index}

```{python}
import matplotlib.pyplot as plt

plt.plot(range(10))
```

A plot in a div float in `index.qmd`

:::

This is a figure defined in `include.qmd`: @fig-in-include

{{< include include.qmd >}}

include.qmd:

::: {#fig-in-include}

```{python}
import matplotlib.pyplot as plt

plt.plot(range(9, -1, -1))
```

A plot in a div float in `include.qmd`

:::

2. Render

quarto render

3. Control experiment: add configuration for default project type

_quarto-default.yml:

project:
  type: default
  render: 
    - index.qmd
  output-dir: _default

output-file: default.pdf

execute: 
  echo: false

format:
  pdf: default

4. Render as default project

quarto render --profile default

Here is a zip of my example, which you can run using Python (optionally through uv):

include-div-mwe.zip

Actual behavior

When rendering the manuscript project:

See manuscript.pdf. Both plots are included in the document. Both captions are not prefixed with the figure label. The label of Figure 1 is located at the end of the document and correctly cross-referenced. The label of Figure 2 is not rendered and cannot be referenced.
The output of quarto render shows a warning:

WARNING (C:/Users/chaasjes/Downloads/include-div-mwe/.venv/Lib/site-packages/quarto_cli/share/filters/main.lua:22344) FloatRefTarget with no content: fig-in-include

When rendering the default project:

See default.pdf. Both plots are included with correctly labeled and cross-referenced captions. There are no warnings or errors in the output.

Other interesting details:

The same behavior is seen when an image is used instead of an executable code block.
If multiple images are included, with different figure labels, the manuscript project puts the separate images in subfigures.

manuscript.pdf
default.pdf

Expected behavior

Regardless of the project type, the output PDF file contains two figures with captions labeled as Figure 1 and Figure 2, and cross references in the text are rendered correctly. In other words, the output should be the same for the manuscript and default projects.

Your environment
  • IDE: VSCode 1.108.2
  • OS: Windows 11
Quarto check output
Quarto 1.8.27
[>] Checking environment information...
      Quarto cache location: [REDACTED]\AppData\Local\quarto
[>] Checking versions of quarto binary dependencies...
      Pandoc version 3.6.3: OK
      Dart Sass version 1.87.0: OK
      Deno version 2.3.1: OK
      Typst version 0.13.0: OK
[>] Checking versions of quarto dependencies......OK
[>] Checking Quarto installation......OK
      Version: 1.8.27
      Path: [REDACTED]\.venv\Lib\site-packages\quarto_cli\bin
      CodePage: 1252

[>] Checking tools....................OK
      TinyTeX: v2025.07
      Chromium: (not installed)

[>] Checking LaTeX....................OK
      Using: TinyTex
      Path: [REDACTED]\AppData\Roaming\TinyTeX\bin\windows\
      Version: 2025

[>] Checking Chrome Headless....................OK
      Using: Chrome found on system
      Path: C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
      Source: Windows Registry

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

[>] Checking Python 3 installation....OK
      Version: 3.13.1
      Path: [REDACTED]/.venv/Scripts/python.exe
      Jupyter: 5.9.1
      Kernels: python3

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

[>] Checking R installation...........(None)

      Unable to locate an installed version of R.
      Install R from https://cloud.r-project.org/

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the issue with _quarto.yml, index.qmd, include.qmd, and the default profile, then compare the PDF outputs from quarto render and quarto render --profile default. Start with the manuscript rendering path and the FloatRefTarget warning at main.lua:22344; done means included figures have labeled captions and working cross-references in the manuscript project.

Written by the indexing model from the issue text.

Assessment

Tech stack
latex, python, vscode
Domain
backend, cli
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.