Some time ago I started working on a couple of books to summarize ideas about AI and QC. I wanted to use a simple format for the text, like markdown, and I found the mdBook project. When I started using it, I almost immediately had the need to add a bibliography to reference papers/books from the text. Unfortunately, neither markdown nor the mdBook project itself provides features to deal with bibliographies in an easy way, unless you start adding ugly html tags here and there.

So, after I got tired of adding manually the references and use html tags, I decided to contribute a solution for the mdBook project that supports adding .bib files from Latex (e.g. generated manually or with any tool to collect, organize and cite articles/books such as Zotero or Mendeley Cite) and reference those cites from the markdown text in an easy way. People use to have these .bib files to keep their collected bibliographies during their research, work etc., so why not allow them to reuse the .bib files in their mdBooks too?

The first problem I faced was that the mdBook project was written in Rust, and I had no idea of that language. That wasn’t a big deal, but what I really didn’t want to do was the parsing of the .bib files. Fortunately, I stumbled upon the nom-bibtex Rust library, which can parse the entries found in the BibTeX format description. So, I decided to explore the internals of the mdBook project to find the right places to inject the new functionality without messing up the current structure of the project (chapters, etc.) and learn Rust at the same time, in order to provide a simple solution for referencing/citing bibliography. In about a week or so, I had a solution developed in my spare time that I think that fits with the mdBook project philosophy and eases the task at hand.

The usage is very simple:

1st) You add your bibliography file in BibTex format to yourbook. To do this, you just add your .bib file containing the bibliography items to the source root of your mdBook. Items in the .bib file look like this:

@article{ven_brain-inspired_2020,
	title = {Brain-inspired replay for continual learning with artificial neural networks},
	volume = {11},
	rights = {2020 The Author(s)},
	issn = {2041-1723},
	url = {https://www.nature.com/articles/s41467-020-17866-2},
	doi = {10.1038/s41467-020-17866-2},
	abstract = {Artificial neural networks suffer from catastrophic forgetting. Unlike humans, when these networks are trained on something new, they rapidly forget what was learned before. In the brain, a mechanism thought to be important for protecting memories is the reactivation of neuronal activity patterns representing those memories. In artificial neural networks, such memory replay can be implemented as ‘generative replay’, which can successfully – and surprisingly efficiently – prevent catastrophic forgetting on toy examples even in a class-incremental learning scenario. However, scaling up generative replay to complicated problems with many tasks or complex inputs is challenging. We propose a new, brain-inspired variant of replay in which internal or hidden representations are replayed that are generated by the network’s own, context-modulated feedback connections. Our method achieves state-of-the-art performance on challenging continual learning benchmarks (e.g., class-incremental learning on {CIFAR}-100) without storing data, and it provides a novel model for replay in the brain. One challenge that faces artificial intelligence is the inability of deep neural networks to continuously learn new information without catastrophically forgetting what has been learnt before. To solve this problem, here the authors propose a replay-based algorithm for deep learning without the need to store data.},
	pages = {1--14},
	number = {1},
	journaltitle = {Nature Communications},
	author = {Ven, Gido M. van de and Siegelmann, Hava T. and Tolias, Andreas S.},
	urldate = {2020-10-15},
	date = {2020-08-13},
	month = {jun},
    year = {2020},
	langid = {english},
	note = {Number: 1 Publisher: Nature Publishing Group},
}

2nd) Then, you add the following configuration to the book section of the toml config file:

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

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

3rd) Finally, you are ready to create references/citations in your markdown files to the citation-keys in the .bib file using the following syntax:

\

For now, only authors, title and date are shown in the generated bibliography, but any other field can be added with very few effort.

This is how the Bibliography is shown in the generated html book:

Bibliography

Bibliography With Abstract

And a citation is shown like this:

Citation

After I had the code, some critical tests for the new feature, and everything formated as required by the mdBook, I opened a new issue for the feature and I pushed a new PR with my implementation

If someone else finds it interesting, maybe it’ll go in the main branch at some point.