mdbook-bib

mdbook-bib is a [mdBook] plugin for creating a bibliography & reference its citations in your books. mdBook is written in the Rust language [Klabnik2018].

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. Follow the instructions here to install mdbook.

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 and uncompress the binaries for your OS (Linux, Windows or macOS)
2. Add the parent directory of the executable to your PATH env variable to make the binary available in your shell

Install from Sources

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

Make sure your PATH env var contains Cargo's /bin directory where the plugin was installed.

Then follow the instructions here to use the plugin.

Configuration

Adding a BibLaTex-format Bibliography

mdbook-bib allows adding a bibliography in BibLaTex format to your book.

Assuming that your directory structure for your book looks like this:

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

1. just add your .bib file containing the bibliography items to the root source of your mdbook (pointed by the src parameter in the [book] section of the .toml file)...

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

2. ...and then add the following configuration to the .toml config file:

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

The bibliography will appear as a separate section in your book ToC.

Adding a BibLaTex-format Bibliography from Zotero

Alternatively, you can use any publicly available library in BibLaTex format from Zotero. In order to do so, just specify the Zotero UserId of the public bibliography you want to access in the preprocessor section:

[book]
#...
[preprocessor.bib]
zotero-uid = "<a_Zotero_userID>"

The Zotero UserId is the number that appears following the users resource in a public bibliography URL. e.g. in the example below, the Zotero UserId is 475425:

https://api.zotero.org/users/475425/items?format=atom&v=3

If you have a Zotero account, you can make your library public marking the checkbox in the Zotero Privacy Settings page.

You can find your Zotero userID in the Zotero Feeds/API section of your Zotero account.

Add References/Citations to the Bibliography

In your markdown files, create references/citations to the citation-keys included in the .bib file with any of these two options:

1. Surround the citation key with the {{#cite and }} delimiters
2. Prepend the citation key with two @ characters

Configure your own Style for Bibliography Entries

You can override the default biblio style provided for the bibliography entries by specifying an ad-hoc Handlebars template and style. In order to do so, the hb-tpl, css, and js parameters are provided as configuration options. hb-tpl allows to point to a .hbs file that includes the Handlebars style. For examples, see the provided templates.

The available placeholders that can be used in the handlebars template for now are:

• citation_key
• authors
• title
• url
• pub_year

Also, with the parameters css and js, you can point to files that provide your own css style and/or Javascript functions used in the rendering of the Handlebars template entries (e.g. for the bib_div class above). For more details, check the structure of the manual of this project.

Handlebars files for different reference styles are provided in the folder templates in the GitHub repository.

Configure your own Style for Citations

You can override the default inline citation style by specifying a Handlebars template using the cite-hb-tpl config option. This works in the same way as for bibliography styles

The available placeholders that can be used in the handlebars template for now are:

• path -- the path to the bibliography file in the output HTML
• item.citation_key
• item.authors
• item.title
• item.url
• item.pub_year

Handlebars files for different citation styles are provided in the folder templates in the GitHub repository.

Sort order references

Configuration Parameters

A complete preprocessor.bib section example, which reads the bibliography from a local file and only shows the cited entries of the bibliography:

[preprocessor.bib]
title = "My Biblio!"
bibliography = "my_biblio.bib"
render-bib = "cited"
hb-tpl = "render/my_references.hbs"
css = "render/my_style.css"

Contribute to mdbook-bib

mdbook-bib is OSS, so contributions are welcome, specially in the form of new requests for features that may be useful for you, issues found, bug fixes, and any other PR.

Use Github's issue tracker to track the list of current issues.

Not sure how to contribute? Check this guide

References