Links to chapters in Books - what am I missing?

[ijmitch]

Description

I have a book project from which I'm rendering the PDF.

A Markdown link to a chapter file works fine in HTML, but in the PDF the link's value seems to be the .md file's name. In the PDF, links to heading within the same file work fine as do links to completely external assets.

Making the first level one heading into a Cross Reference target doesn't make the link render properly either.

I've reproduced this using the Book project boilerplate. I added the following to the index.qmd:

Does a [link to the summary](summary.qmd) work?

or only @sec-summary ?

In HTML both these links work - albeit that @sec-summary is turned into Chapter 2.

But in the PDF the first link is a link which doesn't work, and 'Chapter 2` is just normal text.

How should I be getting links from text to chapters to work in the PDF of a book?

[mcanouil]

Could you share a small self-contained "working" (reproducible) example to work with, i.e., a complete Quarto document or a Git repository? Thanks.

You can share a Quarto document using the following syntax, i.e., using more backticks than you have in your document (usually four ````).

````qmd
---
title: "Reproducible Quarto Document"
format: html
---

This is a reproducible Quarto document using `format: html`.
It is written in Markdown and contains embedded R code.
When you run the code, it will produce a plot.

```{r}
plot(cars)
```

![A placeholder image](https://placehold.co/600x400.png)

The end.
````

[ijmitch]

See https://github.com/ijmitch/linktest

[ijmitch]

Although now I see that the '2' of 'Chapter 2' is actually a link - that's a bit hard to see.

Whereas in HTML 'Chapter 2' is the link - so it's more obvious, but still not descriptive of the target's content.

[mcanouil]

Use [Chapter @sec-summary] where "chapter" can be whatever you want (see https://quarto.org/docs/books/book-crossrefs.html#creating-references).

Note that this is default LaTeX behaviour.
To circumvent this (if it's possible) you'll have to search on LaTeX more dedicated places.

---
title: "Quarto Playground"
format: pdf
number-sections: true
---

This is a playground for Quarto.


# Introduction {#sec-intro}

This is a test of the Quarto system.  It is a test of the system.

# Methods

This is a test of the system.

See @sec-intro.

# Results

This is a test of the system.

[ijmitch]

Using [Summary @sec-summary] in my test book (now in the test repo) isn't really what I'm looking for.

• it means a different form of link between what works in the html rendering of a book project and the pdf format
• the "chapter" or equivalent has the numeral appended to it in both html and pdf form so making that something topic/title related makes no sense. And the pdf form, the 'chapter' word isn't part of the link, only the numeral ('2' in the test case) is a link.

[mcanouil]

That's LaTeX default behaviour.
You can find your own LaTeX workaround using other LaTeX packages but it's unlikely the whole LaTeX template inside Quarto/Pandoc will be modified that much to counter what LaTeX does.

[cderv]

In HTML you will have indeed both Prefix and number as a link when using @sec- cross ref

In PDF we do create this type of LaTeX content: Section~\ref{sec-intro} and LaTeX will only highlight the \ref part.

Not sure which is the LaTeX way to provide a prefix to highlight too. I believe this syntax with only number as link is quite common in LaTeX.

If you do have a LaTeX syntax to share, please do.

Changing this could be possible but this is a feature request, and styling change are always quite complex to make because there is no better choice between one or the other usually.

[ijmitch]

ok, thanks - I have to admit that I'd interpreted the 'and therefore support' as additional rather than instead of:

HTML books are actually just a special type of Quarto Website and consequently support all of the same features as websites including full-text search. The most important difference is that HTML books use chapter numbers and therefore support Cross References between different chapters.

'support' could be 'require' or 'demand'?

[cderv]

I am sorry but I am not following.

I am thinking I may have misunderstood the situation here. I though it was a question regarding difference in style between HTML and PDF.

What we mean by support cross referencens is that in book you can link section between different document in the project;

[ijmitch]

Hi @cderv ... it's not just style. Normal Markdown links of the form [text](relative-file.qmd) are working fine in the HTML for a book, but render as inoperative links in the PDF.

The alternative suggested to use cross references mean that you need to remember not to use the normal Markdown syntax for this case (whereas it works fine for links to headings in the same file, or to fully qualified URLs outside the book). Cross references also don't include the [text] in the clickable link in the PDF, just the computed chapter number.

[cderv]

Oh I see. In short I would say you are observing the difference between regular link to paths and cross reference links to part of content.

Normal Markdown links of the form text are working fine in the HTML for a book, but render as inoperative links in the PDF.

I missed that because this is expected to me I guess. This syntax [text](relative-file.qmd) means "create a url that points to a specific path".

In HTML when doing a website, this is quite common to link to other file in the website. For ease of use, we indeed have a feature where link to a .qmd is transformed to link to its rendered .html. Here you are using usual HTML links to url. This is not cross reference in the sense referencing to part of content or specific chapters like in book.

In PDF, as this is a single doc, a link to a file is a normal link to a url path. This is not a multiple file project so link to file is just a regular link. In TeX this is \href{summary.qmd}{link to the summary}. So regular link but this points to nowhere - as expected.

So Cross References are the way to do this because it will resolve the reference in the project and create the right internal link using \label and \ref. And yes there is a style difference - maybe we can change it I don't know if possible.

Regarding your proposal to have [text](relative-file.qmd) in PDF be transformed to a cross reference @sec- of the first chapter in the file - this could be a feature request. Just not possible right now as regular link and cross reference link are kept different.

Thanks a lot for the feedback !