How can I customize cross-reference in a quarto book?

[karaesmen]

Description

I know that I can refer to different sections with @sec-my-section but from what I understand, user can only refer to these with chapter numbers and customize the prefix e.g. Chapter 1 vs just 1 etc.

Is there another option if I would like to refer to a chapter with its title or any other string but let's me hyperlink to the chapter? For example:

For more details please check out [My Section About Peanuts](@sec-peanuts).

[jdutant]

This should work (it's a link, # in the target indicates an identifier).

for more details please check out [My Section About Peanuts](#sec-peanuts).

You need to explicitly add the identifier {#sec-peanuts} at the end of your chapter's heading line:

# All About Peanuts {#sec-peanuts}

[mcanouil]

By default headers are transformed implicit as ids: # All About Peanuts will have all-about-peanuts as id that you could use as simple links.
If you don't like the default implicit ids, you can as demonstrated above, use the brackets to define it yourself.

[jdutant]

Explicit ids with sec- appear necessary though to use both @ cross-references (to get automatic labels, "Chapter 1") and the occasional custom link reference ("as said in a previous chapter"). At least that's what a few quick tests on Quarto 1.3 suggest: @summary and/or @sec-summary don't link to the bare header "# Summary".

[mcanouil]

sec- prefix is indeed necessary as it is an important part of the cross-reference system.
Cross-references are not simply links, they are more. What you initially asked was to simply make a link in this case the prefix is not necessary.
So if you need to do both, then yes the prefix is required.

Note that this is documented: https://quarto.org/docs/books/book-crossrefs.html#creating-references.

Quarto document	HTML
--- title: "Quarto Playground" format: html --- This is a playground for Quarto. ## Summary {#sec-summary} {{< lipsum 1 >}} ## Introduction {{< lipsum 1 >}} I wrote something amazing in @sec-summary. [My amazing section -@sec-summary]. A link to [my amazing summary](#sec-summary). Lipsum shortcode is from https://github.com/dragonstyle/lipsum.

[ntluong95]

I have a bookdown project in R which has been rendered successfully. In the book, most of the time I am using conventional hyper link to refer to chapter. For example

In chapter pivoting.Rmd, the title is below without specifying the chapter label (inside the curl bracket

# Pivoting data {}

Then in chapter cleaning.Rmd, I cross reference the pivoting chapter using conventional hyperlink (without specifying the label)

Read more in the chapter [Pivoting data]

However, when I port the project to Quarto book, I have to change all .Rmd files to .qmd files, and those chapter links were broken. They are displayed as normal text. I read the Quarto document, if I want to use the conventional hyperlink, either the chapter should have label or specifying the source file like this:

[about](about.qmd)
[about](about.qmd#section)

My wish is to find the way addressing the problem systematically, because I couldn't add label to chapter and then find hyperlinks to add them manually in order to proper displayed.