# Using BibTeX files with AsciiDoc content

**URL:** <https://discourse.gohugo.io/t/using-bibtex-files-with-asciidoc-content/56119>\
**Category:** tips & tricks\
**Tags:** asciidoc\
**Created:** [October 20, 2025, 5:24pm UTC](https://discourse.gohugo.io/t/using-bibtex-files-with-asciidoc-content/56119 "2025-10-20T17:24:08Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [October 20, 2025, 5:24pm UTC](https://discourse.gohugo.io/t/using-bibtex-files-with-asciidoc-content/56119/1 "2025-10-20T17:24:08Z")

</div>

Hugo supports several [content formats](https://gohugo.io/content-management/formats/) including [AsciiDoc](https://asciidoc.org/). It renders AsciiDoc content by calling the [Asciidoctor](https://asciidoctor.org/) executable. Although slower than rendering Markdown, the AsciiDoc format offers additional features, including the ability to insert citations and bibliographies from [BibTeX](https://www.bibtex.org/) 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:

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

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

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

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:

```plaintext
@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:

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

```

To insert a single bibliography item:

```plaintext
bibitem:[einstein1935]

```

To insert the entire bibliography:

```plaintext
bibliography::[]

```

You can control the sort order, the citation style, and locale with document attributes. See [details](https://github.com/asciidoctor-contrib/asciidoctor-bibtex).

### 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](https://docs.asciidoctor.org/asciidoc/latest/attributes/assignment-precedence/).

#### 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:

```toml
[[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](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](#setup) instructions above…

```plaintext
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

```