Add support for biblatex-chicago as a cite-method?

[andrewheiss]

Currently there are three possible options allowed in cite-method when using the PDF or LaTeX format: citeproc, natbib, and biblatex. Using any other option produces an error:

Key cite-method has value SOMETHING_ELSE, which must be one of: `citeproc`, `natbib`, `biblatex`

This is ordinarily totally fine—most biblatex styles are supported by defining the style option in biblatexoptions. For instance, this YAML:

format:
  pdf:
    cite-method: biblatex
    biblatexoptions:
      - style=apa
      - backend=biber

…generates this LaTeX output using the default Quarto template:

\usepackage[style=apa,backend=biber]{biblatex}

…and similar styles can be defined, like style=mla, style=nature, style=ieee, and so on. Most biblatex styles follow the same pattern:

\usepackage[<OPTIONS>]{biblatex}

However, one of the more popular biblatex styles, biblatex-chicago, does not recommend or use this same pattern. Because Chicago is a super complex citation system, the package authors decided to simplify its core options into a package with a different name/alias: biblatex-chicago:

% For author-date style
\usepackage[style=authordate]{biblatex-chicago}

% For notes-bibliography style
\usepackage[style=notes]{biblatex-chicago}

% Or in general
\usepackage[<OPTIONS>{biblatex-chicago}

Theoretically there is a way to use the different Chicago styles by loading just \usepackage{biblatex}, but this is not recommended—see this StackExchange answer and sections 4.5.1 and 5.5.1 in the manual. In general, these two commands are 90% equivalent (using the biblatex-chicago package does a bunch of other changes behind the scenes too):

% Author-date style when using the biblatex-chicago package
\usepackage[style=authordate]{biblatex-chicago}

% Author-date style when using the biblatex package, but feeding it as many 
% of the pre-set biblatex-chicago options as possible
\usepackage[style=chicago-authordate,pagetracker=true,
            autocite=inline,alldates=comp,labeldateparts=true,
            citetracker=true,uniquename=minfull,useeditor=true,usetranslator=true,
            usenamec=true,alltimes=12h,urltime=24h,datecirca=true,datezeros=false,
            dateuncertain=true,timezones=true,compressyears=true,
            ibidtracker=constrict,sorting=cms,punctfont,cmslos=true,nodates,
            uniquelist=minyear,maxbibnames=10,minbibnames=7,sortcase=false,
            abbreviate=false,dateabbrev=false,avdate=true]{biblatex}

Those options can all be set in the YAML section of a Quarto document,

format:
  pdf:
    cite-method: biblatex
    biblatexoptions:
      - style=chicago-authordate
      - pagetracker=true
      - autocite=inline
      - alldates=comp
      - labeldateparts=true
      - backend=biber
      - (AND SO ON...)

but (1) that's a ton of options, and (2) even with all those options, the resulting style still isn't exactly what \usepackage[style=authordate]{biblatex-chicago} produces, since biblatex-chicago.sty makes a bunch of other adjustments too.

---

In an effort to make as few changes to the Quarto/pandoc LaTeX template as possible (i.e. not providing my own modified template.tex and instead relying on a handful of custom partials or preexisting YAML options that set pandoc template variables), I've been playing with different ways to get biblatex-chicago to play nicely with Quarto, but so far haven't found a way.

Here's what I've tried:

1. Use cite-method: biblatex-chicago

This would be a simple (perhaps simplest?) approach? If it were somehow possible to add biblatex-chicago as an acceptable cite-method in YAML, and then add something like this in the main template:

$if(biblatex-chicago)$
\usepackage[$if(biblio-style)$style=$biblio-style$,$endif$$for(biblatexoptions)$$biblatexoptions$$sep$,$endfor$]{biblatex-chicago}
$endif$

…then everything could be configured through YAML:

format:
  pdf:
    cite-method: biblatex-chicago
    biblio-style: authordate
    biblatexoptions:
      - backend=biber
      - noibid=true
      - (OTHER THINGS)

However, the biblio.tex template would also need to be adjusted, since it currently uses this to generate \printbibliography:

$if(biblatex)$
...
\printbibliography
...
$endif$

Since Pandoc template conditionals don't seem to support an OR operator, a parallel if statement for $if(biblatex-chicago)$ would also have to be added, which isn't great 🤷

2. Load biblatex-chicago using the include-in-header option

Another approach I tried was putting the command for loading biblatex-chicago in a separate .tex file and injecting that into the preamble:

% file: chicago-stuff.tex
\usepackage[style=authordate, backend=biber]{biblatex-chicago}

format:
  pdf:
    cite-method: biblatex
    include-in-header: chicago-stuff.tex

This successfully adds \usepackage{biblatex-chicago} to the LaTeX file, but because biblatex-chicago is really just a fancy/complex alias for the regular biblatex package, and because the template already loaded biblatex earlier in the document due to cite-method: biblatex, it causes a package conflict error:

LaTeX Error: Option clash for package biblatex.

…since you can't load the same package twice

So that doesn't work 🤷

3. Don't use cite-method: biblatex but do load biblatex-chicago using the include-in-header option

To force the template to not emit \usepackage[...]{biblatex}, I omitted cite-method in the YAML:

format:
  pdf:
    include-in-header: chicago-stuff.tex

That, however, automatically triggers citeproc and Pandoc's CSL-based handling of citations, and adds the CSLReferences environment at the end to contain all the citeproc-processed references, bypassing biblatex-chicago completely.

I tried to stop that by adding citeproc: false to the YAML, and that did indeed stop the CSL processing, but it also stopped all citation processing completely—citation keys in the rendered document remained like @citekey.

So that also won't work.

4. Use a Lua filter?

I then got desperate and tried to see if I could create a Lua filter that would find/replace {biblatex} with {biblatex-chicago}, given some sort of YAML flag:

format:
  pdf:
    cite-method: biblatex
    biblatex-chicago: true

That way, all the conditional parts of the template that depend on $if(biblatex)$ would still work, but the auto-generated \usepackage[...]{biblatex} command would get replaced with \usepackage[...]{biblatex-chicago}.

But it seems like pandoc's Lua filter system can only access the AST of the markdown file, not anything in the template or preamble, so this is also a no-go.

5. Make a copy of template.tex

Creating a copy of template.tex and adding \usepackage[...]{biblatex-chicago} myself definitely works, but then I lose all future changes to Quarto's version of the file.

6. Give up and just use the CSL version of Chicago

This would also work, though the CSL version of Chicago isn't as complete as biblatex-chicago (i.e. handling specific types of magazines, historical archives, etc.)

---

Ultimately, I guess I'm just trying to find a way to use \usepackage[...]{biblatex-chicago} instead of \usepackage[...]{biblatex} with minimal manual template overrides, relying on the Quarto/pandoc template as much as possible. I'm not sure what the best approach for any of this is—or if it even lies in the scope of Quarto (or if it's more of a pandoc issue?). Chicago is a popular citation style (it's Quarto's default when using CSL)—it would be neat/maybe important to support it through biblatex too.

[mcanouil]

It seems you got everything you need to write a format extension which will do exactly what you want.
See https://quarto.org/docs/extensions/formats.html.

[andrewheiss]

That's actually what I've been working on :) https://github.com/andrewheiss/hikma-academic-quarto

However, since the \usepackage[...]{biblatex} command is part of the default template.tex and not part of a smaller partial, it would still require (I think?) replacing the whole default template, which I'm trying to hopefully avoid

[andrewheiss]

Oooh I just came across this commit (07fe91d) that provides an undocumented (at least at Quarto.org) option for biblio-config. That means I can do this in the YAML:

format:
  pdf:
    biblio-config: false
    cite-method: biblatex

The cite-method makes it so all the $if(biblatex)$ conditionals run (like at the end where \printbibliography goes), while biblio-config: false makes it so that the template doesn't emit any biblatex commands! I can provide that on my own in a partial and not touch the main template.tex file.

I'll work up an example of a working format that can handle both regular biblatex styles like apa and mla and biblatex-chicago, and I'll post it here once I push it.

But it seems like biblio-config fixes all my problems!

[mcanouil]

Worth opening an issue to document that yaml option which is indeed not described in "reference" of the quarto.org.
(At least search can't find it in the website).

Let me know when you have something complete or near complete for this to be added in https://github.com/mcanouil/awesome-quarto (or open a suggestion issue).

[cderv]

The variable is documented as part of the extension template format : https://github.com/quarto-journals/article-format-template
We added it because of similar constraint in some journals where loading biblatex was already done in the CLS class.

I believe documentation for templates and extensions will improve over time. Lots of things to document ! 😅

Pandoc does not offer a way to customize the value of the package in the template. Simple variable addition in their template to do. Could be worth opening an issue there in case they accept.

[mcanouil]

Maybe worth to also document it in the "reference" part of the documentation website.
When I am looking for YAML option, that is the first place I look.

[cderv]

Do we document already all the Pandoc's template variable in the reference ? If so then sure we should add it there too.
I believe you mean under PDF format ? https://quarto.org/docs/reference/formats/pdf.html ?

[mcanouil]

Not biblio-config, I just double checked.

Yes, under the appropriate sub page of "reference".

[andrewheiss]

Given the existence of the biblio-config option, this is all you have to do to support biblatex-chicago.

1: Copy a template partial that is included in the preamble (i.e. before \begin{document}), like title.tex

2: Add a conditional statement to the partial file that will add \usepackage[]{biblatex-chicago} if a YAML variable biblatex-chicago is true:

$if(biblatex)$
% ----------
% BibLaTeX
% ----------
$if(biblatex-chicago)$
\usepackage[$if(biblio-style)$$biblio-style$,$endif$$for(biblatexoptions)$$biblatexoptions$$sep$,$endfor$]{biblatex-chicago}
$else$
\usepackage[$if(biblio-style)$style=$biblio-style$,$endif$$for(biblatexoptions)$$biblatexoptions$$sep$,$endfor$]{biblatex}
$endif$

\addbibresource{$bibliography$}
$endif$

3: Configure the YAML like so:

format:
  pdf:
    biblio-config: false      # No default \usepackage[]{biblatex}
    template-partials:        # Use the updated partial file
      - "path/to/title.tex"
    cite-method: biblatex     # Use biblatex
    biblatex-chicago: true    # Enable biblatex-chicago
    biblio-style: authordate  # Use the author-date style (or notes)
    biblatexoptions:          # Set any other Chicago-specific options
      - backend=biber
      - isbn=false

4: That's it!

---

You can see a working version of this at a custom format I made (YAML settings; custom partial)

[cderv]

Awesome! Thank you for sharing @andrewheiss !