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

[jjallaire]

Discussed in #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{....