Creating a bibliography and citing sources

Unofficial ConTeXt Wiki mirror

Last modified: 2026-08-31

🚧 This page is under construction. Feel free to correct, expand, and improve it; its structure and examples may still change.

Bibliography guides — Guide 1 of 4

← Previous: Bibliography and citations  ·  Current: Guide 1 — Creating a bibliography and citing sources  ·  Next: Guide 2 — Understanding datasets, styles, renderings, selection, and sorting →

1. Creating a bibliography and citing sources

This guide shows how to create a first working bibliography, cite records in a ConTeXt document, and place the resulting bibliography in the output.

The aim is deliberately practical. By the end of the guide, you should be able to:

This guide concentrates on the first working bibliography.

Datasets, renderings, selection criteria, sorting policies, multiple bibliographies, and detailed style questions are introduced in the later guides.

2. Your first working bibliography

The following example is self-contained. The bibliographic records and the ConTeXt source are kept in one file, so the example can be copied and compiled directly.

The expected output contains:

Why begin with a buffer?

A buffer keeps the bibliographic data and the ConTeXt source in one file.

This is useful for wiki examples, tests, and bug reports. In a larger project, an external .bib file is usually easier to maintain.

3. How the example works

The example performs five main operations.

Element Role
\startbuffer[biblio] ... \stopbuffer Stores the bibliographic records inside the example.
\usebtxdataset[default][biblio.buffer] Loads those records into the dataset named default.
\usebtxdefinitions[apa] Loads a bibliographic specification.
\cite[authoryear][beiser1987] Uses the record identified by its key and displays an author–year citation.
\placelistofpublications Places the bibliography at the current position.

3.1. The bibliographic source

The block: 

\startbuffer[biblio]
...
\stopbuffer

contains the bibliographic records.

The expression: 

biblio.buffer

tells ConTeXt to use the contents of the buffer named biblio as bibliographic input.

3.2. Loading the records

The command: 

\usebtxdataset
  [default]
  [biblio.buffer]

loads the records into a dataset named default.

At this stage, the important distinction is:

The deeper distinction between bibliographic sources and datasets is developed in Guide 2.

3.3. Loading the specification

The command: 

\usebtxdefinitions
  [apa]

loads the APA bibliography definitions used in this first example.

The bibliographic data and their presentation remain separate:

3.4. Citing a record

A record is cited by its key: 

\cite[authoryear][beiser1987]

The first argument selects the citation alternative, here authoryear.

The second argument identifies the record: 

beiser1987

The key is not normally printed. ConTeXt uses it to identify the record and constructs the visible citation from the record's fields.

Different citation alternatives can use the same bibliographic record in different ways. They are introduced more systematically in Guide 2.

Several records can also be cited together: 

\cite
  [authoryear]
  [beiser1987,jacobi1785]

The bibliography specification determines how several cited records are combined and formatted, including cases in which several works have the same author. Such style-dependent behaviour is discussed later.

3.5. Placing the bibliography

The command: 

\placelistofpublications

places the bibliography at the current position.

The same structured records can therefore be used in two related ways: 

 selected for that list.

The distinction between citation and bibliography selection becomes important when a document contains several bibliography lists. It is developed in the following guides.

4. Understanding a bibliographic record

A BibTeX record contains three main elements:

For example: 

@Book{beiser1987,
  author    = {Beiser, Frederick C.},
  title     = {The Fate of Reason},
  subtitle  = {German Philosophy from Kant to Fichte},
  publisher = {Harvard University Press},
  address   = {Cambridge, Massachusetts},
  year      = {1987},
}
Element Example Function
Category @Book Identifies the kind of publication.
Record key beiser1987 Identifies the record inside the dataset.
Fields author, title, year Store the publication data.

4.1. Common categories

Common BibTeX-style categories used in bibliographic datasets include: 

@Book
@Article
@InCollection
@InProceedings
@PhdThesis
@Misc

For example, a journal article may be entered as: 

@Article{ameriks1981,
  author  = {Ameriks, Karl},
  title   = {Kant's Deduction of the Categories},
  journal = {The Monist},
  year    = {1981},
  volume  = {64},
  number  = {4},
  pages   = {451--470},
}

Use a category that corresponds to the publication being described.

4.2. Record keys

A record key should normally be:

A simple author–year pattern is often sufficient: 

beiser1987
ameriks1981
jacobi1785

Larger projects may adopt longer or project-specific keys, provided that the system remains consistent.

Key distinction

The key identifies the record for ConTeXt.

It is not normally part of the printed citation or bibliography entry.

4.3. Authors, editors, and translators

A personal name may be written with the family name first: 

author = {Beiser, Frederick C.},

Several people must be separated with the word and: 

author = {Beiser, Frederick C. and Ameriks, Karl},

Do not separate different authors with commas or semicolons.

Editors and translators use their own fields: 

editor     = {Wood, Allen W.},
translator = {Di Giovanni, George},

Common mistake

A comma separates parts of one personal name.

The word and separates different people.

4.4. UTF-8 and stable data

Save both the ConTeXt source and the bibliographic data as UTF-8.

Accented letters and non-Latin characters can normally be entered directly: 

author = {Jacobi, Friedrich Heinrich},
title  = {Über die Lehre des Spinoza},

Bibliographic records should contain stable publication data rather than document-specific layout instructions.

Prefer: 

title = {The Fate of Reason},

to a title containing font or layout commands intended for only one document.

The general principle is: 

data in the bibliographic source presentation in ConTeXt

This distinction also applies to identifiers and network addresses. A bibliographic field is not merely text waiting to be printed: its name identifies the kind of data that it contains.

DOI and URL fields

A DOI should normally be stored as a DOI: 

doi = {10.1037/0033-2909.100.2.176},

while an ordinary web address belongs in a url field: 

url = {https://example.org/document},

Although both may ultimately lead to a resource on the Web, doi and url are different bibliographic fields. Bibliography specifications may therefore interpret and render them differently.

For example: 

@Article{falbo1986quantitative,
  author  = {Falbo, T. and Polit, D. F.},
  title   = {Quantitative review of the only child literature:
             Research evidence and theory development},
  journal = {Psychological Bulletin},
  volume  = {100},
  number  = {2},
  pages   = {176--189},
  year    = {1986},
  doi     = {10.1037/0033-2909.100.2.176},
}

With the APA specification tested with current LMTX, the DOI field is recognised and rendered as part of the bibliography entry. The visible DOI can also be broken across lines when necessary.

The important distinction is: 

BIBLIOGRAPHIC DATA
        |
        +---- doi = {10.1037/...}
        |
        v
BTX SPECIFICATION
        |
        v
DOI RENDERING
        |
        +---- visible form
        +---- hyperlink target
        `---- permitted line breaks

The .bib record should therefore contain the identifier itself, not instructions for typesetting it.

Do not write, for example: 

doi = {\hyphenatedurl{10.1037/0033-2909.100.2.176}},

merely in order to control line breaking. Such formatting belongs to the ConTeXt or BTX presentation layer, not to the bibliographic data.

Likewise, do not replace 

doi = {10.1037/0033-2909.100.2.176},

with 

url = {https://doi.org/10.1037/0033-2909.100.2.176},

merely to obtain a different visual form or better line breaking.

In the APA tests, treating the DOI resolver as a normal url changed the resulting bibliography entry: the specification treated it as a web address and introduced the corresponding URL wording. The data had therefore changed meaning, not merely appearance.

The visible form of a DOI is a separate question. A bibliography style or a project may display the same stored identifier, for example, as 

doi:10.1037/0033-2909.100.2.176

or as 

https://doi.org/10.1037/0033-2909.100.2.176

without changing the bibliographic record itself.

Practical rule

Keep a DOI in the doi field. If its visible form, hyperlink target, or line-breaking behaviour needs adjustment, change the bibliography rendering rather than the bibliographic data.

5. Moving the records to a .bib file

A buffer is convenient for a self-contained example. For normal work, place the records in an external .bib file.

5.1. The bibliographic file

Create a first file named: 

references.bib

and save it as the bibliography file that will accompany your source file: 

@Book{beiser1987,
  author    = {Beiser, Frederick C.},
  title     = {The Fate of Reason},
  subtitle  = {German Philosophy from Kant to Fichte},
  publisher = {Harvard University Press},
  address   = {Cambridge, Massachusetts},
  year      = {1987},
}

@Book{jacobi1785,
  author    = {Jacobi, Friedrich Heinrich},
  title     = {Über die Lehre des Spinoza
               in Briefen an Herrn Moses Mendelssohn},
  publisher = {Gottlieb Löwe},
  address   = {Breslau},
  year      = {1785},
}

@Article{ameriks1981,
  author  = {Ameriks, Karl},
  title   = {Kant's Deduction of the Categories},
  journal = {The Monist},
  year    = {1981},
  volume  = {64},
  number  = {4},
  pages   = {451--470},
}

The external file also adds a journal article, so that the example now contains more than one bibliographic category.

5.2. The ConTeXt source

Create a second file named: 

bibliography-example.tex

Save: 

\mainlanguage[en]

\setupbodyfont
  [libertinus,10pt]

\usebtxdataset
  [default]
  % Here, enter the name of the file containing the bibliographic references
  [references.bib]

\usebtxdefinitions
  [apa]

\starttext

\subject{Reason, faith, and criticism}

Beiser presents the philosophical controversies that followed Kant
\cite[authoryear][beiser1987].

Jacobi's intervention made the question of Spinozism central to
German philosophy
\cite[authoryear][jacobi1785].

Ameriks offers a modern discussion of Kant's categories
\cite[authoryear][ameriks1981].

\subject{Bibliography}

\placelistofpublications

\stoptext

The important difference from the first MWE is: 

\usebtxdataset
  [default]
  [references.bib]

The records now come from an external file rather than a buffer.

5.3. Compiling the document

Place both files in the same directory and run: 

context bibliography-example.tex

The context runner performs the normal processing required to resolve collected information.

Expected result

The document contains three author–year citations and a bibliography with the three corresponding entries.

6. Tools for maintaining the data

A bibliography manager such as JabRef can help create and maintain a large .bib file.

It can assist with:

The resulting .bib file remains an ordinary UTF-8 text file.

It may also be inspected or edited in Emacs, Vim, Visual Studio Code, Notepad++, or another suitable editor.

Division of labour

A bibliography manager or text editor maintains the data.

ConTeXt selects, formats, and places those data in the document.

7. Common problems

7.1. The citation remains unresolved

Check:

For example, these keys are different: 

beiser1987
Beiser1987

7.2. The bibliographic file is not found

The command: 

\usebtxdataset
  [default]
  [references.bib]

expects ConTeXt to find references.bib from the compilation context.

For the first external-file example, keep both files in the same directory.

If the file is in a subdirectory, use an appropriate relative path: 

\usebtxdataset
  [default]
  [bib/references.bib]

Complex project paths are discussed in Guide 4.

7.3. The files are not saved as UTF-8

Incorrect encoding may produce malformed characters or parsing errors.

Verify that both the .tex and .bib files are saved as UTF-8.

7.4. Several authors are separated incorrectly

Incorrect: 

author = {Beiser, Frederick C., Ameriks, Karl},

Correct: 

author = {Beiser, Frederick C. and Ameriks, Karl},

7.5. The key contains spaces

Avoid: 

@Book{Beiser 1987,

Prefer: 

@Book{beiser1987,

7.6. A loaded record does not appear

A record may be available in the dataset but absent from the bibliography because it has not been cited or otherwise selected.

In this introductory guide, cite the record explicitly: 

\cite[authoryear][beiser1987]

The relation between loaded records, cited records, bibliography selection, and rendering scope is explained in Guide 2.

7.7. The record category is unsuitable

Use a category that corresponds to the publication:

A record may be read successfully but still be rendered poorly if its category or fields are unsuitable.

8. What you have learned

This guide has introduced the first complete bibliography workflow in ConTeXt.

You have seen how to:

Continue with:

Guide 2 — Understanding datasets, styles, renderings, selection, and sorting

The next guide explains how sources, datasets, specifications, citation alternatives, renderings, selection criteria, sorting rules, and placement work together.

9. Related pages and commands

Bibliography guides — Guide 1 of 4

← Previous: Bibliography and citations  ·  Current: Guide 1 — Creating a bibliography and citing sources  ·  Next: Guide 2 — Understanding datasets, styles, renderings, selection, and sorting →