33

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?

  • 2
    I don't use pandoc for this kind of conversion, so apologies if I'm way off, but I thought you needed to use the pandoc-citeproc filter..? – jon May 22 '14 at 21:25
  • 2
    @jon If I just add the filter this does not give me the desired output. Maybe I'm misunderstanding pandoc-citeproc. – clstaudt May 23 '14 at 5:41
  • Maybe. What is the desired output? I think the default is something like (biblatex) authordate. But that is only one of many possible bibliographical outputs, and may not be what you are looking for. I don't know how MWEs should look for a markdown-to-LaTeX document, but your original question does not give any indication about what 'style' you need. And bibliographies are, fundamentally, idiosyncratic to say the least.... – jon May 23 '14 at 6:30
  • 2
    @jon My desired output is described above. It is simple text replacement. Pandoc does not need to look at a bibtex file to produce it. – clstaudt May 23 '14 at 7:45
  • 4
    @jon It seems that your comments should be an answer – egreg Jul 5 '14 at 23:18
16

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:

Screenshot of resulting PDF, "stuttgart-media-university---csl.pdf"

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.

  • Does this work with the --biblatex or --natbib options? – sid-kap Feb 1 '17 at 15:36
  • 1
    "If you want to use citations, you also have to define the CSL-style" I don't think this is completely true. You have to use the pandoc-citeproc filter which uses a default CSL file. Defining a CSL file is optional. Please correct me if I'm wrong. – Khalid Hussain Feb 22 '17 at 17:29
  • @KhalidHussain: You may be right... however I cannot tell from the top of my head. It should be easy to verify: just use the command I've given, and skip the --csl=... parameter altogether. If it works without an error printed out, and if the result shows citations, then you'll see a/the default CSL style it used. – Kurt Pfeifle Feb 22 '17 at 18:21
  • 2
    "By default, pandoc-citeproc will use the Chicago Manual of Style author-date format." – Pandoc Manual – Khalid Hussain Feb 22 '17 at 18:32
9

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:

  • Will this work with markdown-style references? (like [-@myref])? Or do I have to use autocite? – sid-kap Feb 1 '17 at 15:35
4

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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.