Skip to content

Notes & citations

Two kinds of supporting text look similar on the page but come from different places: notes you write yourself, and citations to sources you've collected. They're controlled by different levers — keep them separate and the whole system stays simple.

  • A note you wrote → a footnote (or endnote). You own the text.
  • A pointer to a source → a citation ([@key]). A citation style decides how it reads.

Footnotes and endnotes

Write notes with Pandoc's footnote syntax. The reference form puts a marker in the text and the note below; label it with a name, not a number:

The experiment yielded surprising results,[^dataset] contradicting the model.

[^dataset]: See appendix B for the full dataset.

The inline form keeps a short note right at the marker:

The results were surprising.^[See appendix B for the full dataset.]

Labels are identifiers, not the printed numbers — Pandoc numbers notes for you in document order, so name them for what they are and never hand-number.

Where notes land

The same markers can sit at the bottom of the page (footnotes) or be collected at the end (endnotes). That's one switch — keystone-note-placement in pandoc.yaml — and the authoring syntax never changes:

keystone-note-placement: endnotes   # or: footnotes

You rarely set it, because each target ships the convention its readers expect:

Target Default
book, scrbook endnotes
article, report, scrartcl, scrreprt footnotes

Endnote collection is a PDF feature: EPUB has no fixed pages (notes are always section-end), and DOCX/ODT use their native footnotes. Set the key for the PDF you intend to print; it's harmless elsewhere.

Citations

Three pieces work together: a bibliography file of sources, citations in your text, and a citation style (CSL) that formats them. Add a bibliography and citations turn on; omit it and nothing changes.

Citations are a native Pandoc feature. This covers the common cases; Pandoc's citation docs have the complete syntax.

Cite a source

The results were significant [@smith2023, pp. 42-45], confirming earlier
findings [@jones2020; @chen2021].
  • Locator — a page or range after the key: [@smith2023, pp. 42-45]
  • Multiple sources — separate keys with semicolons: [@jones2020; @chen2021]
  • Suppress the author (already named in your prose): [-@smith2023, p. 12]
  • In-text — @smith2023 renders "Smith (2023)…"

The bibliography file

Point bibliography at a BibTeX (.bib) or CSL-JSON file by bare name — Keystone looks in manuscript/, where the file belongs:

bibliography: references.bib

Each entry's key is what you cite with [@key]. Multiple files merge:

bibliography:
  - primary.bib
  - secondary.bib

A referenced file that doesn't exist is a hard error — the build stops and names it, rather than producing silently empty citations.

Citation style

csl controls formatting. Leave it unset for the default. Two Chicago styles ship, selected by bare name:

  • chicago-author-date — the default; renders (Smith 2023) in text
  • chicago-notes-bibliography — renders citations as notes
csl: chicago-notes-bibliography

For any other style (APA, MLA, IEEE, a journal's own), download the .csl from the CSL styles repository, drop it in manuscript/, and name it with the extension:

csl: apa.csl

The .csl suffix is how Keystone tells your file from a shipped style name. link-citations: true (the default) hyperlinks each citation to its entry.

Where the bibliography appears

By default it renders at the end of the document. To place it yourself, add an empty #refs div where you want it:

# References

::: {#refs}
:::

By default the bibliography lists only the entries you actually cite. To list entries you don't cite in the text — a "further reading" section, or a complete works — add them with nocite. Use @* to include every entry in your bibliography file:

nocite: |
  @*

Or name specific keys to add just those, leaving the rest cite-only:

nocite: |
  @smith2023, @jones2020

Either way, the named entries appear in the bibliography as though cited — but no citation marker is added to your text.

How they overlap

The two axes compose. A note-style CSL renders each citation as a note, and keystone-note-placement: endnotes collects every note — including those citation notes — at the back, with the bibliography after them. That's the standard academic layout, and it falls out of the two levers working together with no special configuration.

Format behavior

Format Footnotes Endnotes Bibliography
PDF Bottom of page "Notes" section (chapter- or section-level by target) Typeset at the chosen location
EPUB Section-end Section-end (no fixed pages) HTML section
DOCX / ODT Native footnotes Native footnotes Native bibliography

Citations resolve before any format is written, so every output gets the same citations and a format-native bibliography. Citations fail loudly: a missing bibliography file, an unknown style, or a path where a bare name was expected all stop the build with a message naming the problem.