Why doesn't Pandoc convert citations correctly from Markdown to LaTeX?

Question

Consider the following markdown fragment:

Connecting these native implementations to the Python world is enabled
by the [Cython](http://cython.org/) toolchain  [@behnel2011cython]. 

I use pandoc to convert from markdown to LaTeX:

pandoc --chapters ../Source/Chapters/Content.md -o ../Example/Chapters/Content.tex

This is converted to LaTeX and produces the following output:

Connecting these native implementations to the Python world is enabled
by the \href{http://cython.org/}{Cython} toolchain~
{[}@behnel2011cython{]}. 

Why is the citation not handled appropriately? It should be easy to simply convert it to ~\cite{behnel2011cython}. Did I forget to give pandoc some flag for this?

Answer 1

If you want to use citations, you also have to define the CSL-style (Citation Style Language) to be used, via a *.csl-file you have to reference.

Here is an MWE in Markdown. It tests a few different methods to provide references to citations in Markdown:

# Markdown source code for relevant part of this page

``` {.markdown}
i.  [@nonexistent]
i.  @nonexistent
i.  @z1 says fooo.
i.  @z1 [p. 30] says baaar.
i.  @z1 [p. 30, with suffix] says blahblah.
i.  @z1 [-@z2 p. 30; see also @z3] says blah-blubb.
i.  In a footnote.[^1]
i.  A citation group [see  @z1 p. 34-35; also @z3 chap. 3].
i.  Another one [see @z1 p. 34-35].
i.  And still another, in a footnote.[^2]
i.  Quote with a *suffix* and a *locator* [@z1 pp. 33, 35-37, and nothing else].
i.  Quote with only one locator [@z1 and nowhere else].
i.  Now a few *modifiers*[^3]...
i.  With some extra Markup [*siehe* @z1 p. **32**].
i.  Jane Doz doesnt like me [***siehe*** **@z4**].

[^1]: A citation without locators [@z3].

[^2]: Multiple citations [siehe @z2 chap. 3; @z3; @z1].

[^3]: ...like a quote without author: [-@z1]. And now OStR Oster with a locator [-@z2 p. 44].

$x^2 + y^2 = 1$ @z1
```

# Document output of Markdown code

i.  [@nonexistent]
i.  @nonexistent
i.  @z1 says fooo.
i.  @z1 [p. 30] says baaar.
i.  @z1 [p. 30, with suffix] says blahblah.
i.  @z1 [-@z2 p. 30; see also @z3] says blah-blubb.
i.  In a footnote.[^1]
i.  A citation group [see  @z1 p. 34-35; also @z3 chap. 3].
i.  Another one [see @z1 p. 34-35].
i.  And still anoter, in a footnote.[^2]
i.  Quote with a *suffix* and a *locator* [@z1 pp. 33, 35-37, and nothing else].
i.  Quote with only one locator [@z1 and nowhere else].
i.  Now a few *modifiers*[^3]...
i.  With some extra Markup [*see also* @z1 p. **32**].
i.  Jane Doz doesnt like me [***see*** **@z4**].

[^1]: A citation without locators [@z3].

[^2]: Multiple citations [siehe @z2 chap. 3; @z3; @z1].

[^3]: ...like a quote without author: [-@z1]. And now OStR Oster with a locator [-@z2 p. 44].

$x^2 + y^2 = 1$ @z1

# Bibliography

You convert this Markdown with f.e. the following Pandoc command:

pandoc -V geometry="paperwidth=18cm, paperheight=34cm, margin=0.3cm" \
       -V language=de-DE -V lang=ngerman                             \
       --highlight-style=espresso --filter=pandoc-citeproc           \
       --biblio=my-biblio.bib --csl=stuttgart-media-university.csl   \
       -o stuttgart-media-university---csl.pdf mwe.md

As you can see from the command, it references three files:

1. The Markdown source, mwe.md.
2. An additional file defining the CSL-style to be used, stuttgart-media-university.csl. (I downloaded it from the core repository, of citationstyles.org on GitHub.)

3. The third one, my-biblio.bib, which holds my citation references. Its content is here:

   @Book{z1,
   author="Thales von Milet",
   title="Doppelwinkel-Funktionen",
   url="http://de.wikipedia.org/wiki/Formelsammlung_Trigonometrie#Doppelwinkelfunktionen",
   year="600 v.Chr.",
   address="Milet, Kleinasien",
   publisher="Wikipedia"
   }
   
   @Article{z2,
   author="OStR Dr. math.nat. Oster",
   title="Unterrichtsmaterialen für Klasse 9 (Mittelstufe)",
   year="1969",
   journal="Journal of Generic Studies",
   volume="9",
   pages="33-34"
   }
   
   @InCollection{z3,
   author="Elvis Presley, Madonna and Pink Floyd",
   title="Kombinatorik Hypergeometrischer Verteilungen",
   booktitle="Wiederholungslose Auswahlprobleme",
   editor="Cleopatra, Königin von Ägypten",
   publisher="Steintafeln Moses GmbH & Co. KG",
   address="Gizeh",
   year="30 v.Chr."
   }
   
   @Article{z4,
   author="Jane Doz",
   title="Why All Men Suck",
   year="2006",
   journal="Journal of Gender Studies",
   volume="6",
   pages="33-34"
   }
   

Here is a screenshot of the resulting PDF page:

Looking closely at that page, you can see how exactly each occurrence of Markdown source citational references translate into the final page layout.

Be aware, that the final page layout is heavily influenced by the specific CSL style file you use! Apply a different CSL, and the page content will look different (specifically: the spots with the references, the footnotes and the "Bibliography" section are all influenced by the CSL).

My recently created GitHub repo for testing CSL style files contains even more detailed instructions about this topic.

Answer 2

Just use the flag --biblatex when converting with pandoc:

pandoc --biblatex --chapters ../Source/Chapters/Content.md -o ../Example/Chapters/Content.tex

The result:

Connecting these native implementations to the Python world is enabled
by the \href{http://cython.org/}{Cython} toolchain
\autocite{behnel2011cython}.

You have to use the biblatex package for this to work -- but you really should use it anyway, because it's pretty fantastic: The documentation is excellent, and the package itself is very 'mature'. Here are some relevant questions to get you started:

• biblatex in a nutshell (for beginners)
• What to do to switch to biblatex?
• What is the difference between bibtex and biblatex?

Answer 3

As an alternative to --biblatex you can use --natbib so that LaTeX package 'natbib' commands (e.g. \citep and \citet) are used.