IEEE Citations in Markdown With Pandoc and CSL

Download and keep the files together

Download the complete sample folder, then extract it before running the commands. It contains paper.md, references.bib, ieee.csl, and the rendered paper.html and paper.docx. A reordered version lets you compare the numbers without editing anything first. Run the commands inside the extracted folder so the relative paths resolve.

We tested Pandoc 3.13 on October 27, 2026, using the official macOS portable distribution. Check your own version with pandoc --version. The HTML and DOCX commands below use Pandoc directly. They do not require a TeX installation. See Pandoc's installation page for the package matching your operating system.

The included IEEE CSL is an unchanged snapshot from the Citation Style Language styles repository at commit 1ccf4696be22ea0b55f83cc9163bde3061fddb0a. That file's last repository change was January 7, 2026. Keep this local copy with the project so later style updates cannot silently change a regenerated bibliography. README.txt records the download source, checksum, and commands.

Prepare Markdown, BibTeX, and CSL

The YAML block selects the bibliography and style. Write the citation key inside brackets with an @ prefix. The refs division places the generated bibliography beneath the References heading.

---
title: IEEE citation order check
bibliography: references.bib
csl: ieee.csl
lang: en-US
---

# Source order

One source is the MapReduce paper [@dean2008].

Another source is the Parliament paper [@lamport1998].

The MapReduce paper is cited again [@dean2008].

# References

::: {#refs}
:::

The sample references.bib contains two journal records. Lamport appears first in that file; Dean and Ghemawat appear second. The Markdown deliberately cites Dean and Ghemawat first, giving us a way to test which order the output follows.

@article{lamport1998,
  author = {Lamport, Leslie},
  title = {The Part-Time Parliament},
  journal = {ACM Transactions on Computer Systems},
  volume = {16},
  number = {2},
  pages = {133--169},
  year = {1998},
  month = may,
  doi = {10.1145/279227.279229}
}

@article{dean2008,
  author = {Dean, Jeffrey and Ghemawat, Sanjay},
  title = {{MapReduce}},
  journal = {Communications of the ACM},
  volume = {51},
  number = {1},
  pages = {107--113},
  year = {2008},
  month = jan,
  doi = {10.1145/1327452.1327492}
}

The MapReduce record uses the January 2008 Communications of the ACM publication, volume 51, issue 1, pages 107–113. Its publisher-deposited Crossref title is MapReduce. The earlier OSDI conference version has different publication fields. Keep the DOI and journal details together when importing a record.

Lamport's author-hosted manuscript identifies the 1998 ACM Transactions on Computer Systems article, volume 16, issue 2, pages 133–169. Its cover also notes corrections made in 2000. The sample keeps 1998 as the journal publication year. The extra braces around MapReduce preserve that capitalization during title formatting. Both records retain full journal names; check any abbreviation required by your venue separately.

Render with citeproc

Run these commands from the folder containing the three input files.

pandoc paper.md --citeproc --standalone --output paper.html
pandoc paper.md --citeproc --output paper.docx
pandoc reordered.md --citeproc --standalone --output reordered.html
pandoc reordered.md --citeproc --output reordered.docx

All four sample builds, including the reordered pair, finished successfully with no warnings. The --citeproc option formats the citation nodes and bibliography. The HTML command also uses --standalone to include a complete document with a head and body.

In a separate run without --citeproc, Pandoc returned success but left @dean2008-style keys visible and produced no formatted reference list. An output file and a zero exit status therefore do not establish that citation processing happened. Open the result and inspect the first citation before distributing it.

Check repeated citations and order

The original HTML and DOCX show MapReduce [1], Parliament [2], and MapReduce [1] again. After swapping the first two cited paragraphs, both outputs show Parliament [1], MapReduce [2], and MapReduce [2]. The reference list changes with them and still contains exactly two entries.

The bibliography file stayed unchanged throughout this test. These results show first-citation ordering for the included IEEE style and sample. Keep citation keys in your Markdown while editing, then regenerate after moving sections. Typing [1] by hand would leave Pandoc without a citation key to renumber.

A separate missing-key test used [@missing2026]. Pandoc emitted the warning Citeproc: citation missing2026 not found and still exited with status 0. The output contained an unresolved citation. Read the warnings as well as the document, especially when a build script reports success. Match the key against the bibliography entry, correct it, and rerun the command.

Inspect the HTML and DOCX outputs

The HTML sample links its numbered citations to reference entries. Its list gives both DOIs, the journal volumes and issues, the page ranges, and January 2008 or May 1998 dates. Compare the actual source fields before adjusting punctuation. Replacing the CSL file cannot repair an incorrect year or a DOI belonging to another version.

We also rendered both generated DOCX files for visual inspection. Each fits on one page with three numbered citations and two references. In the DOCX, citation numbers are ordinary generated text. Editing their visible numbers in Word does not update the Markdown or rerun citeproc. Make source changes in the Markdown and bibliography, then generate the DOCX again.

CSL controls citation formatting. The sample DOCX uses Pandoc's default document layout. For a submission template, check Pandoc's --reference-doc option and inspect the regenerated file against the venue's requirements. The Word reference-list guide explains hanging indents and spacing when you need to review the final document.

If you already have a bibliography export, use the BibTeX guide to check entry types, authors, and missing fields first. IEEE Citation Generator can help inspect records or export BibTeX; run this Markdown workflow with Pandoc after saving the files.

Open the generated HTML sample or download the DOCX sample. Compare the reordered HTML and reordered DOCX after changing paragraph order.