Markdown Citation Syntax Tutorial

When writing technical docs or academic papers, you often need to mark "this claim comes from a specific paper" or "this data is from a report." Markdown itself doesn't have a dedicated citation syntax, but through Markdown footnotes and Pandoc extensions, you can handle everything from simple references to full bibliography management.

This article covers how to do citations in Markdown — starting with the basic footnote approach, then moving to the more powerful Pandoc citation syntax.

Footnote Citations: The Simple Approach

If you only need a few citations here and there, Markdown footnotes work just fine. Put the citation details directly in the footnote definition:

This study shows that code reviews effectively reduce defect rates.[^smith2020]

[^smith2020]: Smith, J. (2020). *Code Review Practices in Large-Scale Software Development*. IEEE Software, 37(4), 78-85.

When rendered, you get a superscript number like ¹ in the text that links to the reference at the bottom of the page.

The upside is simplicity — GitHub, GitLab, Obsidian, and Typora all support the [^1] footnote syntax. The downside is that you have to manually format each citation. Every APA-formatted reference? You're typing it out yourself.

Honestly, for five or six citations, footnotes are perfectly fine. But when you're writing a paper with dozens of references, manually managing formats becomes a nightmare. That's where Pandoc citation comes in.

Pandoc Citation Syntax: @key References

Pandoc is a powerful document converter that extends Markdown with a dedicated academic citation system. The core is the @ symbol.

Basic Usage

Use @citationKey in your text to cite a source:

Code reviews have a significant impact on software quality [@smith2020].

According to @smith2020, code reviews can reduce defects by 60%.

The difference between the two forms:

• [@smith2020] — parenthetical citation, renders as (Smith, 2020)
• @smith2020 — narrative citation, renders as Smith (2020), flows naturally in a sentence

Adding Prefixes and Suffixes

You can add prefixes and suffixes inside bracketed citations:

Multiple studies have confirmed this [see @smith2020; also @jones2019, ch. 3].

The data shows a 30% increase [@smith2020, p. 45].

Rendered output:

• (see Smith, 2020; also Jones, 2019, ch. 3)
• (Smith, 2020, p. 45)

Citing Multiple Sources

Separate multiple citations with semicolons:

[@smith2020; @jones2019; @wang2021]

These get sorted according to your chosen citation style. For example, APA format produces (Jones, 2019; Smith, 2020; Wang, 2021).

Suppressing the Author

Sometimes you've already mentioned the author's name and just want the year:

Smith notes that [-@smith2020] code reviews are critical.

The -@ prefix suppresses the author, rendering only (2020).

Preparing a BibTeX File

The key to Pandoc citation is the .bib file — a plain-text bibliography database. Each entry looks like this:

@article{smith2020,
  author  = {Smith, John},
  title   = {Code Review Practices in Large-Scale Software Development},
  journal = {IEEE Software},
  volume  = {37},
  number  = {4},
  pages   = {78--85},
  year    = {2020}
}

@book{jones2019,
  author    = {Jones, Mary},
  title     = {Software Quality Assurance},
  publisher = {Springer},
  year      = {2019}
}

The strings in braces — smith2020, jones2019 — are the citation keys you use in your text. The naming convention is typically "author+year" or any meaningful string, as long as the keys in your text match the ones in the .bib file.

I learned this the hard way: once I exported a BibTeX file from Zotero and the citation keys contained spaces (like @smith 2020). Pandoc simply couldn't recognize them. After changing all keys to space-free format (smith2020), everything worked. If you're also exporting from Zotero, I recommend installing the Better BibTeX plugin — it automatically generates properly formatted citation keys.

Ways to Get BibTeX Entries

Generating Bibliography with Pandoc

With your .md and .bib files ready, one command generates a document with full bibliography:

pandoc document.md \
  --citeproc \
  --bibliography=refs.bib \
  -o output.pdf

Key parameters:

• --citeproc — enables citation processing (replaces the older --filter pandoc-citeproc)
• --bibliography=refs.bib — specifies the BibTeX file path
• -o output.pdf — output format (also supports .html, .docx, etc.)

Pandoc automatically:

1. Replaces @key references in the text with formatted citations
2. Generates a complete bibliography (References) at the end
3. Links in-text citations to the bibliography entries

Specifying a Citation Style

Use the --csl parameter to switch citation formats:

pandoc document.md \
  --citeproc \
  --bibliography=refs.bib \
  --csl=apa.csl \
  -o output.pdf

CSL (Citation Style Language) files are available for free from the Zotero Style Repository, with over 10,000 styles. Common ones:

Citation Toolchain Comparison

Besides Pandoc itself, several toolchains support Markdown citations:

Quarto is essentially a user-friendly wrapper around Pandoc — the syntax is identical, but configuration is simpler. If you don't want to deal with command-line flags, Quarto is a solid choice. Just set up bibliography and csl in your _quarto.yml file, and you never need to type a pandoc command manually.

Footnotes vs Citations: When to Use Which

These two are easy to confuse, so here's a quick breakdown:

My recommendation:

• Writing blog posts, READMEs, tech docs → use footnotes [^1], simple and sufficient
• Writing papers, research reports, books → use Pandoc citation @key, automatic formatting
• Discussing academic topics on GitHub → use footnotes with manually written citation format (GitHub doesn't support Pandoc citation)

FAQ

Can I use @key citations on GitHub?

No. GitHub's Markdown renderer doesn't support Pandoc citation syntax. On GitHub, you can only use footnotes:

According to the study[^1], this approach is viable.

[^1]: Smith, J. (2020). *Code Review Practices*. IEEE Software, 37(4), 78-85.

Pandoc says it can't find a citation key — what do I do?

Check these things:

1. Are the keys in your .bib file identical to the @key references in your text? (They're case-sensitive)
2. Is the file path in --bibliography correct?
3. Does your .bib file have syntax errors? (extra commas, missing braces, etc.)

How do I do academic citations in Obsidian?

Obsidian natively only supports footnotes [^1] — it doesn't recognize Pandoc's @key syntax. But you can use community plugins:

• Pandoc Plugin — call Pandoc directly from Obsidian to export documents with citations
• Citations Plugin — connect to your Zotero database, search and insert citations within Obsidian

How do I change the citation style?

Just point --csl to a different .csl file. For example, switching from APA to IEEE:

pandoc doc.md --citeproc --bibliography=refs.bib --csl=apa.csl -o output.pdf

# IEEE format
pandoc doc.md --citeproc --bibliography=refs.bib --csl=ieee.csl -o output.pdf

Same document, different CSL file — the citation format and bibliography list adjust automatically.

References

• Pandoc Manual — Citations — the authoritative reference for Pandoc citation syntax
• Quarto Documentation — Citations & Footnotes — Quarto's citation system
• Citation Style Language — the CSL specification
• Markdown Guide — Extended Syntax: Footnotes — community reference for Markdown footnote syntax
• Zotero Style Repository — over 10,000 CSL citation styles