Configuration

Quick Start

Add a bibliography file (BibTeX or YAML) to your mdbook source directory:

my_book/
├── book.toml
└── src
    ├── refs.bib
    ├── chapter_1.md
    └── SUMMARY.md

Configure in book.toml:

[preprocessor.bib]
bibliography = "refs.bib"

That’s it! The bibliography appears as a section in your book’s table of contents.

Citation Syntax

Citation syntax controls how you write citations in your markdown files.

Default Syntax

Use either the Handlebars-style or double-at notation:

Example:

According to {{#cite smith2024}}, the results show...
The experiment confirmed earlier findings @@jones2023.

Pandoc Syntax (Opt-in)

Enable Pandoc-compatible syntax for cross-tool workflows (e.g., generating both HTML via mdBook and PDF via Pandoc):

[preprocessor.bib]
bibliography = "refs.bib"
citation-syntax = "pandoc"

This lets you use the same source files with both mdBook (HTML) and Pandoc (PDF).

Example:

According to @smith2024, the results show significant improvement.
This has been documented [@jones2023].
Jones argues [-@jones2023] that further research is needed.
Contact: user\@example.com

Notes:

• Default syntax ({{#cite key}} and @@key) continues to work alongside Pandoc syntax
• Citations inside code blocks are NOT processed
• Email addresses and URL mentions (e.g., https://twitter.com/@user) are NOT matched

Citation key format:

• Native patterns ({{#cite}}, @@): Allow keys starting with digits (e.g., @@2024smith) — BibLaTeX-compliant
• Pandoc patterns (@key, [@key], [-@key]): Require letter or underscore at start (e.g., @smith2024) — Pandoc spec

This difference is by design for cross-tool compatibility. If you need digit-prefixed keys with Pandoc syntax, use the native {{#cite 123key}} form instead.

Unsupported Pandoc features:

• Multi-citation: [@smith2024; @jones2023] — use separate citations instead
• Locators: [@smith2024, p. 42] — page numbers not supported
• Prefixes/suffixes: [see @smith2024, ch. 3] — use surrounding text instead

Backend Selection

The backend controls how citations are rendered in the output.

Understanding the Pipeline

┌─────────────────────────────────────────────────────────────────┐
│                    YOUR MARKDOWN SOURCE                         │
│  "According to @smith2024, this is true [@jones2023]."          │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          ▼
              ┌───────────────────────┐
              │   citation-syntax     │  ← How citations are WRITTEN
              │   "default" | "pandoc"│     (input parsing)
              └───────────┬───────────┘
                          │
                          ▼
              ┌───────────────────────┐
              │       backend         │  ← How citations are RENDERED
              │   "custom" | "csl"    │     (output engine)
              └───────────┬───────────┘
                          │
            ┌─────────────┴─────────────┐
            ▼                           ▼
   ┌─────────────────┐        ┌─────────────────┐
   │ backend="custom"│        │  backend="csl"  │
   │                 │        │                 │
   │ Handlebars      │        │ CSL styles via  │
   │ templates       │        │ hayagriva       │
   └─────────────────┘        │  • csl-style    │
                              └─────────────────┘

Custom Backend (Default)

Uses Handlebars templates for full customization of citation and bibliography appearance.

[preprocessor.bib]
bibliography = "refs.bib"
# backend = "custom"  # This is the default

See Custom Backend for template options.

CSL Backend

Uses hayagriva for standardized academic citation styles (IEEE, APA, Chicago, etc.).

[preprocessor.bib]
bibliography = "refs.bib"
backend = "csl"
csl-style = "ieee"

See CSL Backend for available styles.

Bibliography Options

Section Title

[preprocessor.bib]
title = "References"  # Default: "Bibliography"

Which Entries to Show

[preprocessor.bib]
render-bib = "cited"  # Only show cited entries (default)
render-bib = "all"    # Show all entries from the bibliography file

Sort Order

[preprocessor.bib]
order = "none"    # Original order from file (default)
order = "key"     # Alphabetical by citation key
order = "author"  # Alphabetical by author name
order = "index"   # Order of first citation in the book

Per-Chapter Bibliographies

Add a bibliography section at the end of each chapter:

[preprocessor.bib]
add-bib-in-chapters = true  # Default: false

Configuration Reference

Examples

Minimal Setup

[preprocessor.bib]
bibliography = "refs.bib"

Academic Paper with IEEE Style

[preprocessor.bib]
bibliography = "refs.bib"
backend = "csl"
csl-style = "ieee"
title = "References"

Pandoc-Compatible Workflow

[preprocessor.bib]
bibliography = "refs.bib"
citation-syntax = "pandoc"
backend = "csl"
csl-style = "apa"

Fully Customized

[preprocessor.bib]
bibliography = "refs.bib"
title = "Bibliography"
render-bib = "cited"
order = "index"
add-bib-in-chapters = true
hb-tpl = "templates/references.hbs"
cite-hb-tpl = "templates/citation.hbs"
css = "templates/style.css"

Advanced Options

Using Zotero

Download a public bibliography from Zotero instead of a local file:

[preprocessor.bib]
zotero-uid = "<your_zotero_user_id>"

Setup:

1. Find your User ID in Zotero Feeds/API settings
2. Make your library public in Privacy Settings

Debugging

Enable debug logging to troubleshoot parsing or rendering issues:

MDBOOK_LOG=mdbook_bib=debug mdbook build   # mdbook-bib only
MDBOOK_LOG=debug mdbook build               # All components