Request: Allow adding arbitrary anchors to be linked with @ref

[anthony-wang]

My use case is that I generated thumbnails as previews for plot figures, and I'd like that these thumbnail images be cross-referenced with @ref or similar so that when clicked, we can jump to another section in the docs (e.g. to view the full-sized plot or the source code).

Currently, ![alt text](figure.png) inserts a figure and [Some-Header-Title](@ref) inserts a parsed cross-reference HTML link to the specified header anchor, and [text](URL) is a hyperlink, but I haven't been able to figure out a way to combine inserting the fig + a cross-referenced link. As far as I can tell, Documenter only allows @ref to headers.

Therefore, a way of specifying arbitrary anchors on any content so that we can @ref them elsewhere in the documentation would be nice!

A suggested design could be:
[content](@anchor anchor-name) in the markdown, which is then outputted with <a> tags with id's in the HTML. Then these anchors can be referenced by using @ref.

(thanks to @mortenpi for the suggested design!)

[ettersi]

+1 for this, but shouldn't the syntax be [content](@id anchor-name) to be consistent with the one for naming headers?

[mortenpi]

Yeah, re-using at-id makes sense to me. Currently, we're being extremely conservative about where we try to find at-ids (namely, only only within top-level headings), so generalizing it shouldn't be a problem.

I wonder how easy it is to introduce arbitrary anchors into LaTeX though. @odow, you don't happen to have any thoughts on this?

[ettersi]

I believe this should do the job?
https://www.overleaf.com/learn/latex/Hyperlinks#Inserting_links_manually

[odow]

We already use a mix of hyper refs:

Documenter.jl/src/Writers/LaTeXWriter.jl

Line 317 in 998d26e

_print(io, "\\hypertarget{", id, "}{\\texttt{")

Documenter.jl/src/Writers/LaTeXWriter.jl

Line 356 in 998d26e

_print(io, "\\item \\hyperlinkref{")

But yeah, some way of labeling and ref-ing to tables and figures would be useful.