Error with fig-pos and Single Images in Divs

[BradyAJohnston]

Bug description

When setting the fig-env or fig-pos in the _quarto.yml, there is a peculiar bug where it errors if you include single images inside of custom divs. I will show some tests which reproduce the error from the default book project in VSCode when using "New Project --> Book".

I have started doing all of my figures inside of their own divs. This makes writing much longer figure captions much easier, and spellcheck actually looks at them inside of VSCode rather than when they are inside of the [] of a regular markdown image.

The below project renders OK, including a number of subfigures.

Renders OK

project:
  type: book

book:
  title: "testing"
  author: "Norah Jones"
  date: "23/05/2023"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

bibliography: references.bib

format:
  pdf:
    documentclass: scrreprt
    fig-pos: bp

# Introduction

This is a book created from markdown and executable code.

See @knuth84 for additional discussion of literate programming.


::: {#fig-test layout-ncol="2"}

![](cover.png){#fig-logo1}

![](cover.png){#fig-logo2}

Some logos.
:::

Doesn't Render

If I leave the YAML the same but change it to just a single figure inside of the div then this fails to render:

# Introduction

This is a book created from markdown and executable code.

See @knuth84 for additional discussion of literate programming.


::: {#fig-test}

![](cover.png)


Some logos.
:::

compilation failed- error
LaTeX Error: Not in outer par mode.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.215 \begin{figure}[bp]

The actual .tex lines that are problematic look like this, and from what I can find googling around it doesn't like setting a floating environment inside an already floating environment.

\begin{figure}

{\centering 

\begin{figure}[bp]

{\centering \includegraphics{cover.png}

}

\end{figure}

}

I have a solution that works if I set it up as follows:

::: {#fig-test layout-ncol="1"}

![](cover.png)

Some logos.
:::

I found that it was mentioned in the docs about setting environments inside of divs can be unstable in latex. I propose that that the global fig-env or fig-pos might instead affect the div figure rather than what is contained within?

I figure that this might also be a bit of an esoteric use, but I the ability to better write longer captions I think is crucial as opposed to the ![]() markdown syntax, so potentially even a different way to include images in the div.

System specs:

I have tested on both my windows 11 and MacOS 13.2 machines.

Quarto Check:

quarto check

[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.1.1: OK
      Dart Sass version 1.55.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.3.353
      Path: /Applications/quarto/bin

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

[✓] Checking Python 3 installation....OK
      Version: 3.10.11 (Conda)
      Path: /usr/local/Caskroom/miniconda/base/envs/mn-test/bin/python
      Jupyter: (None)

      Jupyter is not available in this Python installation.
      Install with conda install jupyter

[✓] Checking R installation...........OK
      Version: 4.2.1
      Path: /Library/Frameworks/R.framework/Resources
      LibPaths:
        - /Users/brady/git/phd/thesis/renv/library/R-4.2/x86_64-apple-darwin17.0
        - /Library/Frameworks/R.framework/Versions/4.2/Resources/library
      knitr: 1.39
      rmarkdown: 2.14

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

Checklist

• Please include a minimal, fully reproducible example in a single .qmd file? Please provide the whole file rather than the snippet you believe is causing the issue.
• Please format your issue so it is easier for us to read the bug report.
• Please document the RStudio IDE version you're running (if applicable), by providing the value displayed in the "About RStudio" main menu dialog?
• Please document the operating system you're running. If on Linux, please provide the specific distribution.
• Please provide the output of quarto check so we know which version of quarto and its dependencies you're running.

[cscheid]

I found that it was mentioned in the docs about setting environments inside of divs can be unstable in latex. I propose that that the global fig-env or fig-pos might instead affect the div figure rather than what is contained within?

That's tricky in general. I agree that we're failing here, but the problem lies with pinning down precisely what's "the div figure" vs. what is "what is contained within". Since we allow quite general content in either, that's generally hard.

the ability to better write longer captions I think is crucial as opposed to the ![]() markdown syntax, so potentially even a different way to include images in the div.

You'll still need the ![]() markdown syntax to include the actual image, so what do you prefer about having the caption in a subsequent paragraph?

[BradyAJohnston]

The captions I am writing at the moment are all for my PhD thesis and so each figure caption is usually very long. I find it better for git tracking and if I am editing the document in the source view to have the caption across several lines which is possible with the divs, in comparison to putting the caption inside of the markdown ![]() which all has to be on a single line and can get a bit messy and hard to read and write in the source view when work on longer captions.

Previously as well the spellcheck inside of RStudio wasn't working on the captions when they were inside of the markdown syntax but did work when it was in the div. I'm now using VSCode and it seems to work well regardless, so this isn't as much of an issue any more.

I suppose it just ends up being nicer to work with when the captions are really long. Certainly not an important feature request though, and my current workaround of layout-ncol="1" is serving me well at the moment.

[mcanouil]

I don't understand your issue with long caption and ![](){} notation.

putting the caption inside of the markdown ![]() which all has to be on a single line

Where does this come from? Quarto documentation? Pandoc?
I believe this to be a common preconception coming from the "inline" notation.

See Quarto document code.

---
title: "Quarto Playground"
format: html
---

This is a playground for Quarto.

![
  An Elephant
  with a caption
  on multiline.  
  A second line.
](
  https://images.unsplash.com/photo-1557050543-4d5f4e07ef46?ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D&auto=format&fit=crop&w=3132&q=80
){
  #fig-elephant
}

I can still reference the elephant image using the `fig-elephant` label with @fig-elephant.

And no issues there when rendering to PDF.

[BradyAJohnston]

@mcanouil that's a handly little trick, I didn't realise that the markdown ![]() could be split across multiple lines.

Currently though it seems that if you then edit in visual mode, Quarto converts it all to a single line and you lose the multi-line editing and tracking.

This code below renders to PDF.

# Introduction

This is a book created from markdown and executable code.

See @knuth84 for additional discussion of literate programming.


![
    A multi-line caption.
    With the next line here. 
    And and now another line.
](
    cover.png
){
    #fig-logo
}

If however you edit in visual mode, then switch back to source mode, the .qmd has changed to this:

# Introduction

This is a book created from markdown and executable code.

See @knuth84 for additional discussion of literate programming.

![A multi-line caption. With the next line here. And and now another line.](cover.png){#fig-logo}

This brings me back to the same issue.

[mcanouil]

I don't believe in visual editor for markdown users.
Visual editor has to make choices as it can't possibly cover all syntaxes or ways to read/write things.

VSCode provides keyboards shortcuts to bold/italicise/etc. markdown, thus what's the benefits of visual editor when you are most likely previewing the result live just next to the code?

Note that the fig-env issue does feel as an actual bug a typo while visual editor issue is in fact not really a bug but a choice to make.
If you want markdown flexibility, visual editor is not the tool and likely never will be.

[BradyAJohnston]

Updated previous comment to remove my mistaken fig-env / fig-pos mix up.

[mcanouil]

I don't believe in visual editor for markdown users. Visual editor has to make choices as it can't possibly cover all syntaxes or ways to read/write things.

Just to be clear, this was only my personal opinion as an "advanced" markdown user with the current state of the visual editor.
I do believe that the visual editor is a great (and needed) step towards, for example, live editing of Quarto documents for a large user base (not necessarily familiar with markdown). Also, in time the visual editor (as in RStudio IDE or Quarto VSCode extension) will improve and possibly will keep unedited markups as is when switching between visual and source mode.

[cscheid]

(Revisiting this.)

In the current pre-releases, the following example works:

---
title: Hello
keep-tex: true
format:
  pdf:
    documentclass: scrreprt
    fig-pos: bp
---

## Introduction

This is a book created from markdown and executable code.

See @knuth84 for additional discussion of literate programming.


::: {#fig-test layout-ncol="2"}

![Left](surus.jpg)

![Right](surus.jpg)

Some logos.
:::

Note that this isn't exactly the same as what you've written. Specifically, subfigures require a caption in order for them to appear inside a figure div with layout-ncol layout. I hope to be able to improve this so that plain image inclusion works, but it might not be possible.

What we'll certainly do by the 1.4 release is to issue a warning in case we find images that won't work inside layout-ncol layouts.

[cscheid]

Tagging #4944 here for our own reference.