mdbook-bib

A mdBook plugin for creating a bibliography & citations in your books.

Features

• Add citations from BibTeX/BibLaTeX or YAML bibliography files
• Automatically download your public bibliography from Zotero
• Pandoc-compatible syntax for cross-tool workflows (generate HTML with mdBook and PDF with Pandoc from the same sources)
• Two rendering backends:
  • Custom (Handlebars): Full template customization with CSS/JS
  • CSL: Standard academic styles (IEEE, Chicago, Nature, APA, and 80+ more)

TL;DR

Create an example mdbook:

cargo install mdbook mdbook-bib
mdbook init mybook && cd mybook

Add mdbook-bib config to book.toml:

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

Create example bibliography src/refs.bib:

@article{hello,
  author = {World, Hello},
  title = {My First Citation},
  year = {2024}
}

Cite in src/chapter_1.md:

As shown in @@hello, citations are easy!

Build and serve the book: mdbook build && mdbook serve. Then open http://localhost:3000 in your browser to view the content.

Install

If you have mdbook installed just do:

cargo install mdbook-bib

See all options in the Install section.

Add a Bibliography and Cite Your Entries

Add a bibliography file in BibTeX/BibLaTeX or YAML format to your mdbook's src/ directory and configure in book.toml:

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

Now you can cite entries using either syntax:

{{#cite my-citation-key}}
@@my-citation-key

Pandoc-Compatible Syntax

Enable Pandoc citation syntax for cross-tool workflows:

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

Then use standard Pandoc citations:

@key              # Author-in-text: "Smith (2024)"
[@key]            # Parenthetical: "(Smith, 2024)"
[-@key]           # Suppress author: "(2024)"

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

Rendering Backends

mdbook-bib provides two rendering backends:

• Custom (default): Full control via Handlebars templates, CSS, and JavaScript
• CSL: Standard academic formats (IEEE, APA, Chicago, Nature, 80+ more) via hayagriva

Choose Custom for custom layouts or interactive elements. Choose CSL for standard academic formatting with minimal setup.

Custom Backend (Default)

The default backend uses Handlebars templates for full customization:

[preprocessor.bib]
bibliography = "my_biblio.bib"
# Optional: custom templates
hb-tpl = "render/references.hbs"
cite-hb-tpl = "render/citation.hbs"
css = "render/style.css"

See Custom Backend documentation for template variables and examples.

CSL Backend

For standard academic citation styles, enable the CSL backend:

[preprocessor.bib]
bibliography = "my_biblio.bib"
backend = "csl"
csl-style = "ieee"  # or: chicago-author-date, nature, apa, mla, harvard, ...

See CSL Backend documentation for available styles and examples.

See the manual for all configuration options.

Tip: Debug builds with MDBOOK_LOG=mdbook_bib=debug mdbook build.

Example Books

The example_books/ directory contains working examples demonstrating different configurations.

Contribute

Check the Contrib section of the manual if you want to contribute to mdbook-bib!