Feature request: complain about \@ref() bookdown syntax

[Blake-Madden]

It would be nice if while compiling, Quarto could issue a warning about any \@ref(something) tokens. These are bookdown cross references, and need to be reformatted to @something to work in Quarto.

Currently, they are silently ignored and appear in the output as-is.

[cderv]

The next version of the quarto R package will have a function to help detect the reference and advice on what to do.

This is already available in the dev version on quarto-dev/quarto-r repo.

https://quarto-dev.github.io/quarto-r/reference/detect_bookdown_crossrefs.html

See an example with Bookdown book

Summary check mode

> quarto::detect_bookdown_crossrefs("04-customization.Rmd"))
ℹ Scanning for bookdown cross-references in file: 04-customization.Rmd.
! Found 5 bookdown cross-references that should be converted:

• 04-customization.Rmd: 5 references
- 5 Sec

ℹ Summary of conversion requirements:
• 5 Sec reference

ℹ Manual conversion requirements:
• Section headers: 5 references need manual attention

ℹ For detailed conversion guidance, run: quarto::detect_bookdown_crossrefs("04-customization.Rmd", verbose = TRUE)

> quarto::detect_bookdown_crossrefs("04-customization.Rmd")
ℹ Scanning for bookdown cross-references in file: 04-customization.Rmd.
! Found 5 bookdown cross-references that should be converted:

• 04-customization.Rmd: 5 references
- 5 Sec

ℹ Summary of conversion requirements:
• 5 Sec reference

ℹ Manual conversion requirements:
• Section headers: 5 references need manual attention

ℹ For detailed conversion guidance, run: quarto::detect_bookdown_crossrefs("04-customization.Rmd", verbose = TRUE)

Detailed mode

> quarto::detect_bookdown_crossrefs("04-customization.Rmd", verbose = TRUE)
ℹ Scanning for bookdown cross-references in file: 04-customization.Rmd.
! Found 5 bookdown cross-references that should be converted:


── File: 04-customization.Rmd ──

── Sec references: 
• Line 73 (04-customization.Rmd:73): `\@ref(collaboration)` -> `@sec-collaboration`
ℹ   Note: Also ensure the corresponding header has `{#sec-collaboration}`
• Line 111 (04-customization.Rmd:111): `\@ref(bootstrap-style)` -> `@sec-bootstrap-style`
ℹ   Note: Also ensure the corresponding header has `{#sec-bootstrap-style}`
• Line 193 (04-customization.Rmd:193): `\@ref(bootstrap-style)` -> `@sec-bootstrap-style`
ℹ   Note: Also ensure the corresponding header has `{#sec-bootstrap-style}`
• Line 198 (04-customization.Rmd:198): `\@ref(usage)` -> `@sec-usage`
ℹ   Note: Also ensure the corresponding header has `{#sec-usage}`
• Line 249 (04-customization.Rmd:249): `\@ref(configuration)` -> `@sec-configuration`
ℹ   Note: Also ensure the corresponding header has `{#sec-configuration}`

ℹ Summary of conversion requirements:
• 5 Sec reference
! Section reference detected - requires manual header updates:
Bookdown automatically generates IDs from headers like:
`# Hello World` -> auto-generated ID: `hello-world`
referenced with `\@ref(hello-world)`

Quarto requires explicit header IDs:
`# Hello World {#sec-hello-world}` -> explicit ID: `sec-hello-world `
referenced with `@sec-hello-world`

[cderv]

@cscheid I closed as I think this will serve purpose. However, if you still think adding a lint rule specific to this bookdown conversion is worth it, then please do re-open.