Reference/bibliography block gets automatically set to (css set to style="display: none") in a book project although not set anywhere

[jfy133]

Description

I have been writing a Quarto book project, that currently gets rendered in HTML format.

The HTML version is here: https://www.spaam-community.org/intro-to-ancient-metagenomics-book/
The code is here: https://github.com/SPAAM-community/intro-to-ancient-metagenomics-book

I've been trying to use the bibliography system on a one-.bib file per .qmd file, and I am expecting that for all the citations made on the page, it would show up at the end of the file, either by default, or by explicitly specifying refs:::.

However, these never get displayed/rendered on the HTML version (both when running quarto preview or as deployed on GitHub actions.

However, today I realised I had never checked the actual rendered HTML.

I have found out that actually the refs block is actually rendered! When going into my browser's inspect mode on the following page:

https://www.spaam-community.org/intro-to-ancient-metagenomics-book/denovo-assembly.html (QMD: https://github.com/SPAAM-community/intro-to-ancient-metagenomics-book/blob/main/denovo-assembly.qmd)

that the HTML code for the auto-generated end-page bibliography is actually present, however for some reason the display CSS is set to none.

And indeed manually changing that variable in the inspect mode to e.g. block, ends up rendering the bibliography as desired.

However I cannot find ANY reference in the repository to this option being set anywhere, nor why this would be the default behaviour on this book project, particularly given the Quarto documentation implies it should always be rendered by default.

Can anyone give any pointers/suggestions where to look/how to fix?

[mcanouil]

That's not how references works in books.
There are several discussions in the repository about that, especially some demonstrating the use of the section-bibliographies Lua filter available as a Quarto extension and listed in https://quarto.org/docs/extensions/.

The documentation states to use the "ref fenced div" to explicitly place the bibliography.
In a default book project, a document at the end contains this, making the bibliography appears at the end of the book.
If not set, the bibliography is added at "the end of the document" which in the case of multiple pages means at the end of the first document.
The bibliography you forced to be displayed is your whole book bibliography not a part of it.
It does not make sense to have the entire bibliography at the end of every pages, thus the default.

Ref:

• Support for multiple bibliographies #7642
• How do I show the 'citation' block at the end of my book chapters? #7646

A good starting points is to use the "bibliography" label: https://github.com/quarto-dev/quarto-cli/discussions?discussions_q=label%3Abibliography

[jfy133]

Hi @mcanouil

Thank you for the fast response (and slow reply from mine, I'm on half-time parental leave), and detailed reply.

Maybe my post was not so clear. My question specifically is about the HTML and I would like to learn more about the underlying mechanism here - something that my previous search in that category did not find a good result

You say that 'that's not how references works in books', but could you explain more why?
If you inspect the hidden 'references' section HTML of the the denovo assembly page above, compared to the ancient metagenomic pipelines page, it is actually rendering only the references of citations of the page - not the entire bibliography. Or is this also what your suggested plug-in is doing?

By 'that's not how it works' do you mean conceptually Quarto blocks or hides such a mechanism, rather than it has not been implemented in a way that's possible (which is semi contested by my demonstrated above)? Is this something to do with trying to get parity between HTML and PDF versions and the underlying rendering engines?

Also as a general aside (for future readers), I plan to make a PR to the website docs as I find the bibliography behaviour for books is rather unclear in that it is all 'implicit' - the only indication that it maybe that there is only a single bibliography for a book project is here but only because it says 'the bibliography' but depending on how you read it could easily be interpreted of that as 'the bibliography of that page'.

[mcanouil]

I double checked and I don't see the behaviour you described in a default Book setup.
Are you sure you don't have any specific changes?

Steps:

1. quarto create project book demo Demo.
2. Edit references.bib to add a second reference.
3. Edit references.qmd to remove the "ref div".
4. Add the newly added reference to summary.qmd.
5. Render.

Screen.Recording.2024-04-13.at.22.56.03.mov

The references are displayed on the pages they are used as expected and documented.

When keeping the "ref div":

So could you make a simple reproducible example regarding your CSS thing?

FYI, I am using the very latest version of Quarto CLI.

[jfy133]

Huh interesting... yes, I can replicate your example, and in fact can also make it do what I want it to do: specify two separate .bib files in the markdown header section - one for each page, but each rendered on the corresponding page.

Same as your example, but on top of intro.qmd

---
bibliography: 'references.bib'
---

and on top of summary.qmd

---
bibliography: 'references_2.bib'
---

With the respective bib entries in each one.

However I currently cannot 'replicate' my error in a simple example. I've tried various 'obvious' changes that I believe should influence this, however none of them worked.

The closet I got to replicating the error was putting the two bibliography files in a directory (e.g. assets/) and specifying the path in the header. This produced an error for some reason, but not the same issue I'm having in my actual project.

Given my current project is rather complex, I think I will go back and 'start from scratch' on that project, and slowly transfer over the content step-by-step and see if I identify what triggers it (if I do...), and report back.

Thanks for your time!

[jfy133]

I discovered the issue in the end (thank you to @mcanouil for helping me break down the problem and understanding better the expected behaviour).

So actually by default references will be rendered on a per-file basis at the end of each file.

However if you specify ::: {refs} anywhere any .qmd file in the project, it appears this will force the bibliography to be rendered in that specific place, and force the per-page bibliographies to be 'hidden'.

In my case I had a a .qmd file I thought I wasn't using (as I hadn't got it listed in my side bar) that still had the ::: {refs} 'div' in it (as I understand it is now called). This caused all the other bibliographies to be hidden.

Note this is my understanding now, and may not be 'technically correct'. However, I have opened a PR to tweak the docs phrasing here