Markdown Citations: Add References and a Bibliography

A markdown citation can mean three different things. It might be an academic reference with a generated bibliography, a numbered footnote that works on GitHub, or a source line under a quote. Pandoc's [@key] syntax handles the first, [^1] footnotes handle the second, and a blockquote with an attribution handles the third. This guide routes you to the right one, gives a copy-paste APA template, and shows where each syntax renders.

Which Kind of Markdown Citation Do You Need?

Markdown itself has no citation syntax. CommonMark defines links, and footnotes arrive with GFM and most extensions. Real citations (a key in the text that becomes "(Smith 2020)" plus a formatted reference list) come from Pandoc's citeproc. Searches for markdown cite, references markdown, and markdown citation all land on the same three answers, so pick by where the file will be rendered.

You want	Use	Renders in
Author-date or numbered citations with a bibliography	Pandoc [@key] plus a .bib file and --citeproc	Pandoc, Quarto, R Markdown, MyST, Obsidian with a plugin
Numbered references that work on GitHub	Footnotes [^1]	GitHub, GitLab, Obsidian, most editors
A manual "References" list	Reference-style links and a numbered list	Everywhere
A source under a quotation	Blockquote plus an attribution line	Everywhere

The rest of the post takes them in order of portability, starting with the two that need no build step, then the Pandoc workflow that produces a real bibliography.

Markdown References With Footnotes and a Reference List

For a README, an issue, or a blog post, numbered footnotes are the most portable way to put references in Markdown. Put [^1] after the claim and define [^1]: anywhere in the file; the renderer collects the definitions at the bottom.

Markdown was released in 2004 by John Gruber.[^1]

[^1]: Gruber, J. (2004). *Markdown*. https://daringfireball.net/projects/markdown/

GitHub's formatting docs confirm the footnote's position in the source doesn't affect where it renders, and note the one gap: footnotes don't work in GitHub wikis. The Markdown footnotes guide covers multi-line notes and the platforms that skip them.

When footnotes aren't available, a manual list still reads as a bibliography. Reference-style links keep the URLs out of the prose:

Gruber first described the format in 2004 [1].

## References

1. Gruber, J. (2004). *Markdown*. Retrieved from [daringfireball.net][gruber2004]

[gruber2004]: https://daringfireball.net/projects/markdown/

The Markdown links guide explains reference-style definitions in full. This method has one cost: you number and format every entry by hand, and renumbering after an insert is your job. It's still the right call for a short README with three sources, where a build step would be overkill.

How Do You Cite a Quote in Markdown?

The Stack Overflow question behind much of this search traffic is simpler: how do you attribute a quotation? Use a blockquote for the quote and a final line for the source, either as plain text or as an HTML <cite> element around the title of the work.

> Simplicity is prerequisite for reliability.
>
> Edsger W. Dijkstra, <cite>How do we tell truths that might hurt?</cite> (1975)

MDN describes <cite> as the element for the title of a creative work, so wrap the book or paper title in it rather than the person's name. Most renderers show it in italics. Renderers that strip unknown HTML just show the text, which still reads correctly. The Markdown blockquote guide covers nested and multi-paragraph quotes.

Try a Reference List and Quote Attribution in the Editor

The sample below uses the two methods that render everywhere: a manual reference list built from reference-style links, and an attributed blockquote. Footnotes and Pandoc keys are left out on purpose. Our editor's preview, like any renderer without a footnote extension or citeproc, shows [^1] and [@key] as typed, so test those on GitHub or with Pandoc. The last line of the demo shows what that looks like.

For a PDF of a document that uses the manual list, the Markdown to PDF converter exports it without a LaTeX install.

Academic Citations With Pandoc Citeproc

For a paper, thesis, or anything with an APA or Chicago reference list, Pandoc is the tool. Since version 2.11 (October 2020) citation processing is built in: the --citeproc flag replaced the old pandoc-citeproc filter, according to the release notes. The workflow has four parts.

1. A bibliography file. Pandoc reads BibLaTeX (.bib), BibTeX (.bibtex), CSL JSON (.json), and CSL YAML (.yaml). Export one from Zotero, Mendeley, or by hand:

@article{smith2020,
  author  = {Smith, Jane},
  title   = {Plain Text Publishing},
  journal = {Journal of Documentation},
  year    = {2020},
  volume  = {12},
  pages   = {1--20}
}

2. Citations in the text. The Pandoc manual defines the forms:

Plain text wins [@smith2020].
Smith argues the same [@smith2020, pp. 12-15].
@smith2020 says the format is durable.
Published that year [-@smith2020].
Two sources [see @smith2020, chap. 1; @doe2019].

[@key] gives a parenthetical citation, @key a narrative one, [-@key] suppresses the author, and a semicolon separates multiple keys. Locators such as p., pp., and chap. are recognised from the CSL locale.

3. Metadata in the YAML header.

---
title: Plain Text Publishing
bibliography: refs.bib
csl: apa.csl
---

Without a csl field Pandoc uses Chicago author-date. The apa.csl file, and thousands of others, come from the CSL styles repository; download the one you need next to the document.

4. The command.

pandoc paper.md --citeproc -o paper.pdf

Citeproc replaces each [@key] with the formatted citation and appends a bibliography at the end of the document. Add a ## References heading as the last line if you want a title above it.

We prefer this route over hand-written reference lists for anything longer than a blog post. Changing from APA to Chicago is one line in the header rather than an afternoon of retyping. The Markdown to PDF guide covers the rest of the Pandoc PDF pipeline.

APA Reference List Template for Markdown

If you can't run Pandoc, this is the manual APA fallback that renders anywhere. Copy it, swap in your sources, and keep the entries in alphabetical order by author.

Recent work supports this reading (Smith, 2020, p. 12; Doe & Lee, 2019).

## References

Doe, A., & Lee, B. (2019). *Writing in plain text*. Example Press.

Smith, J. (2020). Plain text publishing. *Journal of Documentation*, 12(1), 1-20. https://doi.org/10.0000/example

Italics on the book title and the journal name follow APA 7. Markdown can't do a hanging indent, so entries sit flush left; a blank line between them keeps each one a separate paragraph.

Write the DOI as a full https://doi.org/ URL rather than a bare identifier. Most renderers autolink it, and readers get a clickable reference in the HTML or PDF output. If you later move the document to Pandoc, the same entries convert to a .bib file with a few minutes of work, so nothing here is wasted.

Where Does Markdown Citation Syntax Render?

Pandoc's @key syntax is an extension, so most renderers print it as typed. This table is drawn from each platform's docs and, for our editor, from its renderer.

Platform	[@key] citations	[^1] footnotes	Notes
Pandoc	Yes, with --citeproc	Yes	Default style Chicago author-date
Quarto	Yes	Yes	Same bibliography and csl fields, Quarto docs
R Markdown	Yes	Yes	Same fields in the YAML header, see the R Markdown cheat sheet
MyST	Yes	Yes	Reads BibTeX and resolves DOI links
Obsidian	With a plugin	Yes	Citations plugin (last release 0.4.5, Sept 2022) or Pandoc Reference List
GitHub, GitLab	No, literal text	Yes	Footnotes are the answer here
VS Code preview	No	With an extension	The built-in preview needs the Markdown Footnotes extension
Our editor	No, literal text	No, literal text	Use the manual reference list

In Obsidian, the community Citations plugin (last release 0.4.5, September 2022) inserts keys from a Zotero export. The Pandoc Reference List plugin shows a formatted reference panel beside the note. Neither changes what GitHub does with the file. Quarto and R Markdown need no plugin at all, since both hand the document to Pandoc with the same bibliography and csl fields.

The limitation to plan around: a file written for Pandoc looks broken on GitHub, with [@smith2020] sitting in the prose. If the same document must render in both places, write footnotes and accept manual formatting, or keep the Pandoc source in a branch that only produces the PDF.

Common Markdown Citation Mistakes

Expecting [@key] to render without citeproc. Running pandoc paper.md -o paper.pdf leaves the keys as text. Add --citeproc and a bibliography field; without both, nothing happens.

Using <cite> for the author's name. The element marks the title of the work. Put the name in plain text and the title inside the tag.

Mixing footnote numbers and citation keys. [^smith2020] is a footnote label, not a citation; it renders as a superscript number and needs a [^smith2020]: definition. Citation keys use @.

Markdown Citations FAQ

Match the method to the destination. Use footnotes and an attributed blockquote for anything that lives on GitHub or GitLab, and Pandoc's [@key] plus a .bib file when you need a formatted bibliography. Whichever markdown citation style you settle on, test the manual list and the attributed quote in the editor first, then run the Pandoc build for the academic version.