Cross-referencing bookdown::html_document2 not working

Question

I am working on a paper in Rmarkdown and I am using bookdown::html_document2 to knit the output. Cross-referencing figures and tables works with the common Bookdown syntax e.g. \@ref(tab:example_table). Cross-referencing chapter sections/titles does not, however: \@ref(introduction) doesn't work. I'll end up with ?? which is strange since the link points to the correct tag: /example_path/example_filename.html#introduction. I'm working in a single document.

I checked the source code and the tag id's for the chapter titles are correct as well. It does work when I reference the chapter section/title with Pandoc's native syntax: [introduction] works. This will, however, print the tag for the introduction section/title and not the title itself so 'introduction' instead of 'Introduction' with a capital 'I'. An obvious work around is to use [Introduction][introduction] but this defeats the purpose of cross-referencing in my case. I also tried to give my chapter sections/titles custom tags but that wouldn't work either. It also doesn't work with bookdown::pdf_document2.

According to this section from "Authoring Books with R Markdown" the syntax I'm using should work so what am I missing here?

I am using Pandoc version 2.7.3.

EDIT:

Removed session info since it was not relevant to the problem.

EDIT:

@RalfStubner requested a mre (which I should have provided in the first place - thanks Ralf for the advice!):

---
title: "Document Title"
author: "Jono3030"
date: "Last updated: `r Sys.time()`"
output:
  bookdown::html_document2:
    number_sections: no
  bookdown::pdf_document2:
    keep_tex: no
    number_sections: no
  bookdown::word_document2: default
---

# Introduction

This is the introduction

# Chapter_one

This is chapter one.

# Chapter_two

This is chapter two. Trying to reference the Introduction.

This does not work: \@ref(introduction)

This works: [Introduction][introduction]

This does not result in the title but in the tag: [introduction]

Rendered output

This is the error message I receive:

Output created: mre.html
Warning message:
The label(s) introduction not found

But the tag seems to be correctly assigned according to the html:

<div id="introduction" class="section level1">
<h1>Introduction</h1>
<p>This is the introduction</p>
</div>

Here is the href:

<p>This does not work: <a href="#introduction"><strong>??</strong></a></p>
<p>This works: <a href="#introduction">Introduction</a></p>
<p>This does not result in the title but in the tag: <a href="#introduction">introduction</a></p>

In the process of creating the mre I also noticed that \@ref(introduction) behaves differently if numbering of the sections isn't disabled. In that case \@ref(introduction) returns the number of the section ie '1'.

mre:

---
title: "Document Title"
author: "Jono3030"
date: "Last updated: `r Sys.time()`"
output:
  bookdown::html_document2: default
  bookdown::pdf_document2:
    keep_tex: no
    number_sections: no
  bookdown::word_document2: default
---

# Introduction

This is the introduction

# Chapter_one

This is chapter one.

# Chapter_two

This is chapter two. Trying to reference the Introduction.

This does work - returns number: \@ref(introduction)

This works: [Introduction][introduction]

This does not result in the title but in the tag: [introduction]

Rendered output

I'm pretty sure I've had this working before. Maybe it should be \@ref(#introduction)? — Marius
Thanks for the comment @Marius! I forgot to mention that I tried \@ref(#introduction) before which in my case renders the output literally as "@ref(#introduction)" in the html and pdf documents. — jono3030
How are you rendering the document? Are you actually using bookdown and render_book or something else? — Marius
Good call. I'm rendering the document from within Vim with the following command: autocmd Filetype rmd map <F5> :w<CR> :!echo<space>"require(rmarkdown);<space>render('<c-r>%')"<space>\|<space>R<space>--vanilla<enter>. However, as per your comment I tried to render the document directly with render_book("filename.Rmd", "bookdown::html_document2") and I'm still getting the same result i.e. ?? — jono3030
Please provide a minimal reproducible example. Your YAML header contains many (probably) unrelated things. — Ralf Stubner

Ralf Stubner Ralf Stubner · Accepted Answer · 2019-08-14T09:00:47

A section heading in R-Markdown/bookdown has the actual text (e.g. Hello World) and an ID. That ID might be automatic (hello-world in the example) or manually defined (e.g. Hello World {#hello-world-section}). There are several ways to cross reference a section:

\@ref(ID), i.e. \@ref(hello-world) or \@ref(hello-world-section). This will produce a numeric reference to the section if the section is numbered. Otherwise an error/warning is produced.
[section text], i.e. [Hello World]. You can refer to a section by the actual text. The actual text of the section heading will also be the link text.
[link text][section text], i.e. [see above][Hello World]. You still use the section text, but your alternate link text is used.
[link text](#ID), i.e. [see above](#hello-world) or [see above](#hello-world-section). Here you are using the section ID and specify the actual link text.

Note that there is no mode where you specify the ID and automatically get the actual text! Also, you never specify the ID brackets but always in parenthesis.

BTW, I found the cross-reference a section in the bookdown book quite clear. But since you seem to have misunderstood it, you might be able to suggest an improved wording.

Cross-referencing bookdown::html_document2 not working

2 Answers