Markdown Citations Still Show [@key] in Word? Fix BibTeX and Bibliography Errors

A citation such as [@smith2024] is useful while writing Markdown, but it should not remain visible in a finished Word document. If citation keys appear unchanged, the conversion process probably could not find the bibliography file, did not match the key, or was not given a citation style.

This is different from a formatting problem. The converter must combine three separate inputs correctly: the citation written in Markdown, the matching record in a BibTeX or CSL JSON file, and the selected citation style. If any one of those parts is missing or inconsistent, the DOCX may contain raw keys, incomplete references, or an empty bibliography.

Why raw citation keys appear in Word

A Markdown citation key is an identifier, not a complete reference. The key tells the citation processor which bibliography record to use.

Recent research describes the same limitation [@smith2024].

The processor then searches the bibliography for a record named smith2024. If the record is found, it formats the in-text citation and adds the corresponding reference to the bibliography according to the selected style.

Raw keys commonly remain when:

• No bibliography file was supplied.
• The key in Markdown does not exactly match the bibliography key.
• The bibliography file is malformed or saved with an unexpected encoding.
• The citation is inside a code block, where it should remain literal text.
• A record is missing required fields for the chosen style.
• The citation style file is missing, unsupported, or not selected.
• The bibliography file was placed outside the uploaded ZIP structure.

Step 1: Check the citation syntax

Use citation syntax consistently. A simple parenthetical citation is commonly written as:

The method was later extended [@smith2024].

A narrative citation can place the author in the sentence:

@smith2024 argues that the original method needs revision.

Multiple sources can be grouped:

Several studies report similar results [@smith2024; @lee2025; @garcia2026].

Do not add extra spaces inside the key or change its capitalization unless the bibliography uses the same characters. Treat citation keys as exact identifiers.

Step 2: Match the key to the bibliography record

A BibTeX record begins with an entry type and key:

@article{smith2024,
  author  = {Smith, Jordan and Lee, Mei},
  title   = {Reliable Document Conversion Workflows},
  journal = {Journal of Technical Publishing},
  year    = {2024},
  volume  = {12},
  number  = {3},
  pages   = {44--58},
  doi     = {10.0000/example-doi}
}

The Markdown citation [@smith2024] matches the key immediately after the opening brace.

Step 3: Include the bibliography in the upload package

When the Markdown and bibliography are separate files, keep them together in the ZIP package. A simple structure is easier to inspect:

research-report.zip
├── research-report.md
├── references.bib
└── images
    ├── workflow.png
    └── results-chart.png

If the document uses CSL JSON instead of BibTeX, replace references.bib with the corresponding JSON file. Do not place the bibliography on your desktop and upload only the Markdown file; the server cannot read files that remain on your computer.

Step 4: Choose the citation style before conversion

The same source record can produce different in-text citations and bibliography entries under different styles. An author-date style may display a surname and year, while a numeric style may display a bracketed number.

Do not select a style based only on visual preference. Use the style required by the journal, school, client, or internal documentation standard.

Step 5: Check bibliography fields before blaming the style

A citation style can only format the data available in the record. Missing author, year, title, container, publisher, page, DOI, or URL fields may create incomplete references.

Check at least these fields where applicable:

• Author or organization name
• Publication year
• Title
• Journal, book, conference, or website name
• Volume, issue, and page range
• Publisher
• DOI or stable URL
• Access date when required by the style

Do not place citations inside code blocks

Citation syntax inside a code block should remain literal because it may be part of an example:

```markdown
This is how a citation is written: [@smith2024]
```

If the same key should become a real citation, place it outside the code fence:

The workflow has been evaluated in prior research [@smith2024].

Use citations and footnotes for different purposes

Citations identify external sources. Footnotes provide supplementary explanation, qualification, or context. They can appear together, but they should not be treated as interchangeable.

Do not use a footnote merely to hide a weak or incomplete citation. If a claim relies on an external source, the source record still needs complete and accurate metadata.

A reliable troubleshooting workflow

1. Find the first raw citation key. Record its exact spelling.
2. Search the bibliography file. Confirm that an identical key exists.
3. Validate the record. Check braces, commas, quotes, JSON syntax, and encoding.
4. Confirm the file is included. Open the ZIP and locate the bibliography.
5. Check the citation location. Ensure the key is not inside code.
6. Select the required style. Use the standard requested by the recipient.
7. Convert a minimal test. Use one citation and one bibliography record.
8. Return the corrected files to the full document. Then inspect the complete bibliography.

Review the final DOCX

Common symptoms and fixes

Frequently asked questions

Final checklist