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.

About Francesco Serafin

I am a PhD student at the Department of Civil, Environmental and Mechanical Engineering at the University of Trento. My two greatest loves: Computer Science and Water (take three with my Lenovo!:D). As a result, the aim of my life is to make both passions coexist. My gpg public key available at https://pgp.mit.edu

2 thoughts on “GitHub: add autogenerated Bibliography to the ReadMe file of your GitHub repository

  1. So, GitHub picks any .bib file that is beside the README.rst file and uses it to produce the citations? How do you configure the citations style? Or am I misunderstanding this and you have generated the citations by manually running pandoc?

    • Hi vzeman79,

      no, GitHub doesn’t pick and parse any .bib file. The README.rst has been locally generated by the “compiling” of the README.md file with pandoc and then pushed on the remote repository.

      francesco

Leave a Reply

Your email address will not be published.

*