Better document internal links in Quarto authoring guide

[NickleDave]

Description

I want internal links in a blog post.

When I say "internal links", I mean as shown here:
https://github.com/holtzy/quarto-tricks/blob/main/internal-link/index.qmd

# Data wrangling {#section-2}

Let's do some data wrangling.

...

# Conclusion

Here is the link to the [section 2](#section-2) of the document!

Every time I need to remember how to do this, I go to the Quarto docs.
Inevitably I start here in "Markdown basics", where I would expect to find an example of internal links:
https://quarto.org/docs/authoring/markdown-basics.html#links-images
Eventually I make my way back to this section on cross-references:
https://quarto.org/docs/authoring/cross-references.html#sections
Which is the only example I find of using the {#...} syntax to reference a heading.
But it is immediately followed by a reminder to turn on section numbering--because this is showing how to use the {#sec-...} prefix--and of course that's not what I want for a blog post (unless it is a very academic blog post that I render in LaTeX or something 🙂 )

This most recent time, after making myself RTFM more, I was reminded that Quarto is using pandoc, so I should probably see how pandoc handles internal links. But the description there is at least as confusing since it doesn't mention the curly braces notation that I suspect I should be using.

Are internal links officially supported by Quarto?
Does Quarto use a different name for this?
I can't find any relevant issues, open or closed, makes me think that might be the case (of course maybe I just am not searching correctly).
Should I be looking somewhere else in the docs?

If this is supported, and Quarto would describe it as "internal links", I would request a little more documentation.
Thank you!

[mcanouil]

"Internal links" are just regular links. Quarto/Pandoc/browser will only assume that no files means current file.

Maybe more examples could be added to https://quarto.org/docs/authoring/markdown-basics.html#links-images
It is not possible and not the goal to duplicate all Pandoc's documentation into Quarto. That is why there are links to Pandoc's documentation.

See Pandoc documentation (link provided in the page above) which is more comprehensive about what Markdown syntax it supports: https://pandoc.org/MANUAL.html#links-1

But the description there is at least as confusing since it doesn't mention the curly braces notation that I suspect I should be using.

Curly braces are for attributes. Why do you want them? It's a regular link thus [text](URI){#id .class key=value}.

Note that for sections, Quarto supports referencing them as part of the cross-reference system: https://quarto.org/docs/authoring/cross-references.html#sections

{#...} is only setting an ID explicitly. It does not do referencing with links or cross-reference.
The cross-reference is using a prefix convention to do more advanced processing to make a link.

[mcanouil]

• docs(markdown-basics): add more links examples quarto-web#1842