Website: The documentation on section-cross-references lacks some implicitly possible options

What would you like to do?

Give feedback or suggest an improvement

Description

The documentation on section-cross-references gives the following example for linking to a section:

## Introduction {#sec-introduction}

See @sec-introduction for additional context.

The following two options, however, are not shown anywhere:

---
title: "Quarto Playground"
format: html
number-sections: true
---

## First Section {#sec-first}

This is a playground for Quarto.

{{< lipsum 1 >}}

## Second Section

See [text @sec-first]

or

See [Text](#sec-first)

<!--See [Text](@sec-first) (why does this not work?)-->

<!--See @sec-first (this one is documented already)-->

While these can be implicitly assumed due to how the crossref-system for figures/tables/... work, they lack documentation. I use this syntax every so often, and most of the time I have to sift through old documents trying to find this particular syntax, since the docs don't mention it explicitly.

Additionally, personally I think that there lacks some documentation on which type of prefix-symbol allows for which type of markdown-link. Currently, [Text](#sec-first) is valid syntax across pdf/html/docx. Given that basically all other cross-refs use the @-symbol instead, one might think that [Text](@sec-first) would be valid as well. However, this fails to convert properly into pdf,docx or html.

If anything, looking at the different options I would much rather expect the [Text](@sec-first) to be the intended one, by proxy of being consistent with other cross-ref syntax, and would expect [Text](#sec-first) to fail by proxy of not being documented to begin with. (While both of these are not documented, only the "consistent" one breaks while the "odd" one actually works.)^1

[^1]: I am aware that [Text](#sec-first) is the common markdown link implementation and should therefore still work. By "odd" I am refering to the internal inconsistency in quarto. Just going from syntax-consistency, this makes no sense to me.

Thank you.
Sincerely,
~Gw