# mdbook-bib
A [mdBook](https://github.com/rust-lang/mdBook) plugin for creating a bibliography & citations in your books.
[](https://github.com/francisco-perez-sorrosal/mdbook-bib/actions/workflows/test.yml)
[](https://github.com/francisco-perez-sorrosal/mdbook-bib/blob/master/LICENSE)
[](https://francisco-perez-sorrosal.github.io/mdbook-bib/)
[](https://crates.io/crates/mdbook-bib)
## 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:
```sh
cargo install mdbook mdbook-bib
mdbook init mybook && cd mybook
```
Add mdbook-bib config to `book.toml`:
```toml
[preprocessor.bib]
bibliography = "refs.bib"
```
Create example bibliography `src/refs.bib`:
```bibtex
@article{hello,
author = {World, Hello},
title = {My First Citation},
year = {2024}
}
```
Cite in `src/chapter_1.md`:
```markdown
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](https://github.com/rust-lang/mdBook) installed just do:
```sh
cargo install mdbook-bib
```
See all options in the [Install section](https://francisco-perez-sorrosal.github.io/mdbook-bib/install.html).
## Add a Bibliography and Cite Your Entries
Add a bibliography file in [BibTeX/BibLaTeX](https://www.ctan.org/pkg/biblatex) or [YAML](https://github.com/typst/hayagriva) format to your mdbook's `src/` directory and configure in `book.toml`:
```toml
[preprocessor.bib]
bibliography = "my_biblio.bib"
```
Now you can cite entries using either syntax:
```markdown
{{#cite my-citation-key}}
@@my-citation-key
```
### Pandoc-Compatible Syntax
Enable Pandoc citation syntax for cross-tool workflows:
```toml
[preprocessor.bib]
...
citation-syntax = "pandoc"
```
Then use standard Pandoc citations:
```markdown
@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](https://github.com/typst/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:
```toml
[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](https://francisco-perez-sorrosal.github.io/mdbook-bib/custom.html) for template variables and examples.
### CSL Backend
For standard academic citation styles, enable the CSL backend:
```toml
[preprocessor.bib]
bibliography = "my_biblio.bib"
backend = "csl"
csl-style = "ieee" # or: chicago-author-date, nature, apa, mla, harvard, ...
```
See [CSL Backend documentation](https://francisco-perez-sorrosal.github.io/mdbook-bib/csl.html) for available styles and examples.
See the [manual](https://francisco-perez-sorrosal.github.io/mdbook-bib/) for all configuration options.
**Tip**: Debug builds with `MDBOOK_LOG=mdbook_bib=debug mdbook build`.
## Example Books
The [`example_books/`](example_books/) directory contains working examples demonstrating different configurations.
## Contribute
Check the [Contrib section of the manual](https://francisco-perez-sorrosal.github.io/mdbook-bib/contrib.html) if you want to contribute to mdbook-bib!