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

[Gewerd-Strauss]

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

[cderv]

See [text @sec-first]

I believe this syntax is documented there in the Basics about referencing: https://quarto.org/docs/authoring/cross-references.html#references

Currently, Text is valid syntax across pdf/html/docx

This is because it is not a cross-reference feature from Quarto. it is inherit from Pandoc header attributes feature.

Using this syntax, you won't get any numbering of the section. It is different syntax, for a different yet similar feature which allow to link to another element with an id.

If anything, looking at the different options I would much rather expect the Text to be the intended one, by proxy of being consistent with other cross-ref syntax, and would expect Text to fail

The hard part here is that [Text](#sec-first) is a valid Pandoc's Markdown syntax that we would not want to break.

I recognized this may be confusing, as we do not even document the syntax as part of basic markdown syntax. We only do links to external url and also using images. No example on internal content link (https://quarto.org/docs/authoring/markdown-basics.html#links-images)

[Text](@sec-first) could be a new variant to add as another way to link while replacing the whole link text (no number and no text). 🤔 Usually though, when cross reference is desired, numbering is important.

[Gewerd-Strauss]

I believe this syntax is documented there in the Basics about referencing

Welp... Evidently I did not find that - or it was so long ago that I unfortunately forgot. I guess my primary issue on that page is more my own - I would go Quarto.org/guide>Authoring>Scholarly Writing>Cross-References>Basics, skim the ToC, and jump to Sections - and thus I will miss the overview under References. To my brain, it would make sense to document the different methods for cross-referencing a section under Sections - but after another full read I understand why that idea might not be that good.

---

Thank you for the explanation, that clears it up a lot on my end.
I'll excuse myself for the hassle arising from my confusin here.

Thank you for this tool, btw. It's an integral part of my workflow for basically anything written, nowadays.

On my end this issue can be closed then.

[cderv]

Thanks @Gewerd-Strauss !

@cwickham What do you think of this doc feedback ? I let you decide if you want to keep this one around as an opportunity to rethink the organization of this doc https://quarto.org/docs/authoring/cross-references.html#references Maybe we need a more explicit title for the section about syntax for references that applies to all (include sections references)