PANDOC-CITEPROC-PREAMBLE.1(1)

💖 PANDOC-CITEPROC-PREAMBLE 💖

ok so bestie, welcome to pandoc-citeproc-preamble — that's the name of this little User Commands cutie, and honestly it's about to make your bibliographies look absolutely iconic. ✨

---

🌸 NAME 🌸

pandoc-citeproc-preamble — slides a preamble in right before Pandoc's bibliography, no cap 📚💅

---

🦋 SYNOPSIS 🦋

pandoc-citeproc-preamble

(yeah that's literally it, she's a filter, she doesn't need a whole argument era)

---

✨ DESCRIPTION ✨

okay so here's the tea: pandoc-citeproc-preamble is a JSON filter for pandoc(1), and what she does is insert a preamble before the output that Pandoc's citeproc filter appends to the document. 🫶

and what even goes in that preamble? literally whatever you want — it might include a heading (like, say, "Bibliography"), and/or raw markup to format the bibliography for whatever output format you're on. slay. 💅

---

🎀 USAGE 🎀

the way you use it: drop --filter pandoc-citeproc-preamble somewhere after --citeproc. like this, bestie:

% pandoc -s --citeproc --bibliography=~/doc/mine.bib \
    --filter pandoc-citeproc-preamble \
    ~/doc/my_essay.mdwn -o ~/my_essay.pdf

see how --filter pandoc-citeproc-preamble comes after --citeproc? that's the move. order matters here, iykyk. 👑

---

💜 FILES 💜

• ~/.pandoc/citeproc-preamble/default.FORMAT — the default citeproc preamble for Pandoc output format FORMAT (think stuff like "latex", you know the vibe). 🍓

and if you wanna override that? no problem babe, you just set some document metadata like this:

% pandoc ... --filter pandoc-citeproc-preamble \
    -M citeproc-preamble=~/mypreamble.tex ...

boom. custom preamble. main character energy. 💖

---

🌈 RATIONALE 🌈

okay let me explain why this exists because it's genuinely so real of this tool.

one motivation for authoring with Pandoc is that your input files are agnostic with regard to the output format they'll eventually be compiled to. like... you should NOT have to cram LaTeX code into your input file just to format the bibliography. that's so not the point. 😭 your input file might get compiled to HTML too, and she shouldn't be forced to pick a side.

BUT — and this is the plot twist — when you're compiling to PDF, formatting code is usually required so the entries of Pandoc's bibliography actually line up with each other. by default, all entries except the first will be indented. (not cute.) another super common customisation is setting up a hanging indent for bibliography entries.

and here's the problem: Pandoc's citeproc filter doesn't provide any facility to add formatting control code to its output. none. zero. 💀

so pandoc-citeproc-preamble is necessary so that you're not forced to dump your control code at the end of your input files — which would make you lose the input file's agnosticity with regard to output format. and we are NOT losing that. periodt. 🔥

---

👑 AUTHOR 👑

Sean Whitton <spwhitton@spwhitton.name> — the legend herself 💫

---

🧚 SEE ALSO 🧚

• pandoc(1)

---

and that's the whole page, bestie!! go forth and make bibliographies pretty 🦋🌸💖

ta-ta for now — this was PANDOC-CITEPROC-PREAMBLE.1, built with perl v5.40.1, dated 2025-10-01. mwah 💋