bookdown pdf_document2 bibliography references not properly rendered or linked since recent pandoc changes

Issue Description

With recent pandoc updates, I had to update my LaTeX templates to properly support citations. This change is necessary since the old templates throw errors on the old command \cslreferences.

However, the change in the template has resulted in output that is has lost the bibliographic links and formatting. Previously refs were properly presented in "apalike" format, but they are now shown in an un-transformed format, for example: ([ref-coull_dopamine_2012]).

To get refs working, I updated the template.tex with the following change in the csl-refs section, which was sourced from the pandoc templates: https://github.com/jgm/pandoc-templates/blob/master/common.latex

$if(csl-refs)$
% definitions for citeproc citations
\NewDocumentCommand\citeproctext{}{}
\NewDocumentCommand\citeproc{mm}{%
  \begingroup\def\citeproctext{#2}\cite{#1}\endgroup}
\makeatletter
 % allow citations to break across lines
 \let\@cite@ofmt\@firstofone
 % avoid brackets around text for \cite:
 \def\@biblabel#1{}
 \def\@cite#1#2{{#1\if@tempswa , #2\fi}}
\makeatother
\newlength{\cslhangindent}
\setlength{\cslhangindent}{1.5em}
\newlength{\csllabelwidth}
\setlength{\csllabelwidth}{3em}
\newenvironment{CSLReferences}[2] % #1 hanging-indent, #2 entry-spacing
 {\begin{list}{}{%
  \setlength{\itemindent}{0pt}
  \setlength{\leftmargin}{0pt}
  \setlength{\parsep}{0pt}
  % turn on hanging indent if param 1 is 1
  \ifodd #1
   \setlength{\leftmargin}{\cslhangindent}
   \setlength{\itemindent}{-1\cslhangindent}
  \fi
  % set entry spacing
  \setlength{\itemsep}{#2\baselineskip}}}
 {\end{list}}
\usepackage{calc}
\newcommand{\CSLBlock}[1]{\hfill\break\parbox[t]{\linewidth}{\strut\ignorespaces#1\strut}}
\newcommand{\CSLLeftMargin}[1]{\parbox[t]{\csllabelwidth}{\strut#1\strut}}
\newcommand{\CSLRightInline}[1]{\parbox[t]{\linewidth - \csllabelwidth}{\strut#1\strut}}
\newcommand{\CSLIndent}[1]{\hspace{\cslhangindent}#1}
$endif$

previously I was using this (which no longer renders):

$if(csl-refs)$
\newlength{\cslhangindent}
\setlength{\cslhangindent}{1.5em}
\newenvironment{CSLReferences}%
  {$if(csl-hanging-indent)$\setlength{\parindent}{0pt}%
  \everypar{\setlength{\hangindent}{\cslhangindent}}\ignorespaces$endif$}%
  {\par}
\newenvironment{cslreferences}%
  {$if(csl-hanging-indent)$\setlength{\parindent}{0pt}%
  \everypar{\setlength{\hangindent}{\cslhangindent}}\ignorespaces$endif$}%
  {\par}
$endif$

Question

I am guessing that the template needs to be updated or maybe a filter is no longer working as \cslreferences has changes to \CSLReferences. Some advice on how to get these references working in the PDF would be great.

Example (run script build.R or command rmarkdown::render('Article/Article.Rmd', output_format ="all") to render. minimal.zip

p.s. the included example also renders out to html and .doc just to show what the references should look like.

Checklist

When filing a bug report, please check the boxes below to confirm that you have provided us with the information we need. Have you:

[x] formatted your issue so it is easier for us to read?
[x] included a minimal, self-contained, and reproducible example?
[x] pasted the output from xfun::session_info('bookdown') in your issue?
[x] upgraded all your packages to their latest versions (including your versions of R, the RStudio IDE, and relevant R packages)?
[x] installed and tested your bug with the development version of the bookdown package using remotes::install_github("rstudio/bookdown") ?

R version 4.5.1 (2025-06-13)
Platform: x86_64-pc-linux-gnu
Running under: Debian GNU/Linux forky/sid

Random number generation:
 RNG:     Mersenne-Twister 
 Normal:  Inversion 
 Sample:  Rounding 
 
Locale:
  LC_CTYPE=en_AU.UTF-8      
  LC_NUMERIC=C              
  LC_TIME=en_AU.UTF-8       
  LC_COLLATE=en_AU.UTF-8    
  LC_MONETARY=en_AU.UTF-8   
  LC_MESSAGES=en_AU.UTF-8   
  LC_PAPER=en_AU.UTF-8      
  LC_NAME=C                 
  LC_ADDRESS=C              
  LC_TELEPHONE=C            
  LC_MEASUREMENT=en_AU.UTF-8
  LC_IDENTIFICATION=C       

Package version:
  base64enc_0.1.3   bookdown_0.44.2  
  bslib_0.9.0       cachem_1.1.0     
  cli_3.6.5         digest_0.6.37    
  evaluate_1.0.5    fastmap_1.2.0    
  fontawesome_0.5.3 fs_1.6.6         
  glue_1.8.0        graphics_4.5.1   
  grDevices_4.5.1   highr_0.11       
  htmltools_0.5.8.1 jquerylib_0.1.4  
  jsonlite_2.0.0    knitr_1.50       
  lifecycle_1.0.4   memoise_2.0.1    
  methods_4.5.1     mime_0.13        
  R6_2.6.1          rappdirs_0.3.3   
  rlang_1.1.6       rmarkdown_2.29.2 
  sass_0.4.10       stats_4.5.1      
  tinytex_0.57      tools_4.5.1      
  utils_4.5.1       xfun_0.53        
  yaml_2.3.10

Sep 24 '25 06:09 zeigerpuppy

Hi, do you have a .Rmd document that have this errors ?

What is Article/Article.Rmd ? Which format it is using ? Only output: bookdown::pdf_document2 ?

This is for trying to reproduce on my end with same condition as yours.

Also, what is the error you have ?

A few more questions / comments

I had to update my LaTeX templates to properly support citations

Which template is that? Your own custom template?

I updated the template.tex with the following change in the csl-refs section

Which template.tex? Is it your own custom template ?

If the report concerns updating your custom template to match changes in the new Pandoc version, then this is an expected process, and bookdown or rmarkdown can't help with that. For PDF, both tools directly use the TeX template bundled inside Pandoc.

Updating template is a part of the job when maintaining custom template for Pandoc. We do this in rticles package for example:

https://github.com/rstudio/rticles/pull/549

Sep 24 '25 09:09 cderv

Yes the Article/Article.Rmd is the markdown file and it renders pdf_document2 format.

It uses the template.tex.

You can render by running the command markdown::render('Article/Article.Rmd', output_format ="all")

I'll try with a base pandoc template, but I think the \CSLReferences{} may be broken with new changes in pandoc (as I copied those exactly from the default template)

Sep 24 '25 12:09 zeigerpuppy

Interesting addendum.... I tried with a clean template from the rticles package (actually it's the JOSS article, which my template was based on).

When I created a new RMarkdown article in RMarkdown and knited that, it showed a similar issue.

When the YAML option link-citations: yes is enabled, the citations do not get linked, and are displayed as their bibtex index in the rendered PDF [ref-astropy].

To replicate:

In RStudio:

install rticles package
create new RMarkdown "From Template"
select "Journal of Open Source Software Article"
edit the <title>.Rmd file and add link-citations: yes in YAML header
knit the document

Sep 25 '25 02:09 zeigerpuppy