quarto-dev / quarto-dev/quarto-cli
multi-line fig-cap in .qmd notebook still broken
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 6k
- Forks
- 458
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 41
Description
Bug description
First, I think this is the same issue as #6521. But it not only affects the rendering of .qmd files to .ipynb, but also the notebooks of manuscript projects. I hope it was ok to open a new issue, I did not know if a comment under the old one would have been enough or not.
When using the "manuscript" project, long fig-caps cause comically wide HTML previews. Trying to use a multi-line fig-cap does not work at all: It gets wrongly transformed and no figure output is displayed.
Steps to reproduce
First, the _quarto.yml file:
project:
type: manuscript
manuscript:
article: index.qmd
notebooks:
- notebook: figures.qmd
format:
html: default
Then the main manuscript index.qmd:
---
title: Manuscript
authors:
- name: Roman Ludwig
---
## Section
This is a simple placeholder for the manuscript's main document.
{{< embed figures.qmd#fig-some-lines >}}
The notebook figures.qmd, once with one long fig-cap line:
---
title: Plotting Figures
---
```{python}
#| label: fig-some-lines
#| fig-cap: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Donec ultrices tincidunt arcu non. Nulla aliquet porttitor lacus luctus accumsan tortor posuere ac. Dui accumsan sit amet nulla facilisi. Et tortor at risus viverra.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0., 1., 10)
data = np.random.uniform(size=10)
plt.plot(x, data)
plt.show()
```
And then lastly, the figures.qmd notebook with a multi-line fig-cap:
---
title: Plotting Figures
---
```{python}
#| label: fig-some-lines
#| fig-cap: >-
#| Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
#| incididunt ut labore et dolore magna aliqua. Donec ultrices tincidunt arcu non.
#| Nulla aliquet porttitor lacus luctus accumsan tortor posuere ac. Dui accumsan sit
#| amet nulla facilisi. Et tortor at risus viverra.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0., 1., 10)
data = np.random.uniform(size=10)
plt.plot(x, data)
plt.show()
```
Expected behavior
A single long line on a notebook's code cell should not cause the entire document to get rendered as wide as that cell, I guess?
But more importantly, multi-line fig-caps should work as one would expect YAML to work.
Actual behavior
In the first case, when using one long line in the fig-cap, the resulting notebook gets rendered way too wide:
While in the second case, it does not get rendered at all, because the figure caption is wrongly formatted (I presume):
Somehow it transforms the fig-cap: >- line to fig-cap: |- and inserts a blank line afterwards.
Note that in the main article, it looks fine when using the single long line, since there the code cell is not displayed.
Also, I looked at the code that was merged in #7893 and it seems that the YAML in the cell tags is correctly parsed. I.e., if I run nb_cell_yaml_options("python", cell) from here with the multi-line fig-cap, the returned dictionary contains a "fig-cap" key and its value has no newline characters \n in it.
I am not sure this helps, but I think the issue is not at the parsing step 😅
Your environment
- IDE: VS Code
- OS: Ubuntu 22.04 inside WSL2 on Widnows 11
I installed numpy, matplotlib, and jupyter to create this minimal plot.
Quarto check output
Quarto 1.5.30
[✓] Checking versions of quarto binary dependencies...
Pandoc version 3.1.13: OK
Dart Sass version 1.70.0: OK
Deno version 1.41.0: OK
Typst version 0.11.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
Version: 1.5.30
Path: /opt/quarto/bin
[✓] Checking tools....................OK
TinyTeX: v2024.04
Chromium: (not installed)
[✓] Checking LaTeX....................OK
Using: TinyTex
Path: /home/rmnldwg/.TinyTeX/bin/x86_64-linux
Version: 2024
[✓] Checking basic markdown render....OK
[✓] Checking Python 3 installation....OK
Version: 3.10.12
Path: /home/rmnldwg/repos/quarto-test/.venv/bin/python3
Jupyter: 5.7.2
Kernels: python3
[✓] Checking Jupyter engine render....OK
[✓] Checking R installation...........(None)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the manuscript project using the provided _quarto.yml, index.qmd, and figures.qmd examples, then inspect src/resources/jupyter/notebook.py around nb_cell_yaml_options and lines 689-706. Trace where the parsed fig-cap is transformed for notebook rendering. Done means multiline captions render as one caption and long captions no longer force an excessively wide HTML preview.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- jupyter, python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100