fix #2032: keep figure captions when a chunk produces multiple figures

[yihui]

Problem

When a single chunk produces multiple captioned figures for Markdown-based output (HTML, or PDF via Pandoc), the captions are silently dropped.

Minimal example:

---
output: pdf_document
---

```{r fig.cap=caps, echo=FALSE}
caps <- c("caption one", "caption two")
plot(1:5)
plot(6:10)
```

The plot hook is called once per figure and the bare images end up in a single paragraph in the intermediate .md:

![caption one](test-1.pdf) ![caption two](test-2.pdf)

Pandoc treats several images in one paragraph as inline images, so it emits no figure environment / <figcaption> and the captions disappear. Reproduced for both pdf_document and html_document.

Fix

Insert a blank line after each captioned figure except the last, so Pandoc renders a separate figure (with caption) per image:

![caption one](test-1.pdf)

![caption two](test-2.pdf)

This is applied in the two bare-image producers, hook_plot_md_base() and hook_plot_md_pandoc(), via a small helper sep_captioned_fig(). The condition keys on caption presence and figure position (fig.cur < fig.num) — figures without a caption are left inline, and single-figure chunks and the last figure of a chunk are unchanged. The LaTeX hook (hook_plot_tex()) already wraps each plot in its own figure environment and is unaffected.

Relation to prior work

Supersedes the stale #1760 (thanks @atusy for the original diagnosis and PR). That PR gated on echo == FALSE || fig.show == 'hold', which missed cases like purrr::walk(list(g, g), print); keying on the caption instead handles those too. Also closes #1524. And also closes #1760.

Verification

• Confirmed with Pandoc that joined images produce no caption, and blank-line-separated images produce a figure per caption, for both LaTeX and HTML output.
• Verified end-to-end that pdf_document and html_document now keep per-figure captions (HTML went from 0 to N <figcaption>s).
• Added unit tests in test-hooks-md.R covering non-last / last / single / no-caption cases.
• Full testit suite passes.

🤖 Generated with Claude Code