How to cite sources in Markdown
Try it — edit the markdown and watch the preview
Result
Markdown has no citation syntax. There are three ways to cite anyway, and which one is right depends entirely on whether a build step is involved.
Footnotes: portable, manual
The estimate has been disputed.[^weber]
[^weber]: Weber, K. (2024). *Counting things badly*.
Journal of Approximation, 12(3), 44–61.
The marker can be any label — [^1], [^weber], [^see-also] — and the
definition can sit anywhere in the file. Renderers collect them at the foot of
the page and number them in order of first use, so moving a paragraph
renumbers everything correctly without you touching it.
This works on GitHub, in most static site generators and in the editor on this page. You write each reference yourself and you keep the list consistent yourself, which is fine for a dozen and tedious past fifty.
Pandoc: the real answer, with a build step
The estimate has been disputed [@weber2024, p. 47].
Others disagree [@lin2023; @okafor2025].
Pandoc resolves each key against a bibliography file, formats the citation to a CSL style, and generates the reference list. Declare the file in front matter:
---
bibliography: references.bib
csl: apa.csl
---
Then build with pandoc --citeproc. Swap the CSL file and the same document
reformats from APA to Chicago to Vancouver without a single edit to the prose —
which is the entire point, and something no manual method gives you.
The cost is that the file is no longer self-contained. [@weber2024] is
meaningless without references.bib, and it renders as literal text anywhere
Pandoc is not running — including GitHub.
By hand: a References section
## References
- Weber, K. (2024). *Counting things badly*. Journal of Approximation.
- Lin, S. (2023). [A better count](https://example.com/paper).
Unfashionable and often correct. It renders everywhere, needs no tooling, and for a design document, a report or a README with six sources it is the fastest route to something readable.
Which to use
| Situation | Use |
|---|---|
| A README or a GitHub document | Footnotes, or a References list |
| A thesis, paper or anything with a style guide | Pandoc with --citeproc |
| A docs page with a handful of sources | A References list |
| Quarto or R Markdown | Pandoc syntax — it is already there |
| Obsidian | A Zotero plugin, or footnotes |
Citing a repository
GitHub reads a CITATION.cff file in the repository root and shows a
“Cite this repository” button from it, offering APA and BibTeX. It is YAML
rather than Markdown and takes about five minutes:
cff-version: 1.2.0
title: clockwise
authors:
- family-names: Weber
given-names: Kim
version: 2.1.0
date-released: 2026-07-14
Worth doing for anything academic or research-adjacent, and invisible effort otherwise.
Common questions
- Does Markdown support citations?
- Not on its own. There is no citation syntax in CommonMark or GitHub Flavored Markdown. Pandoc adds one, and it is the method serious academic writing uses — but it needs Pandoc, a bibliography file and a build step, none of which are Markdown.
- What is the Pandoc citation syntax?
- A key in square brackets prefixed with an at sign — `[@weber2024]` — optionally with a locator, `[@weber2024, p. 47]`. Pandoc resolves it against a `.bib`, `.json` or `.yaml` bibliography and formats it with a CSL style, then generates the reference list for you.
- What works without Pandoc?
- Footnotes. `[^key]` in the text and `[^key]: the full reference` anywhere in the document renders on GitHub, in most static site generators and here. You write and order the references yourself, which is fine for a document with a dozen of them and painful past fifty.
- How do I cite in a README or on GitHub?
- Footnotes, or a References section of ordinary links. GitHub does not run Pandoc, so `[@key]` renders as literal text. For a repository citing itself, GitHub also reads a `CITATION.cff` file and shows a "Cite this repository" button from it.
- Which bibliography format should I use?
- BibTeX (`.bib`) if you already have one — every reference manager exports it. CSL JSON is the format Pandoc prefers internally and handles edge cases more predictably. Both work; the choice matters less than keeping one file rather than three.
- Can Obsidian or Quarto do this?
- Quarto uses Pandoc directly, so the syntax works as documented. Obsidian needs a plugin — usually one bridging to Zotero — because Obsidian's own renderer has no citation support.