Citations and Bibliography

Part of the motivation for using Pandoc for this package was that it supports citations and bibliographies through citeproc. Given a markdown document with citations in it and a .bib file, Pandoc can generate a formatted document with citations and a bibliography.

This package maintains some easy-to-use functions for working with citations and bibliographies in markdown documents.

# for demonstration
import tempfile
from IPython.core.display import display, HTML

import sys
sys.path.append('..')
import pymddoc

/tmp/ipykernel_889889/3729719973.py:3: DeprecationWarning: Importing display from IPython.core.display is deprecated since IPython 7.14, please import from IPython display
  from IPython.core.display import display, HTML

Citation Auto-complete

Check out the pandoc citer VSCode plugin for citation auto-complete as you edit your documents.

In the document YAML header, you will need to provide the bibliography attribute.

markdown_text = '''
---
title: "Hello World"
bibliography: ["data/references.bib"]
---
Use citations like this [@Angelou1969] or this [-@Cohen1963]. These will auto-complete if you use the VSCode plugin.
'''.strip()

Compiling Documents with Citations

Most importantly for our purposes, we should be able to compile a document that includes citations automatically from a database. We can do this by specifying the citeproc_bibliography argument in PandocArgs. This argument should be a path to a .bib file.

In this example I write the bibtex data to a temporary file which is then used to compile the document.

bib_file_text = '''
@book{Angelou1969,
    place={New York},
    edition={1},
    title={I Know Why the Caged Bird Sings},
    ISBN={9780375507892},
    publisher={Random House},
    author={Angelou, Maya},
    year={1969},
    month={Jan.}
}
@article{Cohen1963,
    author = "P. J. Cohen",
    title = "The independence of the continuum hypothesis",
    journal = "Proceedings of the National Academy of Sciences",
    year = 1963,
    volume = "50",
    number = "6",
    pages = "1143--1148",
}
'''

md_file_text = '''
Use citations like this [@Angelou1969] or this [-@Cohen1963].
'''.strip()

with tempfile.TemporaryDirectory() as tmpdir:
    bib_fname = tmpdir + '/refs.bib'
    with open(bib_fname, 'w') as f:
        f.write(bib_file_text)


    doc = pymddoc.MarkdownDoc.from_str(md_file_text)
    html = doc.render_html(
        pandoc_args=pymddoc.PandocArgs(
            citeproc_bibliography=bib_fname,
        )
    )
display(HTML(html))

Use citations like this (Angelou 1969) or this (1963).

Angelou, Maya. 1969. I Know Why the Caged Bird Sings. 1st ed. Random House.

Cohen, P. J. 1963. “The Independence of the Continuum Hypothesis.” Proceedings of the National Academy of Sciences 50 (6): 1143–48.

You can change the bibtex file if you have any issues with the citation information.