Organising bibliographies in complex editorial projects

1. Organising bibliographies in a multifile project

The first three guides introduced:

• bibliographic records and citation keys;
• sources and datasets;
• specifications and renderings;
• bibliography scope with method and criterium ;
• repeated rendering with repeat ;
• chapter bibliographies and final bibliographies;
• several renderings and several datasets.

This guide applies those mechanisms to a structured publication containing several files.

A long monograph, critical edition, translation, or collected volume may contain:

• shared page and font settings;
• several chapters or components;
• primary and secondary bibliographic collections;
• chapter bibliographies;
• final bibliography lists;
• commands that must remain stable throughout the project;
• data files maintained independently from the document prose.

At that scale, bibliography management becomes an architectural problem.

2. Separate the project responsibilities

A multifile publication is easier to maintain when each kind of file has one main responsibility.

Responsibility	Recommended location
General layout, fonts, language, and headings	A shared environment
Dataset loading, specifications, renderings, and bibliography commands	A bibliography environment
Bibliographic records	One or more .bib files
Chapter prose and citations	Chapter components
Chapter bibliography placement	The relevant chapter component
Final bibliography placement	A backmatter component
Complete publication assembly	A product file

This separation prevents the same setup from being copied into several chapters.

It also makes it easier to determine where a correction belongs.

3. A recommended directory structure

The following structure uses one product, several components, shared environments, and two bibliographic data files:

book/
├── product.tex
├── env/
│   ├── general.mkxl
│   └── bibliography.mkxl
├── bib/
│   ├── primary.bib
│   └── secondary.bib
├── frontmatter/
│   └── introduction.tex
├── bodymatter/
│   ├── chapter-01.tex
│   └── chapter-02.tex
└── backmatter/
    └── bibliography.tex

The directory names describe the function of the files.

The extensions used here are project conventions:

• .mkxl identifies shared LMTX environment files;
• .tex identifies the product and textual components;
• .bib identifies bibliographic data.

ConTeXt can recognise other file extensions, but a consistent local convention makes the project easier to read.

Location	Main responsibility
product.tex	Assemble the publication.
env/general.mkxl	Define general document settings.
env/bibliography.mkxl	Load datasets and define renderings and citation commands.
bib/*.bib	Store bibliographic records.
frontmatter/*.tex	Preliminary components.
bodymatter/*.tex	Chapters, citations, and chapter bibliography placement.
backmatter/bibliography.tex	Place the final bibliography lists.

4. Environment, product, and components

This guide uses a product-centred structure:

• environments define reusable settings;
• the product assembles the publication;
• components contain the actual document units.

A larger publication may additionally use a ConTeXt project containing several products, but that extra level is not required for the example below.

4.1. The general environment

The file env/general.mkxl may contain:

\startenvironment general

\mainlanguage
  [en]

\setuppapersize
  [A5]

\setuplayout
  [backspace=18mm,
   topspace=15mm,
   width=middle,
   height=middle,
   header=0pt,
   footer=8mm]

\setupbodyfont
  [libertinus,10pt]

\stopenvironment

This file contains settings shared by all components.

4.2. The product file

The file product.tex loads the environments and lists the components in publication order:

\environment env/general.mkxl
\environment env/bibliography.mkxl

\startproduct book

\component frontmatter/introduction

\component bodymatter/chapter-01
\component bodymatter/chapter-02

\component backmatter/bibliography

\stopproduct

The product expresses the structure of the publication.

It should not repeat the detailed bibliography configuration.

4.3. Chapter components

A chapter component contains prose, citations, and—when required—the bibliography associated with that chapter.

For example:

\startcomponent chapter-01

\chapter{The pantheism controversy}

Jacobi's intervention changed the terms of the debate
\PrimaryCite{jacobi1785}.

Beiser reconstructs the wider historical conflict
\SecondaryCite{beiser1987}.

\subject{Secondary literature used in this chapter}

\placebtxrendering
  [secondary-chapter]
  [method=global,
   criterium=chapter,
   repeat=yes]

\stopcomponent

Here the rendering is defined centrally, while the chapter component determines where it is placed and which structural scope is requested.

4.4. The bibliography component

The backmatter component decides where the final lists appear:

\startcomponent bibliography

\chapter{Bibliography}

\subject{Primary sources}

\placebtxrendering
  [primary-global]
  [method=global,
   repeat=yes]

\subject{Secondary bibliography}

\placebtxrendering
  [secondary-global]
  [method=global,
   repeat=yes]

\stopcomponent

The distinction is therefore:

Element	Main role
Environment	Defines reusable settings and commands.
Product	Assembles the publication.
Component	Contains one editorial or structural unit and determines where structurally dependent material is placed.

5. Centralising bibliography settings

The file env/bibliography.mkxl should contain the shared bibliography configuration.

5.1. Loading the datasets

For example:

\startenvironment bibliography

\usebtxdataset
  [primary]
  [bib/primary.bib]

\usebtxdataset
  [secondary]
  [bib/secondary.bib]

\usebtxdefinitions
  [apa]

The paths are written relative to the compilation context used for the product.

For a production project, verify the paths both when compiling the complete product and when testing individual components.

5.2. Defining the renderings

The same environment may define:

\definebtxrendering
  [primary-global]
  [apa]
  [dataset=primary,
   sorttype=authoryear]

\definebtxrendering
  [secondary-chapter]
  [apa]
  [dataset=secondary,
   sorttype=authoryear]

\definebtxrendering
  [secondary-global]
  [apa]
  [dataset=secondary,
   sorttype=authoryear]

The names combine:

• the collection;
• the intended scope or editorial role.

Prefer:

primary-global
secondary-chapter
secondary-global

to temporary names such as:

list1
testlist
final2

The environment defines reusable bibliography configurations.

Structural options such as criterium=chapter remain at the placement point because they depend on the current document context.

In other words:

environment  -> what bibliography configurations exist
component    -> where and in which structural scope they are rendered

5.3. Ending the environment

The file ends with:

\stopenvironment

The complete environment therefore follows this pattern:

\startenvironment bibliography

\usebtxdataset
  [primary]
  [bib/primary.bib]

\usebtxdataset
  [secondary]
  [bib/secondary.bib]

\usebtxdefinitions
  [apa]

\definebtxrendering
  [primary-global]
  [apa]
  [dataset=primary,
   sorttype=authoryear]

\definebtxrendering
  [secondary-chapter]
  [apa]
  [dataset=secondary,
   sorttype=authoryear]

\definebtxrendering
  [secondary-global]
  [apa]
  [dataset=secondary,
   sorttype=authoryear]

\stopenvironment

6. One dataset or several datasets?

Several files may contribute to one logical dataset:

\usebtxdataset
  [secondary]
  [bib/books.bib]

\usebtxdataset
  [secondary]
  [bib/articles.bib]

This is useful when files are separated for maintenance but the records form one collection.

Separate datasets are useful when a stable editorial distinction must remain visible:

\usebtxdataset
  [primary]
  [bib/primary.bib]

\usebtxdataset
  [secondary]
  [bib/secondary.bib]

The distinction can then be expressed directly in citations:

primary::jacobi1785
secondary::beiser1987

7. Defining project-level citation commands

A project may define semantic wrapper commands so that chapter authors do not have to repeat dataset names and low-level options.

For example, add to env/bibliography.mkxl:

\define[1]\PrimaryCite
  {\cite
     [authoryear]
     [primary::#1]}

\define[1]\SecondaryCite
  {\cite
     [authoryear]
     [secondary::#1]}

A chapter can then use:

\PrimaryCite{jacobi1785}

and:

\SecondaryCite{beiser1987}

These commands:

• reduce repeated typing;
• prevent dataset-name errors;
• make the editorial role of the citation visible;
• allow later project-wide changes.

8. Chapter and final bibliography placement

The bibliography environment defines the lists.

The components decide where those lists are placed and, when necessary, which structural scope applies.

8.1. Chapter placement

At the end of a chapter component:

\subject{Secondary literature used in this chapter}

\placebtxrendering
  [secondary-chapter]
  [method=global,
   criterium=chapter,
   repeat=yes]

The option criterium=chapter restricts this rendering to the current chapter scope.

The physical placement of the list and its structural scope remain distinct aspects of the setup.

The three options answer different questions:

method=global       -> use globally registered bibliography references
criterium=chapter   -> restrict the rendering to the current chapter
repeat=yes          -> allow already rendered records to appear again

8.2. Final placement in the backmatter

In backmatter/bibliography.tex:

\subject{Primary sources}

\placebtxrendering
  [primary-global]
  [method=global,
   repeat=yes]

\subject{Secondary bibliography}

\placebtxrendering
  [secondary-global]
  [method=global,
   repeat=yes]

The data and rendering definitions remain in the shared environment.

The placement remains in the appropriate textual component.

8.3. Repeated placement

A record already displayed in a chapter bibliography may need to appear again in the final bibliography.

In the chapter-plus-final pattern used here:

repeat=yes

allows records already rendered in chapter bibliographies to appear again in the final bibliography.

Other rendering sequences may require different choices.

9. A complete multifile project example

The following files form one small but genuine multifile project.

9.1. Directory tree

9.2. File: bib/primary.bib

@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},
}

@Book{hegel1820,
  author    = {Hegel, Georg Wilhelm Friedrich},
  title     = {Grundlinien der Philosophie des Rechts},
  publisher = {Nicolai},
  address   = {Berlin},
  year      = {1820},
}

9.3. File: bib/secondary.bib

@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},
}

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

9.4. File: env/general.mkxl

\startenvironment general

\mainlanguage
  [en]

\setuppapersize
  [A5]

\setuplayout
  [backspace=18mm,
   topspace=15mm,
   width=middle,
   height=middle,
   header=0pt,
   footer=8mm]

\setupbodyfont
  [libertinus,10pt]

\stopenvironment

9.5. File: env/bibliography.mkxl

\startenvironment bibliography

\usebtxdataset
  [primary]
  [bib/primary.bib]

\usebtxdataset
  [secondary]
  [bib/secondary.bib]

\usebtxdefinitions
  [apa]

\definebtxrendering
  [primary-global]
  [apa]
  [dataset=primary,
   sorttype=authoryear]

\definebtxrendering
  [secondary-chapter]
  [apa]
  [dataset=secondary,
   sorttype=authoryear]

\definebtxrendering
  [secondary-global]
  [apa]
  [dataset=secondary,
   sorttype=authoryear]

\define[1]\PrimaryCite
  {\cite
     [authoryear]
     [primary::#1]}

\define[1]\SecondaryCite
  {\cite
     [authoryear]
     [secondary::#1]}

\stopenvironment

9.6. File: frontmatter/introduction.tex

\startcomponent introduction

\chapter{Introduction}

This small project demonstrates the separation of data, shared bibliography
configuration, chapter content, and final-list placement.

\stopcomponent

9.7. File: bodymatter/chapter-01.tex

\startcomponent chapter-01

\chapter{The pantheism controversy}

Jacobi's intervention transformed the reception of Spinoza
\PrimaryCite{jacobi1785}.

Beiser reconstructs the wider philosophical conflict
\SecondaryCite{beiser1987}.

\subject{Secondary literature used in this chapter}

\placebtxrendering
  [secondary-chapter]
  [method=global,
   criterium=chapter,
   repeat=yes]

\stopcomponent

9.8. File: bodymatter/chapter-02.tex

\startcomponent chapter-02

\chapter{Law and the categories}

Hegel develops the institutional form of freedom
\PrimaryCite{hegel1820}.

Ameriks analyses the structure of Kant's deduction
\SecondaryCite{ameriks1981}.

\subject{Secondary literature used in this chapter}

\placebtxrendering
  [secondary-chapter]
  [method=global,
   criterium=chapter,
   repeat=yes]

\stopcomponent

9.9. File: backmatter/bibliography.tex

\startcomponent bibliography

\chapter{Bibliography}

\subject{Primary sources}

\placebtxrendering
  [primary-global]
  [method=global,
   repeat=yes]

\subject{Secondary bibliography}

\placebtxrendering
  [secondary-global]
  [method=global,
   repeat=yes]

\stopcomponent

9.10. File: product.tex

\environment env/general.mkxl
\environment env/bibliography.mkxl

\startproduct book

\component frontmatter/introduction

\component bodymatter/chapter-01
\component bodymatter/chapter-02

\component backmatter/bibliography

\stopproduct

9.11. Compile the product

From the book/ directory, run:

context product.tex

The intended result is:

• Chapter 1 contains a chapter-scoped secondary bibliography with Beiser;
• Chapter 2 contains a chapter-scoped secondary bibliography with Ameriks;
• the final primary bibliography contains Jacobi and Hegel;
• the final secondary bibliography contains Beiser and Ameriks.

This project demonstrates two independent editorial dimensions:

dataset
    primary / secondary

structural scope
    chapter / whole document

Bibliographic classification and structural scope are therefore independent choices.

10. Naming and path conventions

Use names that express stable editorial roles.

10.1. Dataset names

Prefer:

primary
secondary
translations
archives

10.2. Rendering names

Include the collection and intended scope or editorial role:

primary-global
secondary-chapter
secondary-global
translations-global

Avoid names whose meaning depends on an implementation detail or an ambiguous use of terms such as local.

10.3. Citation command names

Use commands that express editorial function:

\PrimaryCite
\SecondaryCite
\TranslationCite

10.4. Paths

Keep path conventions consistent.

For example:

\usebtxdataset
  [secondary]
  [bib/secondary.bib]

Test the project from the directory and compilation workflow that will be used in production.

Direct component compilation may require additional environment or path arrangements and should be tested separately.

11. Common project-level problems

11.1. The same setup appears in several chapters

Move shared definitions to an environment.

11.2. A citation resolves in one component but not another

Check:

• whether the bibliography environment is loaded;
• whether the dataset has been loaded;
• whether the path to the .bib file is correct;
• whether the key is explicitly qualified;
• whether the component is being compiled inside the expected product setup.

11.3. A record appears in the wrong bibliography

Check the dataset attached to the rendering.

The visible bibliography heading does not determine the dataset.

11.4. A chapter bibliography contains records from another chapter

Check:

• whether criterium=chapter is used;
• the active structural scope;
• component boundaries;
• placement of the chapter rendering;
• whether the citations belong to the intended dataset;
• whether the document has been reprocessed after structural changes.

Do not attempt to repair chapter scope merely by replacing method=global with method=local.

11.5. A final bibliography omits a record displayed in a chapter bibliography

Check:

• the dataset associated with the final rendering;
• whether method=global is used;
• whether repeat=yes permits the record to appear again;
• whether the record was cited or otherwise registered;
• whether the complete product has been processed again.

11.6. A record appears in one chapter bibliography but not another

If the same record is cited in more than one chapter, check:

• whether each placement uses the intended criterium=chapter ;
• whether repeat=yes permits repeated rendering;
• whether the citation occurs within the expected chapter scope.

11.7. Several files contain the same key

Duplicate keys in one dataset may produce conflicts or unexpected results.

Use a bibliography manager or a text search to locate duplicate records.

11.8. A style change requires editing every chapter

The bibliography configuration has not been sufficiently centralised.

Move the specification and rendering settings to the bibliography environment.

12. A practical diagnostic table

Symptom	Inspect first
A key is unresolved	Data file, dataset loading, path, key spelling, or qualification
A citation works only in the complete product	Component environment and path setup
The correct record appears in the wrong list	Rendering-to-dataset association
A chapter bibliography contains records from another chapter	criterium=chapter, component boundaries, and placement context
A chapter bibliography is empty	Rendering dataset, qualified citation key, chapter scope, and criterium
A record appears in the first chapter bibliography but not when cited again later	repeat
A chapter record is absent from the final bibliography	Final rendering scope and repeat=yes
A style correction must be repeated in several files	Missing central environment
Two records disagree about one publication	Duplicate bibliographic data
The final bibliography does not appear	Backmatter component and product assembly

13. Checklist before publication

Before producing the final PDF, verify:

• shared bibliography settings are centralised in an environment;
• bibliographic records are stored outside the textual components;
• every dataset has a stable editorial purpose;
• every rendering is associated with the correct dataset;
• dataset and rendering names are consistent;
• citation keys are unique;
• citations are explicitly qualified where several datasets are used;
• chapter bibliographies use the intended criterium and contain only records from the intended structural scope;
• repeat=yes is used where chapter and final renderings must reuse the same records;
• final bibliographies contain all intended records;
• paths work in the production compilation workflow;
• the product includes the bibliography component;
• the complete project compiles cleanly after structural changes.

14. What you have learned

This guide has shown how to organise bibliography management in a structured multifile publication.

The main workflow is:

bib/*.bib
        |
        v
datasets and renderings in env/bibliography.mkxl
        |
        +--------------------> citations in bodymatter/*.tex
        |
        +--------------------> chapter-scoped lists in bodymatter/*.tex
        |
        +--------------------> final lists in backmatter/bibliography.tex
        |
        v
complete assembly in product.tex

The central principles are:

• data, configuration, content, and placement should remain separate;
• shared bibliography settings belong in an environment;
• the product expresses publication structure;
• components contain chapter or backmatter content;
• datasets express bibliographic collections;
• renderings express bibliography lists;
• method controls the rendering/reference state used;
• criterium expresses structural scope at bibliography placement;
• repeat permits intentional reuse across chapter and final lists;
• stable names and paths make the project maintainable;
• a genuine multifile test is necessary before adopting the architecture in a large production project.

A useful summary is:

dataset    -> which bibliographic collection?
rendering  -> which bibliography list?
method     -> which rendering/reference state?
criterium  -> which structural scope?
repeat     -> may an already rendered record appear again?
component  -> where is the list placed?
product    -> how is the publication assembled?

15. End of the bibliography guides

The four guides form a progression:

1. Creating a bibliography and citing sources
2. Understanding bibliography datasets, styles, renderings, selection, and sorting
3. Creating local and multiple bibliographies
4. Organising bibliographies in complex editorial projects

Together they move from a first working citation to the organisation of a structured scholarly publication.

Advanced subjects require separate treatment, including:

• developed bibliographic references in notes;
• Chicago notes-and-bibliography and SBL workflows;
• custom bibliographic specifications;
• complex parent–child records and crossref ;
• PDF interaction between citations and bibliography entries;
• multilingual and multiscript bibliographies;
• philological references, critical editions, translations, and scholarly series.

16. Related pages and commands

• References notes and floats/Bibliography and citations
• Creating a bibliography and citing sources
• Understanding bibliography datasets, styles, renderings, selection, and sorting
• Creating local and multiple bibliographies
• Bibliography-related commands
• \usebtxdataset
• \usebtxdefinitions
• \cite
• \definebtxrendering
• \setupbtxrendering
• \placebtxrendering
• \environment
• \component
• \product