General support for references to the name of a Section/Chapter/etc. rather than its number.

[jjallaire]

Discussed in https://github.com/quarto-dev/quarto-cli/discussions/1178

^{Originally posted by **fuhrmanator** June 18, 2022} In books it is very useful to refer to a section by its name. The Quarto documentation does this, e.g. the link to "Cross references" on this line: https://github.com/quarto-dev/quarto-web/blob/eed8baacea8448cd2ec60e34250ad2215de6831f/docs/authoring/figures.qmd#L25 But it's done with a hyperlink to an absolute HTML page. Another example is within a page: https://github.com/quarto-dev/quarto-web/blob/eed8baacea8448cd2ec60e34250ad2215de6831f/docs/authoring/cross-references.qmd#L26 There's an anchor generated through `## Options {#options}`. It seems to be HTML-specific. In LaTeX, it's done by `\nameref{sec-blahblah}` and I see that quarto supports this for PDF output. Are there plans to make this work with `@sec-blahblah` for other render destinations (e.g. html)? I'm thinking something like `[caption@sec-blahblah]` as a general solution.

[jjallaire]

We don't currently have a way to inject section names directly into references to them however we will definitely consider this for a future release! Note that the only difference I currently see in HTML and PDF output is the placement of the hyperlink. e.g. for this source code:

---
title: "section-names"
number-sections: true
---

## Quarto {#sec-quarto}

Quarto enables you to weave together content and executable code into a finished document. To learn more about Quarto see <https://quarto.org>.

See @sec-quarto.

HTML output looks like this:

and PDF output looks like this:

[fuhrmanator]

Thanks for the hint about an HTML and PDF solution.

[wklimowicz]

Not sure whether this is in scope, but would be great to have native quarto support for making the LaTeX reference become a hyperlink to the entire prefix, not just the number (so that the hyperlink is Figure 1, not just the 1). The easy workaround right now is just to use \autoref{fig-foo} rather than @fig-foo. I tried looking at a lua filter to do this but because of the way citeproc works this isn't trivial.

EDIT: With some playing around I've managed to get a workaround pandoc filter which replaces all instances of the citeproc citation with \autoref, so the whole word is highlighted.

-- Pandoc filter to replace citations with \autoref{}
function replace_citations(cite)
    local replace_envs = { "fig", "tbl" }
    if quarto.doc.is_format("latex") then
        for _, citation in ipairs(cite.citations) do
            local id = citation.id
            for _, prefix in ipairs(replace_envs) do
                if id and id:match("^" .. prefix .. "%-") then
                    return pandoc.RawInline("latex", "\\autoref{" .. id .. "}")
                end
            end
        end
    end
    return cite
end

return {
    Cite = replace_citations
}

EDIT2: This works for tables and figures, but doesn't work for equations (with \autoref they show up as section 1 rather than Equation 1). This is because quarto (or rather pandoc?) creates a \phantomsection around the equation, so this in quarto:

$$
y = mx + c
$$ {#eq-foo}

becomes this in LaTeX:

\begin{equation}\phantomsection\label{eq-foo}{
y = mx + c
}\end{equation}

Once again, easy workaround is just to use raw latex for now with \begin{equation} \label{....