In a Quarto Book project, how do I create a link from one chapter to another?

[lassehjorthmadsen]

Description

I'm having a hard time getting links from one chapter to another to work in a Quarto Book. Figure I must be making a simple mistake. Searched high and low and used a variety of chatbots. Minimal example, where I expect a link from Chapter 2 to Chapter 1 after rendering/previewing, but see none, only the literal "See @chap:one." text.

Tried with and without pandoc-args in _quarto.yml.

I'm on Windows 11, Quarto 1.7.30.

Thanks a lot for any input.

chapter1.qmd:

---
title: "Chapter 1"
format: html
---
# Chapter 1 {#chap:one}
Content. 

chapter2.qmd:

---
title: "Chapter 2"
format: html
---
# Chapter 2 {#chap:two}
See @chap:one.

_quarto.yml:

project:
  type: book
  output-dir: docs
book:
  title: "Test Book"
  author: "Test Author"
  date: "today"
  chapters:
    - index.qmd
    - chapter1.qmd
    - chapter2.qmd
format:
  html:
    theme: cosmo
    number-sections: false
    pandoc-args: ["--filter", "pandoc-crossref", "--no-citeproc"]
crossref:
  chapters: true

[cscheid]

We should have a warning about this, but: try using dashes rather than colons in your reference ids.

[mcanouil]

See the documentation about book cross-reference: https://quarto.org/docs/books/book-crossrefs.html

The search in the documentation is better than any chatbot available.

• sec is the keyword
• - is the separator
• an explicit ID is required

[mcanouil]

Side note, from where does your example come from? There are several options that clearly do not come from Quarto's documentation.

pandoc-args: ["--filter", "pandoc-crossref", "--no-citeproc"]

Even if pandoc-args would work in Quarto and passed on to Pandoc, it's undocumented in Quarto and in this case, bypassing Quarto does not feel like a great idea.

• You can disable citaproc with citeproc: false.
• Quarto handles cross-reference as described in the documentation and has fixes/changes from pandoc-crossref.
  Note that filters are to be passed on to filters.

  filters:
    - pandoc-crossref
  

My guess is that you used AI to get those options. If that is indeed the case, I would recommend to instead use the documentation and the search, which will give you better, faster, and more accurate answers than AI.

[lassehjorthmadsen]

Thanks a lot, @mcanouil and @cscheid. I got confused about the use of # and @ and also mixed up : and - separators. Sorry for the inconvenience. As for pandoc-args, it shouldn't have been in the example. It was indeed a result of AI hallucinations combined with me losing patience.