[FR] Add support for the YALM setting "language: ui: references_name" to change the title of references section in html output

[gvazquezvilar]

Right now (to the best of my knowledge) there is no way to modify the title of the "References" section that is added at the end of each chapter in the bookdown::gitbook html output. This is required not only for a proper multi-language support, but also because in some cases it would be useful to have a different title for the section (e.g., "Bibliography").

One option would be to add support for a new YALM setting

language:
  ui:
    references_name: 'Bibliography'

and use this setting for the corresponding section title. Now, in the output html files this is simply rendered as <h3>References</h3>

[cderv]

How do you insert your reference section in your project ?

See bookdown-demo for an example (in which we use References as title, but you can replace header to your own choice) https://github.com/rstudio/bookdown-demo/blob/main/06-references.Rmd

We mention in the doc how to add references section in a HTML book https://bookdown.org/yihui/bookdown/citations.html

This is Pandoc feature: https://pandoc.org/MANUAL.html#placement-of-the-bibliography

The split-bib config will reuse the header of the bibliography section and put it in the chapter. References is just the default used by Pandoc.

[gvazquezvilar]

Thank you for the answer. The example you mention: https://github.com/rstudio/bookdown-demo/blob/main/06-references.Rmd works fine for references at the end of the document. However, you say that split-bib config will reuse the header of the bibliography section and put it in the chapter. If this is correct, it is not working for me.

The relevant part of my YAML config is:

output: bookdown::gitbook
documentclass: book
bibliography: [book.bib]
biblio-style: apalike
link-citations: yes

bookdown::gitbook:
  split_by: rmd
  math_method: r-katex

I use the split_by: rmd command to get the html filenames from those of the Rmd files. By running

bookdown::render_book("index.Rmd", "bookdown::gitbook")

I already get a section with the citations at the end of each of the chapters, including its title "References", and I don't know how to change it. If, following pandoc manual, I add

### Bibliography {-}
::: {#refs}
:::

at the end of each Rmd file, I get the references twice, one with the "Bibliography" title, and the second with the "References" title. Also tried adding reference-section-title: Bibliography in the YAML configuration file with no luck.

Looking for a solution I realized that I am not the only one with this issue, see e.g.: https://stackoverflow.com/questions/67199534/change-references-by-bibliography-in-bookdown-gitbook

[cderv]

I already get a section with the citations at the end of each of the chapters

Do you have chapter for references like bookdown-demo ? If you set split_bib = FALSE for gitbook, where the Reference part is set and what is the header of the section ?

In the bookdown-demo, you'll notice that there is specific chapter at the end, with only a title. This is because Pandoc will put bibliography at the end of the book. (end of all merged document).

If you use the ::: {#refs} trick , you need to add the header inside the ::: block. Try

::: {#refs}
### Bibliography {-}
:::

[gvazquezvilar]

To narrow down my problem I tried to do a minimal example reproducing it and then it started working as expected. The key for me is that whenever the last section just includes a single line with the header:

`r if (knitr::is_html_output()) '# Bibliography {-}'`

Then pandoc uses this title for the per-chapter reference sections. I believe that this is indeed not very intuitive and that it is not explained at all in the official documentation: https://bookdown.org/yihui/bookdown/citations.html

A more intuitive option would be to add support for the reference-section-title: Bibliography in the YAML configuration file. In my book, this command adds a last section with the right title, but it is not a separate html file and the title is no longer reused in the per-chapter citations sections.

Thank you Christophe for your help. Before asking here I tried all possible options for a couple of days, with no success. I even had prepared a script to swap in the html files <h3>References</h3> by something else.

[cderv]

Then pandoc uses this title for the per-chapter reference sections.

To be clear on what happens

• This is bookdown which odes the per-chapter reference (controlled by split_bib options). It reads the references section written by Pandoc and split it to but the right references in the right chapter
• Pandoc Citeproc will add no title by default for the bibliography. By default, it will place the reference part at the end of the document
• By adding `r if (knitr::is_html_output()) '# Bibliography {-}'` you are adding a section in your HTML book specific for references.
• bookdown will re-use this title for the per-chapter bibliography.

A more intuitive option would be to add support for the reference-section-title: Bibliography in the YAML configuration file. In my book, this command adds a last section with the right title, but it is not a separate html file

reference-section-title: Bibliography tells pandoc to add a Title to the bibliography, but by default it will still add the bibliography at the end of the document. But this will happen at Pandoc conversion step, and bookdown has no idea that this will be a new chapter in its own HTML page. This is why we don't document this way, but we document the other way (adding a specific chapter for this in the book)

and the title is no longer reused in the per-chapter citations sections.

This could be an issue 🤔 If there is a header above the reference section, it should be reused. Unless Pandoc adds it another way this option is set...

Thank you Christophe for your help. Before asking here I tried all possible options for a couple of days, with no success. I even had prepared a script to swap in the html files <h3>References</h3> by something else.

No problem. Feel free to ask anytime. We try to document correctly, but it is hard to document everything in the right place and the right form.

[cderv]

reference-section-title is not working for me at all. It creates an issue with how bookdown works to detect chapters. I guess you don't get the same error because you are using split_by = "rmd".

But basically bookdown expects chapters to be at least in one source file, but using reference-section-title creates a title with no Rmd file associated, so this is erroring.

Error in vapply(idx2, character(1), FUN = function(i) head(nms[idx > i],  : 
  values must be length 1,
 but FUN(X[[7]]) result is length 0

Anyhow, for now, it can't be used. Sorry

[cderv]

Ok know issues that I forgot about 🤦

• https://github.com/rstudio/bookdown/issues/1108