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:
The trick is add the citation between square brackets and after the at @
symbol in the following way:
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.
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:
And the parsed source file in .rst
My .bib
file is available at https://github.com/sidereus3/LaTeX.
So, GitHub picks any
.bib
file that is beside theREADME.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 runningpandoc
?Hi vzeman79,
no, GitHub doesn’t pick and parse any
.bib
file. TheREADME.rst
has been locally generated by the “compiling” of theREADME.md
file withpandoc
and then pushed on the remote repository.francesco
The problem with your solution is that you can’t use README.md and README.rst at the same time because GitHub will always displays README.md first. Except of course if you delete your README.md from the git repo, but that’s really harsh.
I suggest this better alternative :
Name your README.md as README-ORIG.md
pandoc README-ORIG.md -t gfm -o README.md –bibliography=ref.bib
Regards