Using BibTeX files with AsciiDoc content

tips & tricks
1

Hugo supports several content formats including AsciiDoc. It renders AsciiDoc content by calling the Asciidoctor executable. Although slower than rendering Markdown, the AsciiDoc format offers additional features, including the ability to insert citations and bibliographies from BibTeX files.

Setup

These instructions were written for and tested on Ubuntu 24.04.3 LTS.
Adjust them as needed for your specific operating system.

To render AsciiDoc content with BibTeX support you must:

  1. Install Ruby, Asciidoctor, and the Asciidoctor BibTeX extension:

    sudo apt install ruby ruby-dev
gem install --user-install asciidoctor asciidoctor-bibtex

  2. Add $HOME/.local/share/gem/ruby/3.2.0/bin to your PATH. You can include something like this in your .bashrc file:

    # Set PATH to include $HOME/.local/share/gem/ruby/3.2.0/bin if it exists.
if [ -d "$HOME/.local/share/gem/ruby/3.2.0/bin" ];then
  PATH="$HOME/.local/share/gem/ruby/3.2.0/bin:$PATH"
fi

  3. In your site configuration, add the Asciidoctor BibTeX extension to the list of Asciidoctor extensions:

    [markup.asciidocExt]
  extensions = ['asciidoctor-bibtex']

  4. In your site configuration, add the Asciidoctor executable to Hugo’s security.exec allowlist:

    [security.exec]
  allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^git$', '^npx$', '^postcss$', '^tailwindcss$','^asciidoctor$']

  5. Create content files with an .ad, .adoc, or .asciidoc extension.

BibTeX files

A BibTeX file has a .bib extension, and typically looks something like this:

@article{einstein1935,
  author  = {Albert Einstein and Boris Podolsky and Nathan Rosen},
  title   = {Can Quantum-Mechanical Description of Physical Reality Be Considered Complete?},
  journal = {Physical Review},
  volume  = {47},
  number  = {10},
  pages   = {777--780},
  year    = {1935}
}

@book{knuth1997,
  author    = {Donald E. Knuth},
  title     = {The Art of Computer Programming, Volume 1: Fundamental Algorithms},
  publisher = {Addison-Wesley Professional},
  year      = {1997},
  edition   = {3rd},
  address   = {Reading, Massachusetts}
}

You can use a single BibTeX file for the entire project, separate files for each page, or a combination of both.

Inserting citations and bibliography items

To insert a citation:

The foo cite:[einstein1935] is bar cite:[knuth1997].

To insert a single bibliography item:

bibitem:[einstein1935]

To insert the entire bibliography:

bibliography::[]

You can control the sort order, the citation style, and locale with document attributes. See details.

Location of BibTex files

Asciidoctor determines the location of BibTeX files based on two primary scenarios:

  1. Explicit path: You specify the exact file path.
  2. Automatic location: Asciidoctor searches for the file, with the search logic determined by the value of the markup.asciidocExt.workingFolderCurrent setting in your site configuration.

Each scenario is described below.

Explicit path

If a path is provided via the site configuration or a document attribute, it must be an absolute path or a path relative to the current working directory (typically the root of your project).

The site configuration setting (markup.asciidocExt.attributes.bibtex-file) overrides the document attribute setting (:bibtex-file:).

You can allow the document attribute to take precedence by using the “soft setting” syntax in your site configuration: append the @ symbol to the end of the attribute value in the site configuration (e.g., bibtex-file=my.bib@). See details.

Automatic location

If a path is not provided via the site configuration or a document attribute, Asciidoctor searches for the file, with the search logic determined by the value of the markup.asciidocExt.workingFolderCurrent setting in your site configuration.

If workingFolderCurrent is false or not defined, Asciidoctor searches for the first .bib file it can find in this order:

  1. The current working directory (typically the root of your project).
  2. The $HOME/Documents directory.

If workingFolderCurrent is true, Asciidoctor searches for the first .bib file it can find in this order:

  1. The directory where the current AsciiDoc file resides.
  2. The current working directory (typically the root of your project).
  3. The $HOME/Documents directory.

Controlling BibTeX File publishing

All BibTeX files found inside the content directory are published during the site build. To prevent this, use an exclusionary mount in your site configuration:

[[module.mounts]]
  source = 'content'
  target = 'content'
  excludeFiles = '**.bib'

Known issue

If the Asciidoctor BibTeX extension is enabled in your site configuration, Asciidoctor will emit warnings when processing an .adoc file if it cannot locate a BibTeX file for that document. This occurs even if the document does not contain any citation macros like cite, bibitem, or bibliography.

For more details on this behavior, please see: https://github.com/asciidoctor-contrib/asciidoctor-bibtex/issues/103. You can work around this by placing an empty BibTeX file in the root of your project directory.

Try it

After completing steps 1 and 2 of the setup instructions above…

git clone --single-branch -b hugo-forum-topic-56119 https://github.com/jmooring/hugo-testing hugo-forum-topic-56119
cd hugo-forum-topic-56119
hugo server
3 Likes