This tool allows working with Bibtex-style bibliographies for Markdown files. It requires two inputs: (i) a markdown file which supports a custom syntax (described below) to include bibtex references, and (ii) a bibtex-style bibliography file.
It generates another markdown file as output, which has all the custom syntax replaced appropriately using references from the bibliography. This output markdown file can then be directly rendered or converted to other formats (say with pandoc).
The tool has been written for Ubuntu and tested on Python v3.5 and above but is also compatible with previous and newer versions of python3.
Requires python3, the re
and argparse
packages from Python Standard Library and the bibtexparser
package (available via pip):
pip install bibtexparser
This tool has been written primarily for the purpose of maintaining academic reading lists in Github Flavored Markdown (GFM). The tool can be run as a Python script, e.g.:
python3 md_with_bib.py <infile> -b <bibfile> -o <outfile>
It accepts the following command-line arguments:
infile: Path of input markdown file.
-b, --bibfile: Path of bibtex-style bibliography file. Default: 'biblio.bib'.
-o, --outfile: Path of output markdown file. Default: 'result.md'.
To refer attributes of a bibtex reference, the following syntax can be used anywhere in the input markdown file:
[@<bib_ref_ID>:<bib_ref_cmd>]
where <bib_ref_ID>
is the unique bibtex ID of the reference and <bib_ref_cmd>
is the command to be executed for the reference.
Currently the following commands are supported for <bib_ref_cmd>
:
title
: Displaytitle
attribute of the reference (see Note 1 below).subtitle
: Displaysubtitle
attribute of the reference (for bibentries of typebook
).journal
: Displayjournal
attribute of the reference (for bibentries of typearticle
).author
: Displayauthor
attribute of the reference (in et al. format; see Note 2 below).authors
: Display full list of authors for the reference (see Note 2 below).cite
: Displays a label for the reference in <Author et al., year> format and inserts the full citation for that reference in the reference list at the bottom of the output markdown file (see Note3 below).booktitle
: Display thebooktitle
attribute of the reference (for bibentries of typeinproceedings
).series
: Display theseries
attribute of the reference.month
: Display themonth
attribute of the reference.year
: Display theyear
attribute of the reference.citation
: Displays the full citation for the reference. Unlike thecite
command which adds a label at the location of the custom syntax and the actual citation in the references at the bottom, thecitation
command adds the full citation at the location of the custom syntax.URL
: Display theURL
attribute of the reference.full
: Displays the reference like a header with a title in the current line, followed by the full list of authors in the subsequent line, followed by a few other attributes and the year in the next line.
Note that even though bibtex supports citations for many entry types, this tool mostly focuses on the following entry types: inproceedings
, article
, book
, phdthesis
and mastersthesis
. When citing other entry types it still produces a basic citation with the author
, title
and year
fields (see Note 4 below).
For a working example which uses the custom syntax with a variety of the above commands, execute the following on the command-line:
python3 md_with_bib.py example/input.md -b example/biblio.bib -o example/output.md
The above uses the sample input files in the example folder. A copy of the generated output file (output.md) is already present in the example folder for reference.
The title of any reference is automatically linked to its URL (if provided for the reference in the bibtex file). This is true regardless of whether the title is refered to individually via title
command or as a part of a citation.
For bibentries of type book
, the editor
attribute in --bibfile
is checked before the author
attribute when using author
or authors
command for <bib_ref_cmd>
. Exactly one of editor
or author
attributes is expected for bibentry of type book
. If both are provided, the editor
attribute overrides author
.
Since academic documents often require multiple citations simultaneously, the above custom syntax allows having multiple cite
commands in a single pair of square brackets. Such references should be separated by semi-colons. Note that multiple references in a single pair of square brackets are only allowed for the cite
command. All other commands must have a square bracket of their own. In any square bracket containing multiple commands, all commands are treated as cite
regardless of what the actual commands are.
Example 1 - Valid multiple cite
commands in a single square bracket:
Many more advancements have been made along these lines [@zenke2014:cite; @silver2011:cite].
Example 2 - Invalid multiple commands in a single square bracket:
Many more advancements have been made along these lines [@zenke2014:author; @silver2011:title]
is still treated as:
Many more advancements have been made along these lines [@zenke2014:cite; @silver2011:cite].
For citation purposes, every bibentry must have at least the following attributes: author
(or editor
for entry of type book
), title
and year
. Additionally entries of type inproceedings
must have a booktitle
attribute and entries of type article
must have a journal
attribute.