Managing Citations and Bibliographies in Markdown with Pandoc

Quick answer

Write your citations as @key or [@key] right in your Markdown, point Pandoc at a bibliography file, and it replaces every key with a properly formatted in-text citation and appends a matching bibliography. Pick the format — BibTeX, CSL JSON, CSL YAML, or RIS — pick a citation style, and Pandoc's citation processor, citeproc, handles the formatting.

Here's why that's worth doing over the alternative. A word processor buries your citations inside proprietary fields that break the moment you switch software or hand a draft to a collaborator. A citation key typed as plain text stays readable, greppable, and diffable in version control — you can see exactly what changed between drafts, down to which sources came and went.

Step-by-step

1. Write citation keys inline as you draft

The basic syntax uses @ followed by an identifier. In-text: @foo says.... Parenthetical: [@foo]. To cite more than one source at once, separate the keys with a semicolon:

Plain text formats outlast proprietary ones because they require no
special software to read [@doe99; @smith2000].

Already named the author in your sentence? Suppress it with a minus sign so you're not repeating yourself: [-@smith04]. Add a locator — a page number, chapter, or range — right after the key: [@smith04, chap. 1] or [@doe99, pp. 33-35]. And if a locator or suffix ever gets misread as part of the citation, wrap it in curly braces to force the parsing you want: [@smith{ii, A, D-Z}, with a suffix].

2. Supply the bibliographic data

Pandoc reads bibliographic entries in five formats: BibTeX, BibLaTeX, CSL JSON, CSL YAML, or RIS. This data usually comes from a reference manager — Zotero, EndNote, and Mendeley can all export to one of these — though for a short piece it's just as easy to write a handful of entries by hand in CSL YAML.

Sources started life as a Word document or Google Doc instead of a reference manager? Converting Word and Google Docs to Markdown with Pandoc covers getting the surrounding prose into Markdown before you wire up citations.

3. Point Pandoc at the bibliography and a citation style

From the command line:

pandoc --bibliography refs.bib --csl ieee.csl input.md -o output.pdf

--bibliography names the file with your entries; repeat the flag to combine multiple files. --csl names the style sheet that controls how citations and the bibliography get formatted. Set both the same way in the document's own YAML front matter instead, if you'd rather not type flags every time:

---
bibliography: refs.bib
csl: ieee.csl
---

Leave csl out entirely and Pandoc quietly defaults to chicago-author-date — easy to forget, and an easy way to end up with a style you didn't intend. For a short document with only a few sources, skip the external file altogether and embed the entries directly:

---
references:
  - id: doe2020
    type: article-journal
    author:
      - family: Doe
        given: Jane
    title: An Example Title
    issued:
      date-parts: [[2020]]
---

4. Render and check the output

Run Pandoc to produce your final format — PDF, DOCX, or HTML. Once citations render correctly, exporting Markdown to PDF or Word with Pandoc covers that conversion step in more detail. Before you call it done, check three things: no literal [@key] text left unresolved anywhere in the output, a bibliography appended at the end, and a style that actually matches what's required — a journal's house style, a course's citation guide, your publisher's rules.

Common problems and fixes

A citation key doesn't resolve. The key in your Markdown doesn't match the id field in the bibliography exactly — this comparison is case-sensitive. Open the bibliography file and check the id character-for-character.

The bibliography doesn't appear at all. Older Pandoc versions need an explicit --citeproc (or -C) flag to turn citation processing on; newer versions enable it automatically once a bibliography is present. Also confirm bibliography: points to a path that actually resolves from wherever you're running the command.

The wrong citation style renders. Almost always this means --csl wasn't specified, so Pandoc silently fell back to chicago-author-date instead of the style you needed. Pass the .csl file that matches your target style explicitly.

A locator gets swallowed into a suffix. Ambiguous punctuation after the key confuses the parser. Curly braces fix it: [@smith, {pp. iv, vi-xi} with suffix here] keeps the suffix separate from the locator.

Sometimes what you actually need isn't a formal citation at all — a blog post referencing an article, say, rather than an academic paper citing a source. For that, reference-style links are a lighter-weight option.

Frequently Asked Questions

What citation formats can Pandoc read?

Pandoc's citation processor (citeproc) accepts bibliographic data in BibTeX, BibLaTeX, CSL JSON, CSL YAML, or RIS. Most reference managers, including Zotero, EndNote, and Mendeley, export to at least one of these, so you rarely have to hand-write entries.

What citation style does Pandoc use by default?

If you don't specify a CSL stylesheet with --csl or the csl: metadata field, Pandoc falls back to chicago-author-date. Thousands of other styles, including APA, MLA, IEEE, and journal-specific ones, are available as .csl files you can point to instead.

Can I put my bibliography directly in the Markdown file instead of a separate .bib file?

Yes. For short documents, add a references: field to your YAML front matter with a list of CSL-YAML entries (id, type, author, title, issued date). No external file needed — useful for a single blog post or note with a handful of sources.

How do I cite a source without showing the author's name?

Put a minus sign before the @ key, like [-@smith04]. This suppresses the author from the rendered citation, which is useful when you've already named the author in the sentence.

How do I add a page number or chapter to a citation?

Add a locator after the key, separated by a comma: [@smith04, chap. 1] or [@doe99, pp. 33-35]. Pandoc parses common locator terms like p., pp., and chap. automatically.

Doing this with Carets

A citation-heavy Markdown draft is still, first, a Markdown file — and that's where Carets fits. Syntax highlighting makes a malformed @key or an unclosed bracket easy to spot before you ever run Pandoc, instead of finding out from a build error later. Files, projects, and tags keep a paper's draft and its .bib or CSL-YAML references organized side by side, instead of scattered across apps.

One scope note, to be fair about it: Carets doesn't run Pandoc for you — that conversion step still happens on the command line. What it gives you is a fast, native place on iPhone, iPad, and Mac where the citation-heavy draft itself stays plain text and stays clean, right up until you're ready to render it.

Carets is free on the App Store for iPhone, iPad, and Mac.

Conclusion

The whole workflow comes down to two halves: citation keys typed as plain text while you write, and a bibliography file plus a CSL style that Pandoc uses to format them on export. Set the bibliography and style up once, and reusing that same setup across future articles, chapters, or drafts costs you almost nothing.