Add figure notes option

[turbanisch]

In my field it seems customary to separate the title/short description of a figure from its notes (containing lengthy details), similar to

Is there any way to accomplish this with Rmarkdown/knitr or would it make sense to add a chunk option specifically for this purpose? Stack Overflow offers one solution for latex documents that works and surprisingly does not even result in ugly latex code.

However, the markup in the Rmarkdown file is verbose and other output formats won't accept the code. Many packages for producing tables have an option to provide both a title and notes, for example

modelsummary::modelsummary(mods, title = "...", notes = "...")

But I am not aware of a package that allows producing figures with captions that are not baked into the actual image file. So in my opinion, a chunk option for this purpose would be a welcome addition although I do not know how and whether this could be implemented and whether you like the idea at all. For latex specifically, I was thinking that perhaps the existing chunk option fig.scap could be used because I assume in most cases the short title of a figure would also be used in the list of figures (抛砖引玉而已). But I do not know of a way to have Latex print this short caption outside of the list of figures.

---

By filing an issue to this repo, I promise that

• [x] I have fully read the issue guide at https://yihui.org/issue/.
• [x] I have provided the necessary information about my issue.
  • If I'm asking a question, I have already asked it on Stack Overflow or RStudio Community, waited for at least 24 hours, and included a link to my question there.
  • If I'm filing a bug report, I have included a minimal, self-contained, and reproducible example, and have also included xfun::session_info('knitr'). I have upgraded all my packages to their latest versions (e.g., R, RStudio, and R packages), and also tried the development version: remotes::install_github('yihui/knitr').
  • If I have posted the same issue elsewhere, I have also mentioned it in this issue.
• [x] I have learned the Github Markdown syntax, and formatted my issue correctly.

I understand that my issue may be closed if I don't fulfill my promises.

[yihui]

That sounds like a reasonable feature request. I feel it shouldn't be too hard to implement for LaTeX output, but could be challenging when considering other output formats.

[linogaliana]

I had asked this question almost two years ago in stackoverflow because I needed that for pagedown. Maybe it sounded obvious for people having knowledge in HTML+CSS (I have very limited knowledge) but people proposed me to use a p tag for notes while using figcaption for the caption :

<figure>
  <figcaption>Wikipedia logo</figcaption>
  <img src="https://upload.wikimedia.org/wikipedia/commons/0/07/Wikipedia_logo_%28svg%29.svg">
  <p>Lorem ipsum dolor sit amet.</p>
</figure>

Hope this might help (indeed would be a very useful feature)

[linogaliana]

If it can help, I propose below snippets written by @rlesur, @JulietteS and I toimplement in HTML this functionality.

I think it had the inconvenient of breaking the automatic numbering of figures (@rlesur and @JulietteS : am I correct ?)

At R level, the main ingredient was a function caption_above

caption_above <- function(x, options, ...){

  notes <- ""
  if (!is.null(options$fig.subnotes)){
    notes <- sprintf("<figsubnotes>%s</figsubnotes>", options$fig.subnotes)
  }

  fignumber <- ""
  if (!is.null(options$fig.number)){
    fignumber <- sprintf("<fignumber>%s</fignumber>", options$fig.number)
  }

  paste(
    '<figure>',
    fignumber,
    '<figcaption>',
    options$fig.cap,
    '</figcaption><img src="',
    knitr::opts_knit$get('base.url'),
    paste(x, collapse = '.'),
    '">',
    notes,
    '</figure>',
    sep = '')

}

We were using a custom output format (overcharging pagedown::html_paged) where we were putting this line:

of$knitr$knit_hooks <- list(plot = caption_above)

Finally, I tried to recollect our different CSS elements to control the position of the note (colors were defined in our CSS as variables, you can of course get rid of these elements):

figure > figsubnotes {
  font-family: var(--title-font);
  font-size:7pt;
}

figure figcaption {
  font-family: var(--title-font);
  font-size:9pt;
  font-weight:bold;
}

figure figcaption {
  background-color: var(--theme-color-light);
  color: #333333;
  padding: 2pt 10pt;
  z-index: 1;
  text-indent: 5pt;
}

/* hack to avoid break before figure subnotes */
figure > figsubnotes::before {
    content: "";
    display: block;
    height: 70px;
    margin-top: -70px;
}

figure > figsubnotes {
  break-inside: avoid;
}

fignumber {
  background-color: var(--theme-color-dark);
  z-index: 2;
  padding: 1pt 5px;
  color: white;
  font-family: var(--body-font);
  font-weight: bold;
  position: relative;
  top: 8pt;
}

And finally we were using this as a chunk option in our Rmd:

```{r, fig.number="3", fig.cap = "Un titre pertinent", fig.height=3, fig.width=4.5, fig.subnotes ="Des notes de lecture éclairantes <br> et si on veut changer de ligne on peut. <br> *L'italique aussi est possible pour les sources.*"}

There's maybe easier paths to implement this feature for HTML output. I hope, at least, these snippets might help (once again this was a collective effort and most of the great ideas came from @rlesur and @JulietteS)

[turbanisch]

Thanks a lot for the suggestion! For me personally, the issue is more pressing in LaTeX/PDF output than in HTML because figures don't float in HTML. So even if I did not know how to make figure notes part of the figure itself, I could at least put them somewhere close to the figure and add some styling with CSS.

LaTeX, on the other hand, removes figures from the surrounding stream of text and puts them in an appropriate spot. So figure notes would have to be part of the figure environment to prevent them from being detached from the figure itself. Unfortunately, the figure environment is created by knitr itself and I can't think of a hack to insert figure notes.

The issue is of course even more complex because LaTeX itself (leaving R Markdown aside) by default does not even offer semantic markup for figure notes. I'd suggest adding such a field by defining a custom command somewhere in the preamble, e.g. with the floatrow package (which builds on the caption package):

\documentclass{article}

\usepackage{floatrow}
\newcommand{\figsourcenote}[1]{\floatfoot{#1}}

\begin{document}

\begin{figure}
  \centering
    \includegraphics[...]{...}
  \caption{...}
  \figsourcenote{\emph{Note:} ...}
\end{figure}

\end{document}

That way, the user could re-define the command \figsourcenote to his liking.

[eteitelbaum]

I want to endorse this idea as well. I saw this discussion in Stack Overflow on using custom hooks in a .Rnw file. Is there a way to implement this strategy (using custom hooks) in an .Rmd file?

[matthewgson]

I'd like to second this. Hope to see this feature implemented soon!

[scipima]

as i'm slowly moving my reports to quarto, would be great if the solution applied to .Rmd could also travel to the new .qmd format. and by the way, thanks for the great work!

[danielvartan]

I also second that. 🙋

[alceunascimento]

It will be great for scientific papers !! Waiting for it !

[yihui]

Okay, since the user interest appears to be strong, I'll look into this feature request before the next release. Thanks!

BTW, if you are a Quarto user, this has already been possible. See https://github.com/quarto-dev/quarto-cli/discussions/6103#discussioncomment-7296412 for an example, but it's not clear whether Quarto wants to offer an official way to style the figure notes: https://github.com/quarto-dev/quarto-cli/issues/7514