GitHub: add autogenerated Bibliography to the ReadMe file of your GitHub repository

I was working on my last project, when I had to deal with the ReadMe file of the GitHub repository. That project should be a kind of data structure for environmental modeling purposes, and in scientific fields you always have to cite papers, reports and things like those.

However a simple ReadMe.md is not built or parsed by anything, then a problem rises: should I have to write the biblioraphy (or references) by hand, typing each single character? Naaaaaa, I’m too lazy for that.

What’s the solution? Pandoc!

From Wiki, Pandoc is an open-source document converter, widely used as a writing tool, it can export many many different types of formats and, while parsing the source text, it can easily generate the bibliography from your .bib file.

To get a working tools, you should install:

yaourt -S pandoc pandoc-citeproc

The trick is add the citation between square brackets and after the at @ symbol in the following way:

[@david2013:software]

where david2013:software is the corresponding key from the bibliography file, inside your text written with MarkDown syntax and then convert it to reStructuredText, linking your original .bib file.

pandoc localReadMe.md -o ReadMe.rst --bibliography=path/to/biblio.bib

The .rst file just generated is parsable by GitHub, and it is the one you will push on the online repository…with the bibliography automatically generated!
What I strongly suggest is to add the title ## References at the end of your MarkDown text, because the bibliography is automatically added at the end of it.

Enjoy! GWH!

Here the source code in MarkDown format as example:

# RiverNe3

`@author` Francesco Serafin (sidereus3), [email protected]

`@copyright` GNU Public License v3 AboutHydrology (Riccardo Rigon)

## Description

This component (which is not part of OMS <em>[@david2013:software]</em> yet) is an abstract schematization of a river network through a tree data structure, in order to parallel process independet HURs.
[...]

#### Decorator Pattern

The *decorator pattern* was implemented to allow each developer to write her/his own plain tree (e.g. `RiverBinaryTree.java` useful to abstract a simple river network <em>[@wang2011:common]</em>), implementing the interfa

Once you have your own plain tree, you can decorat it writing a *decorator* (e.g. `Hydrometers.java`), extending the `BinaryTreeDecorator.java` abstract class.
[...]

## References

And the parsed source file in .rst

My .bib file is available at https://github.com/sidereus3/LaTeX.