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]
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]
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.
