cap-location: margin doesn't play nicely with .column-page & .column-margin (PDF)

[sasja-san]

Bug description

I'm trying out the Tufte style features (PDF) with quarto but I can't get figure captions to work. Here's my output:

---
reference-location: margin
citation-location: document
tbl-cap-location: margin
cap-location: margin

pdf-engine: lualatex

format:
    pdf:
      papersize: a4
      geometry:
        - showframe # not for final release
        - left=15.0mm
        - textwidth=102.0mm
        - marginparsep=7.7mm
        - marginparwidth=70.3mm
---

And this is my qmd code:

![Hello from margin, please.](widea.jpg){#fig-widea}

@fig-widea is a nice one.

---

::: {.column-page #fig-widea-wider }

![](widea.jpg)

WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?!

:::

@fig-widea-wider is a bit wider.



---

for spacing...

---

::: {.column-margin #fig-wideb}

![](wideb.jpg)

Here's the caption text to the village picture. Here's the caption text to the village picture. Here's the caption text to the village picture. Here's the caption text to the village picture. 

:::

@fig-wideb looks like a nice place.

As you can see the caption text is there, but doesn't respect the image height (it seems to me).

In case it's not clear, these are the properties I expected:

• The caption text to Figure 2 should be in the margin, starting at the right underneath the image.
• The caption to Figure 3 should be underneath the image, all placed in the margin.

Quarto check output

Based on git commit d089957
Fri Jan 5 08:56:19 2024

Quarto 99.9.9
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.1.11: OK
      Dart Sass version 1.69.5: OK
      Deno version 1.37.2: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 99.9.9
      Path: /home/sasja/.quarto/quarto-cli/package/dist/bin

[✓] Checking tools....................OK
      TinyTeX: v2024.01
      Chromium: 869685

[✓] Checking LaTeX....................OK
      Using: TinyTex
      Path: /home/sasja/.TinyTeX/bin/x86_64-linux
      Version: 2023

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

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

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

[✓] Checking R installation...........OK
      Version: 4.3.2
      Path: /usr/lib64/R
      LibPaths:
        - /usr/lib/R/library
      knitr: 1.45
      rmarkdown: 2.25

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

But issue is also there on quarto-1.4.534 (Aug 4 2023)

[dragonstyle]

It is correct that these don't place nicely - for the time being, if you are placing items in the margin (either by extending them into the margin or placing them in the margin) you can't also place the caption for that item in the margin. You can manage this on a per figure basis like so:

---
reference-location: margin
citation-location: document
tbl-cap-location: margin
cap-location: margin
format:
    pdf:
      papersize: a4
      geometry:
        - showframe # not for final release
        - left=15.0mm
        - textwidth=102.0mm
        - marginparsep=7.7mm
        - marginparwidth=70.3mm
---


![Hello from margin, please.](fish.jpg){#fig-widea}

@fig-widea is a nice one.

---

::: {#fig-widea-wider .column-page  cap-location=bottom}

![](fish.jpg)

WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?! WHY DO YOU TREAT ME LIKE NOTHING!?!?!

:::

@fig-widea-wider is a bit wider.



---

for spacing...

---

::: {.column-margin #fig-wideb cap-location=bottom}

![](fish.jpg)

Here's the caption text to the village picture. Here's the caption text to the village picture. Here's the caption text to the village picture. Here's the caption text to the village picture. 

:::

@fig-wideb looks like a nice place.

• We definitely can improve the behavior of elements like figures being placed in the margin while also placing the caption in the margin (effectively ignoring the cap-location directive for those items).

• I'm slightly more skeptical that we should support page width elements with margin captions - I feel we should likely ignore the margin-caption directive for these cases as well.

[sasja-san]

Thank you for the quick reply.

Could what you wrote here be integrates into the documentation? For me (who is new to quarto but have been using pandoc for a long time) understanding syntax like this

 {.column-margin #fig-wideb cap-location=bottom}

is kinda tricky. Maybe it's covered somewhere in the docs why it's a . in one place, # in another and nothing in a third, but I couldn't find it.

It could also be helpful to mention the preferred way two write captions, as some of the ways really doen't work that well. (I saw a recommendation in another issue)

[sasja-san]

Sorry, didn't mean to close. I blame writing from my phone (and being generally ignorant).

[dragonstyle]

A challenge for us is that we're using a combination of identifiers , classes, and attributes (#, ., and <x>=<y> respectively) throughout Quarto, the hope being we choose each when it makes the most sense for the feature at hand.

• Definitely agree we could (for example), explain what each of these things are just to help oriented users to the syntax and how we generally use it and there terminology for it.

• I think this also points to a real need in terms of user education. We have pretty robust documentation, but it is organized pretty conceptually, so its best optimized to someone who is 'soaking' in Quarto and building a knowledge base over time by encountering a variety of different bits of documentation. We are still really missing documentation that is more task oriented (or perhaps recipe oriented) that can help users jump from a task and navigate deeper into the documentation (for example, recipes for positioning figures and captions that goes over common approaches and points you to deeper reading on figure layout or article layout).

I'm going to leave this open and flagged as a documentation issue. We're really continuing to make strides on that front and this is good consideration as more improvement... Feel free to weigh in if I haven't gotten the summary above right!

[sasja-san]

All the documentation/examples regarding this is about knitr and all these things. I'm not here for R. I'm here because wrangling pandoc with its extensions is a very annoying and time consuming task. Here are the things I looked at to try to figure this out:

1. Tufte Handout style Example
2. Guide >> Authoring >> Article Layout (not very helpful for this)
3. Guide >> Advanced >> Page Layout (looks cool but ignored because only has HTML)
4. Guide >> Authoring >> Article Layout

Especially 1 and 4 seemed useful. But the largest problem was that all the things I wanted were done within R blocks. So I was given some syntax to make it work, but not the right one. I did install R, knitr and RMarkdown in an attempt to make it work through some sort of include_image("path") or whetever it was called, but then told myself "This is way too stupid to be the correct way".

This example from 4 seems to do what I want, regarding layout:

```{r}
#| label: fig-mtcars
#| fig-cap: "MPG vs horsepower, colored by transmission."
#| column: margin

library(ggplot2)
mtcars2 <- mtcars
mtcars2$am <- factor(
  mtcars$am, labels = c('automatic', 'manual')
)
ggplot(mtcars2, aes(hp, mpg, color = am)) +
  geom_point() +
  geom_smooth(formula = y ~ x, method = "loess") +
  theme(legend.position = 'bottom')
```

but then I have the problem of having no clue as to how I should translate

#| label: fig-name
#| fig-cap: "Here's my text"
#| column: margin

into

{.column-margin #fig-name cap-location=bottom}

where the toughest part would be to take what seems to be a mere attribte (column: margin) and then using it as a higher order directive ({.column-margin ...})

Proposed solution

Include picture files as includes in what's at link 1 and 4, especially in 1.

While you're at it...

If someone edits these entries I would suggest adding some examples using listings (maybe in the margin? I saw something in the upcoming feature list). An example with a listing and a comment/code annotation to it in the margin would be greatly appreciated.

[dragonstyle]

Thank you for sharing the detailed write up - it is really helpful to actually see what you tried, what parts helped and didn't, and your approach. Thanks again for that!

There isn't really a systematic way to translate from code cell options to markdown representation - we basically try to use the best syntactic / intuitive approach for the markdown representation and promote commonly needed behaviors into code cell options. We try to provide examples of both pure markdown and computational cells with options whenever we can / when we think they're likely to be useful. We do some of this in the Article Layout documentation but you currently need to connect it to the figures documentation to complete picture.

So I think the articles 1 + 4 + https://quarto.org/docs/authoring/figures.html likely would/should have all the information you need, but it requires you to string together content across multiple indirectly connected pages to extract what you need.