Citations

Scholarly reads a local BibTeX file, collects the keys cited in your slides, and builds a reference list. Set up the bibliography file first, then add citations and a reference slide. Manual notes and Markdown footnotes are described separately below.

Configuration

Configure citation settings in your frontmatter:

---
theme: scholarly
bibFile: references.bib  # Path to BibTeX file (default: references.bib)
bibStyle: apa            # Citation style
bibShowNum: false        # Show numbered markers in bibliography (e.g. [1])
---

Supported styles:

• apa (default)
• harvard1
• vancouver
• ieee
• mla
• chicago-author-date

BibTeX File Example

Create references.bib beside slides.md. The keys in this sample are used in the examples below:

@article{lecun2015deep,
  title={Deep learning},
  author={LeCun, Yann and Bengio, Yoshua and Hinton, Geoffrey},
  journal={Nature},
  volume={521},
  pages={436--444},
  year={2015}
}

@inproceedings{vaswani2017attention,
  title={Attention is all you need},
  author={Vaswani, Ashish and others},
  booktitle={NeurIPS},
  year={2017}
}

Basic Usage

Parenthetical Citations

Use @citekey for parenthetical citations:

A review of deep learning describes these methods @lecun2015deep.

With APA style: A review of deep learning describes these methods (LeCun et al., 2015).

Narrative Citations

Use !@citekey for narrative (author-prominent) citations:

!@vaswani2017attention introduced the Transformer architecture.

Renders as: Vaswani et al. (2017) introduced the Transformer architecture.

Multiple Citations

Use several keys when a sentence refers to more than one paper. Every key must exist in the bibliography:

These papers discuss neural network architectures @lecun2015deep @vaswani2017attention.

Bibliography

Add a references slide:

---
layout: references
---

The theme builds the bibliography from the citations used in your slides.

If the slide body is empty or contains only headings and comments, the theme inserts the bibliography automatically.

If you want custom placement inside a references slide, add [[bibliography]] exactly where the list should appear.

You do not need a project-level vite.config.ts; Scholarly registers the citation hooks from the theme package.

Pagination

Create one references slide for each page. perPage limits the entries on a slide; it does not create additional slides automatically:

---
layout: references
perPage: 5
page: 1
---

---
layout: references
perPage: 5
page: 2
title: "References (continued)"
---

Markdown Footnotes

Standard Markdown footnotes work out of the box. No theme-specific syntax is required:

Our compact model stays stable across five seeds[^1].

[^1]: Validation accuracy varied by less than 0.3 percentage points.

In Slidev's interactive view, the theme applies academic footnote styling automatically:

• Hover a footnote marker on desktop to preview the note
• Click the marker to pin the popover
• Press Esc or click outside to close it

Set the global default in the deck headmatter:

---
footnoteDisplay: hover-only
---

Override it on an individual slide with frontmatter:

---
footnoteDisplay: notes-only
---

• footnoteDisplay: both keeps the bottom footnotes and the inline hover/click preview
• footnoteDisplay: hover-only hides the bottom footnote block and keeps only the inline preview
• footnoteDisplay: notes-only keeps the bottom footnotes and disables the hover/click popover

Priority order:

• Per-slide footnoteDisplay
• Global headmatter footnoteDisplay
• Legacy themeConfig.footnoteDisplay
• Default both

When you print or export slides, footnotes fall back to the normal footnote block at the bottom of the slide.

Cross-Slide Anchor Jumps

In Slidev's interactive view, Scholarly turns internal href="#..." links into slide-aware jumps:

• In-text BibTeX citations can jump to the matching bibliography entry, even when the references list is on another slide
• Generic internal links such as [Jump](#appendix-proof) work across slides when the target is declared with ## Appendix {#appendix-proof}, ::anchor{#appendix-proof}, or an explicit id="appendix-proof"
• After jumping, a floating Back to source button appears so you can return to the previous citation or link position

This behavior is designed for live presentations and local browser viewing. Print and export outputs keep the normal static content.

Doctor Diagnostics

Run the doctor when citations do not render as expected:

pnpm exec sch doctor

The citation checks report:

• Citation setup: whether citations have a bibFile or default references.bib
• Citation bibliography: whether the .bib file exists and has duplicate keys
• Citation keys: unresolved @citekey values used in slides
• References slide: whether a layout: references slide exists

Common warnings:

- Citation setup: [WARN] citations found but no bibFile or references.bib
- Citation bibliography: [WARN] missing .bib file: ./references.bib
- Citation keys: [WARN] unresolved citation keys: missing2026
- References slide: [WARN] missing; add layout: references

Cite Component (Manual)

Use the lightweight <Cite> component for manual notes that do not belong in BibTeX. For formal citations, prefer @citekey or !@citekey.

Author-Year Marker (Legacy)

<Cite author="Smith et al." year="2024" />

Renders as: (Smith et al., 2024)

You can also provide additional context:

<Cite author="Smith et al." year="2024">
Citation text here.
</Cite>

Numeric Marker

<Cite :inline="true">
Citation text here.
</Cite>

Optionally set a fixed id:

<Cite :inline="false" :id="1">
Reference item here.
</Cite>

Props

Prop	Type	Default	Description
id	string | number	automatic	Fixed numeric marker or key
inline	boolean	true	Uses inline rather than block presentation
author	string	-	Author text for a manual author-year marker
year	string | number	-	Year for a manual author-year marker