mdbook-bib

mdbook-bib is an mdBook preprocessor for adding citations and bibliographies to your books. mdBook is written in Rust Klabnik2018.

Two Rendering Backends

mdbook-bib offers two rendering backends to suit different needs:

Custom Backend (Default)

The Custom backend uses Handlebars templates for maximum flexibility. You control exactly how citations and bibliography entries are rendered, including custom HTML, CSS, and JavaScript.

Best for: Power users who need custom layouts, interactive elements, or non-standard citation formats.

See Custom Backend for details.

CSL Backend

The CSL backend uses hayagriva to render citations in standard academic formats. Simply specify a style name and get properly formatted output.

Best for: Academic writing where you need standard citation styles like IEEE, APA, or Chicago.

See CSL Backend for details.

Quick Start

Configure the preprocessor in book.toml:

[preprocessor.bib]
bibliography = "refs.bib"      # BibTeX or YAML
# Custom mode by default
# backend = "csl"              # Optional: use CSL instead of custom
# csl-style = "ieee"           # Required when backend = "csl"

Cite entries with {{#cite key}} or @@key. For Pandoc compatibility, enable citation-syntax = "pandoc" to also use @key, [@key], and [-@key].

GitHub project

mdbook-bib is Open Source and available on GitHub.

License

mdbook-bib is released under the MPL-2.0 License.

Installation

mdbook-bib requires mdbook to be installed.

Install with Cargo (Recommended)

Once mdbook is installed, if you are a Rustacean and you have Rust/Cargo installed, you can get mdbook-bib from Crates simply with:

cargo install mdbook-bib

Install from Binaries

1. Download the binary for your OS (Linux, Windows, macOS)
2. Add the executable’s directory to your PATH

Install from Source

git clone git@github.com:francisco-perez-sorrosal/mdbook-bib.git
cd mdbook-bib
cargo install --path .

Ensure Cargo’s bin/ directory is in your PATH. Then see Configuration to start using the plugin.

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

Custom Backend (Handlebars)

The Custom backend uses Handlebars templates to render citations and bibliography entries. This gives you full control over the HTML output, including custom layouts, interactive elements, and styling.

When to Use Custom Backend

• You need custom HTML layouts for bibliography entries
• You want interactive elements (copy buttons, collapsible details, tooltips)
• You need to match a specific visual style not available in standard CSL formats
• You want to embed custom JavaScript functionality

Configuration

The Custom backend is the default. No backend option is needed:

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

# Optional customization
hb-tpl = "render/references.hbs"      # Bibliography entry template
cite-hb-tpl = "render/citation.hbs"   # Inline citation template
css = "render/style.css"              # Custom CSS
js = "render/script.js"               # Custom JavaScript

Template Variables

Bibliography Entry Template (hb-tpl)

Available variables for rendering each bibliography entry:

Citation Template (cite-hb-tpl)

Available variables for inline citations:

Example Templates

Simple Bibliography Entry

<div class="bib-entry" id="{{citation_key}}">
  <span class="bib-index">[{{index}}]</span>
  <span class="bib-authors">
    {{#each authors}}{{#unless @first}}, {{/unless}}{{this.[1]}} {{this.[0]}}{{/each}}
  </span>
  <span class="bib-title">"{{title}}"</span>
  {{#if pub_year}}<span class="bib-year">({{pub_year}})</span>{{/if}}
  {{#if url}}<a href="{{url}}">[link]</a>{{/if}}
</div>

Simple Citation

<a href="{{path}}#{{item.citation_key}}">[{{item.index}}]</a>

Citation with Hover Preview

<a href="{{path}}#{{item.citation_key}}"
   class="citation"
   title="{{item.title}} ({{item.pub_year}})">
  [{{item.index}}]
</a>

Bibliography Entry with Copy Button

<div class="bib-entry" id="{{citation_key}}">
  <div class="bib-header">
    <span class="bib-index">[{{index}}]</span>
    <button class="copy-btn" onclick="copyBib('{{citation_key}}')">Copy</button>
  </div>
  <div class="bib-content">
    <strong>{{title}}</strong><br>
    {{#each authors}}{{this.[1]}} {{this.[0]}}{{#unless @last}}, {{/unless}}{{/each}}
    {{#if pub_year}}({{pub_year}}){{/if}}
  </div>
</div>

Custom CSS

Style your bibliography with CSS:

.bib-entry {
  margin: 1em 0;
  padding: 0.5em;
  border-left: 3px solid #4a9eff;
}

.bib-index {
  font-weight: bold;
  color: #4a9eff;
}

.bib-title {
  font-style: italic;
}

.citation {
  color: #4a9eff;
  text-decoration: none;
}

.citation:hover {
  text-decoration: underline;
}

Custom JavaScript

Add interactivity with JavaScript:

function copyBib(key) {
  const entry = document.getElementById(key);
  const text = entry.querySelector('.bib-content').innerText;
  navigator.clipboard.writeText(text);
}

Full Configuration Example

[preprocessor.bib]
bibliography = "references.bib"
title = "References"
render-bib = "cited"          # Only show cited entries
order = "index"               # Order by citation appearance
hb-tpl = "render/refs.hbs"
cite-hb-tpl = "render/cite.hbs"
css = "render/bib.css"
js = "render/bib.js"

Tips

• Use {{#if field}}...{{/if}} to conditionally render optional fields
• Use {{#each authors}}...{{/each}} to iterate over the author list
• Inside {{#each authors}}, access {{this.[0]}} (last name) and {{this.[1]}} (first name)
• Add id="{{citation_key}}" to entries for citation linking
• Use {{index}} for numbered citations

CSL Backend

The CSL backend uses hayagriva to render citations and bibliographies in standard academic formats: IEEE, Chicago, APA, Nature, and 80+ other styles.

When to Use CSL Backend

• You need standard academic citation formatting
• You want numbered citations (IEEE, Vancouver) or author-date citations (Chicago, APA)
• You need superscript citations (Nature)
• You want consistent formatting without manual template work

Configuration

Enable the CSL backend by setting backend = "csl":

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

Supported Styles

Numeric Styles

Citations appear as numbers in brackets or superscripts:

Author-Date Styles

Citations include author name and year:

Note Styles

Some styles use footnotes or endnotes:

Citation Variants and Style Types

When using Pandoc citation syntax (@key, [@key], [-@key]), the behavior depends on the style type:

Numeric Styles (IEEE, Vancouver, Nature)

Citation variants have no effect on numeric styles. All variants render identically because numeric citations don’t include author/year information:

Author-Date Styles (APA, Chicago, Harvard)

Citation variants do affect author-date styles:

Use author-in-text (@key) when the author is grammatically part of your sentence:

@smith2024 demonstrated that…

Use parenthetical ([@key]) for citations at the end of a statement:

…as shown in previous work [@smith2024].

Use suppress-author ([-@key]) when you’ve already named the author:

Smith [-@smith2024] argues that…

Label Styles (Alphanumeric)

Citation variants have no effect on label styles. The label is always rendered the same way:

Style Resolution

The CSL backend resolves style names in two ways:

1. Registry Aliases (Recommended)

The styles listed above are registry styles with short, memorable aliases. These provide:

• Short names (e.g., ieee instead of institute-of-electrical-and-electronics-engineers)
• Accurate numeric vs author-date detection
• Superscript rendering for styles like Nature

2. Hayagriva Fallback

Any style available in hayagriva’s archive (80+ styles) can be used by its full name:

csl-style = "annual-reviews"           # Numeric style
csl-style = "american-physics-society" # Another numeric style
csl-style = "council-of-science-editors-author-date"  # Author-date

Fallback limitations:

• Citation format (numeric vs author-date) is detected automatically from CSL metadata
• Superscript styles render as bracketed (e.g., [1] instead of ¹) — superscript cannot be detected from CSL metadata alone

For best results, use registry aliases when available. If you need a specific style not in the registry, the fallback will still format citations correctly, just without superscript support.

Dependent Styles

Some CSL styles are “dependent” — they reference a parent style instead of defining their own formatting. These are not supported. If you encounter an error about a dependent style, use the parent style instead (e.g., use nature instead of nature-communications).

Examples by Style

IEEE (Numeric)

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

Output:

• Inline: [1], [2], [3]
• Bibliography: [1] A. Author, "Title," Journal, vol. 1, pp. 1-10, 2024.

Chicago Author-Date

[preprocessor.bib]
bibliography = "refs.bib"
backend = "csl"
csl-style = "chicago-author-date"

Output:

• Inline: (Smith 2024), (Jones and Lee 2023)
• Bibliography: Smith, John. 2024. "Title." Journal 1: 1-10.

Nature (Superscript)

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

Output:

• Inline: ¹, ², ³ (as superscripts)
• Bibliography: 1. Author, A. Title. Journal 1, 1-10 (2024).

APA

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

Output:

• Inline: (Author, 2024)
• Bibliography: Author, A. (2024). Title. Journal, 1, 1-10.

Vancouver vs Vancouver-Superscript

Both Vancouver styles are numeric, but differ in citation rendering:

vancouver (bracketed):

As shown in previous studies [1], the results [2,3] indicate...

vancouver-superscript (superscript):

As shown in previous studies¹, the results²,³ indicate...

Use vancouver for most medical journals. Use vancouver-superscript when the journal specifically requires superscript numbers (less common).

Alphanumeric

The alphanumeric style uses author-based labels instead of sequential numbers:

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

Output:

• Inline: [Smi24], [JL23] (author-derived label + 2-digit year)
• Bibliography: [Smi24] Smith, J. "Title." 2024.

Label format:

• Single author: First 3 letters of surname + year (e.g., [Smi24])
• Two authors: Initials of both authors + year (e.g., [JL23] for Jones & Lee)

This style is useful when you want readers to identify sources at a glance without flipping to the bibliography.

Full Configuration Example

[preprocessor.bib]
bibliography = "references.bib"
backend = "csl"
csl-style = "chicago-author-date"
title = "References"
render-bib = "cited"    # Only show cited entries
order = "author"        # Sort by author name

YAML Bibliography Support

The CSL backend also supports YAML bibliography files (hayagriva’s native format):

# refs.yaml
smith2024:
  type: article
  title: Example Article
  author:
    - Smith, John
    - Jones, Jane
  date: 2024
  parent:
    - type: periodical
      title: Journal of Examples
      volume: 1
      page: 1-10

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

Citation Linking

Citations automatically link to their bibliography entries. The bibliography page includes anchor IDs matching the citation keys.

Limitations

The CSL backend does not support custom HTML templates, copy buttons, or JavaScript integration. For these features, use the Custom Backend.

Citation Text Processing

For label and author-date styles, hayagriva generates citation text that may include surrounding brackets or parentheses (e.g., [Smi24] or (Smith, 2024)). The CSL backend strips these delimiters before re-wrapping them with markdown links.

Note: This stripping removes all leading/trailing brackets [] and parentheses () from the citation text. In the unlikely event that a citation naturally contains these characters at its boundaries (e.g., a citation key that renders as [[Special]]), they would be removed. Standard bibliography entries are unaffected by this behavior.

Tips

• Choose numeric styles (IEEE, Vancouver) for technical papers
• Choose author-date styles (Chicago, APA) for humanities and social sciences
• Use Nature style for scientific journals requiring superscript citations
• Check your target journal’s requirements before selecting a style

Dev

Testing

Running Tests

cargo test              # Run all tests
cargo test --workspace  # Run tests for the entire workspace

Test Organization

Tests are organized into logical modules under src/tests/:

Test Utilities

The common module provides reusable test infrastructure:

• BibItemBuilder - Fluent builder for creating test BibItem instances
• dummy_bibliography() / yaml_bibliography() - Pre-parsed bibliographies (lazy-loaded)
• create_*_backend() functions - Factory functions for backend instances
• Test fixtures - DUMMY_BIB_SRC, sample text with citations

Example using the builder:

#![allow(unused)]
fn main() {
let item = BibItemBuilder::article("smith2024")
    .title("Test Article")
    .authors(&["Smith, John"])
    .year("2024")
    .build();
}

Parametrized Tests

Tests use the rstest crate for parametrization. Example:

#![allow(unused)]
fn main() {
#[rstest]
#[case::ieee("ieee")]
#[case::apa("apa")]
#[case::chicago("chicago-author-date")]
fn test_csl_style(#[case] style: &str) {
    let backend = CslBackend::new(style.to_string()).unwrap();
    // test logic...
}
}

Each case runs as a separate test, making it easy to identify failures.

Debug

The preprocessor uses the tracing library for logging. To enable debug output, use the MDBOOK_LOG environment variable:

MDBOOK_LOG=mdbook_bib=debug mdbook build

Examples

MDBOOK_LOG=debug mdbook build # **Set globally for all targets**

MDBOOK_LOG=mdbook_bib=debug,handlebars=warn mdbook build # Debug specific modules like ours (mdbook_bib)

Tips

• The default log level is info if MDBOOK_LOG is not set
• Noisy dependencies (handlebars, html5ever) are automatically silenced to warn unless explicitly specified
• Module paths (targets) are only displayed when MDBOOK_LOG is set

Commits

This project follows the Conventional Commits specification for commit messages. This enables automatic changelog generation with proper categorization.

Commit Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Common Types

Examples

feat(parser): add YAML bibliography support
fix: handle empty author fields gracefully
docs: update installation instructions
refactor(render): extract template loading into separate module
test: add integration tests for CSL backend

Before Committing

Format and lint your code:

cargo fmt --              # Format all code
cargo clippy --fix        # Run clippy with auto-fixes
cargo clippy --fix --tests  # Run clippy for tests

Pre-commit hooks (.rusty-hook.toml) block commits with formatting errors. GitHub’s test.yml workflow runs on pushes to master. Look for problems in the GitHub Actions.

Versioning

From version 0.5.0, mdbook-bib’s minor version tracks mdbook’s minor version for compatibility.

Release

The release process is managed via make. Run make help to see all options:

make help

Quick Release

To release the next patch version (auto-incremented):

make release              # Releases 0.5.1 → 0.5.2 automatically

To release a specific version:

make release VERSION=1.0.0

Dry-Run Mode

Add DRY_RUN=1 to any command to simulate without making changes:

make release DRY_RUN=1              # Simulate with auto-version
make release DRY_RUN=1 VERSION=1.0.0  # Simulate specific version
make update-cargo DRY_RUN=1         # Simulate just Cargo.toml update

Prerequisites

Install git-cliff for changelog generation:

cargo install git-cliff

Available Targets

Release Steps

The release process performs these steps locally:

1. check-release - Validate version format and clean working directory
2. update-version - Update Cargo.toml and .github/workflows/doc.yml
3. update-lockfile - Regenerate Cargo.lock
4. update-changelog - Generate CHANGELOG.md using git-cliff
5. Commit all changes with message Prepare for release vX.Y.Z
6. Create annotated tag vX.Y.Z
7. Push commit and tag atomically to origin

GitHub Workflows (Sequential)

After the push, GitHub Actions run in sequence with failure gates:

1. release.yml - Builds binaries for Linux, Windows, and macOS

   • Uploads to GitHub Releases
   • If any platform fails → stops here (no publish)

2. publish.yml - Publishes to crates.io

   • Only runs if all Release builds succeeded
   • If publish fails → stops here (no docs)

3. doc.yml - Deploys documentation to GitHub Pages

   • Only runs if Publish succeeded

This ensures you never publish a crate that fails to build on any platform.

Contribute

Contributions are welcome! You can help by:

• Reporting issues: Found a bug or have a feature request? Open an issue
• Submitting PRs: Bug fixes, improvements, and documentation updates
• Suggesting features: Ideas for new citation styles, syntax, or integrations

See the Dev page for build and test instructions. New to open source? Check How to Contribute.

References