Figure out cross-references

[hadley]

From @jjallaire

(1) Inherit from bookdown::html_document2()

(2) Call the helper function I asked Yihui to put in so I could support cross-references in distill

(3) Look at the code of that function and just do it yourself (that might be the best bet although I haven't actually looked at the code recently so don't recall how trivial or non-trivial it is)

[maelle]

Does Hugo's cross-reference stuff help at all? https://gohugo.io/content-management/cross-references/

[hadley]

@maelle I don't think so, because we want RMarkdown cross-references.

[hadley]

Need this in hugo_document() setup:

  # Trick knitr into producing bookdown labels
  knitr$opts_knit$bookdown.internal.label <- TRUE

But is cross-linking worth it? Unlike bookdown, this only allows links within the current doc, which is primarily useful for floating figures, and the current syntax highlighting isn't designed for floating figures (since everything is wrapped in a <div>)

---

Test file:

---
output: hugo_document
---

```{r test, fig.cap = "This is a caption"}
plot(1:5, 1:5)
```

See Figure \@ref(fig:test).

[maelle]

Probably off-topic because too centered on Hugo/html (and on rOpenSci website knitr plot hook) and because I'm assuming linking to figures might be useful even if they're not floating. Is hugodown plot hook outputting html? If it were outputting a Hugo figure shortcode or even the same figure html as what Hugo shortcode would produce (which has the benefit of having separate title, caption and alt text), the title part of that html could be used as a Markdown link. In Hugo academic there's a custom figure shortcode that includes an id HugoBlox/hugo-blox-builder#1475

[hadley]

hugodown produces html; I can make it produce whatever is needed, but this part of the code is already quite hacky so I'd prefer to avoid adding to it unless there is an existing compelling use case (i.e. you can point me to blog posts where you already use this technique).

[maelle]

we use Hugo shortcode as a knitr plot hook (in some of the most recent posts, in the archetype https://github.com/ropensci/roweb2/blob/master/archetypes/Rmd/index.md -- called .md for use with Hugo/blogdown addin but it's Rmd), but not for the cross-reference aspect, it was because I couldn't think of another way to let post authors tweak image width/position, caption and alt text on a per chunk basis -- which minus the different caption/alt seems to already work with hugodown as is. So no compelling use case on the cross-reference aspect and I'll stop the off-topic commenting. 🙂

[apreshill]

Also chiming in even though no one asked, I do not find the cross-references across posts important and have never used them in 3 years of using Hugo via blogdown. What I do like and use is:

• figure numbering within a single post, and

• linking to specific figures/tables in text within the same post.

[danmackinlay]

FWIW I have a total of 3834 links between posts across the 735 pages of the site I manage (pace @apreshill ) and a total 54 links within a single post, so across two data points we have two different internal linking tendencies. Importance weighting these data points is left as an exercise 😉