CODEWITHSUNDEEP
ryamlbookdown
Brian Holt
Brian Holt

Reputation: 75

Using bookdown, must one set number_sections: true in _output.yml for cross referencing sections?

I'm able to render an HTML book using Bookdown, but cross referencing sections is failing.

I can make it work, however. First, I'll make the cross referencing work.

Edit 9/20/20 12:15 pst in response to a request for a more repex

My chapter heading looks like this:

# Getting Articles {#getArt}

The cross reference in a different chapter looks like this, a text excerpt:

you'll need to walk through the steps found in the Getting Articles section \@ref(getArt) )

This reference works when _output.yml's number_sections: true, but not when number_sections: false

end edit

In my _output.yml I have the following code; the comment on the last line is my issue:

bookdown::gitbook:
 css: style.css
 toc_depth: 4
 number_sections: true    # if true, cross reference section labels render correctly

If I set number_sections true then I may correctly cross reference to sections, like this where it reads "...in the Getting Articles section 2" :

Jay Efran (2007) (to obtain this article, you’ll need to walk through the steps found in the Getting Articles section 2 )

But if my _output.yml looks like this:

bookdown::gitbook:
 css: style.css
 toc_depth: 4
 number_sections: false

I get the following (note the "??"):

Jay Efran (2007) (to obtain this article, you’ll need to walk through the steps found in the Getting Articles section ?? )

According to Yuhui's bookdown text, section 2.6, it states the following about cross referencing and the "??":

When a referenced label cannot be found, you will see two question marks like ??, as well as a warning message in the R console when rendering the book.

But I am at a loss as what to do. Clearly, the cross reference is there and correctly works but only under the _output.yml condition number_sections: is set to true.

Is there a work around?

Upvotes: 1

Views: 212

Answers (1)

Martin C. Arnold
Martin C. Arnold

Reputation: 9668

The reason why this doesn't work is that bookdown converts \@ref(getArt) (where getArt is the ID of your section) to a link to that section and sets the section number as the link text. For HTML output this looks roughly like this:

<a href="chapter_title.html#getArt">2</a>

(see the source on GitHub)

If you set number_sections: false there is no chapter number, hence the link text is "??". In this respect, the documentation is somewhat inaccurate (because the reference exists and the link actually works).

The workaround is to manually assign an ID to the section header and reference it like this:

You'll need to walk through the steps found in the 
[Getting Articles section](#getArt).
    
# Getting Articles {#getArt}

Upvotes: 2

Related Questions