Vignette figure cross-references render as literal \@ref() text on the pkgdown site

[NewGraphEnvironment]

Problem

Figure cross-references in the vignettes render as literal text on the published site. From
https://newgraphenvironment.github.io/flooded/articles/valley-confinement.html right now:

<p>Burn the stream network onto the DEM grid (Figure @ref(fig:plot-dem))
@ref(fig:plot-streams)). This is what the VCA bankfull regression
<p>...flat valley floor (Figure @ref(fig:plot-slope-mask)).</p>
<code>max_width = 2000</code>; Figure @ref(fig:plot-dist-mask)).</p>

A reader gets Figure @ref(fig:plot-dem) instead of Figure 1.

Scope

vignette	\@ref() in source	literal on live site
valley-confinement.Rmd	8 lines	8
stac-dem.Rmd	1 line (two refs)	2
pars-floodplain.Rmd	0	0

All three use bookdown::html_vignette2.

Cause

Bookdown's cross-reference machinery is not fully wired through html_vignette2 under pkgdown. It
is version- and context-dependent, not a typo in the vignettes: rendering
valley-confinement.Rmd locally with rmarkdown::render() resolves all eight refs, and the same
source deployed via the pkgdown workflow does not. So the local render is not a valid check for
this — the published page is.

Recorded as a known gotcha in the soul r-packages convention:

Gotcha — cross-references don't resolve in vignettes. Table \@ref(tab:foo) and
Figure \@ref(fig:foo) markers compile to a literal \@ref(...) in the rendered HTML rather
than a numbered link.

Options

1. Natural language + captions (what the convention recommends, and what the new "Whose
   floodplain is it?" section in valley-confinement.Rmd already does): "the floodplain map
   below", "the parameter table", and let fig.cap carry the identification. Cheapest, works
   everywhere, loses the numbers.
2. bookdown::html_document2 — real numbered cross-refs, but the output stops being a true
   package vignette. That is the cd-style report-appendix pattern, not a vignette pattern.
3. Leave as-is. Not really an option — the current output is visibly broken prose.

Recommend option 1 across all nine occurrences, since the newest vignette section is already
written that way and the mixture is what looks careless.

Acceptance

• No @ref( appears in the HTML of any published article page
• Every figure still carries a fig.cap so it is identifiable without a number
• Verified against the deployed site, not a local render — the two disagree here