Indexes and registers in ConTeXt · Overview · How-to guides · Previous: Managing structured register data · Managing indexes in a project environment · Next: How-to guides

Under construction. This page describes a multi-file workflow. The complete examples should be tested with a current ConTeXt LMTX installation before this banner is removed.

Managing indexes in a project environment

A short document can define and place an index in a single source file. A book, critical edition, manual, or collected volume usually requires a different organisation:

the document is divided into several components;
all components must use the same register definitions;
sorting keys and entry conventions must remain consistent;
processors and formatting rules must be defined only once;
the final index must collect occurrences from the whole product;
project-wide changes should not require editing every chapter.

The most reliable solution is to centralise the index configuration in an environment file, insert entries from the components, and place the completed registers at product level.

Goal. At the end of this guide, you should be able to organise indexes and registers across a multi-file ConTeXt project without duplicating definitions or losing project-wide consistency.

Typical project structure

project/
├── index-environment.mkxl
├── book-product.tex
├── chapter-one.tex
├── chapter-two.tex
└── indexes.tex

index-environment.tex contains shared register definitions, processors, macros, and formatting rules;
index-product.tex assembles the complete document;
chapter-one.tex and chapter-two.tex contain the text and register occurrences;
indexes.tex places the final project-wide registers.

The extensions .mkxl, .mkiv, and .tex are conventional rather than mandatory. Their practical value is to act as visual signals: they help distinguish, classify, and locate files according to their intended role within a project.

1. Separate project configuration from document content

A useful project structure contains three kinds of files:

File type	Responsibility	Typical contents
Environment	Defines shared behaviour.	Fonts, layouts, registers, processors, macros, formatting rules
Product	Assembles the complete document.	Components, front matter, back matter, final register placement
Component	Contains one logical part of the document.	Chapters, sections, text, register occurrences

A minimal directory may therefore contain:

index-environment.tex
index-product.tex
chapter-one.tex
chapter-two.tex
indexes.tex

Separation of concerns. The environment defines how indexes behave. Components record where entries occur. The product determines where the complete registers are placed.

2. Centralise register definitions in the environment

The environment file is the appropriate place for definitions that every component must share.

For the predefined index:

\setupregister
  [index]
  [n=2,
   balance=yes]

For an additional register:

\defineregister[persons]

\setupregister
  [persons]
  [n=2,
   balance=yes]

Processors and project-specific insertion macros also belong in the environment:

\defineprocessor
  [main]
  [style=bold]

\define[2]\WorkEntry
  {\index[#1]{#2}}

Define each register once. Repeating \defineregister, processor definitions, or conflicting \setupregister settings in several components makes the project harder to maintain and may produce inconsistent output.

3. Insert entries from components

Components should contain document content and register occurrences, but not project-wide definitions.

A chapter may use the predefined index directly:

\index[Plato+Republic]
      {Plato+\emph{Republic}}

A project macro can hide the low-level syntax:

\WorkEntry
  {Plato+Republic}
  {Plato+\emph{Republic}}

An additional register defined as persons can receive an entry with:

\persons[Plato]{Plato}

The component does not need to know how either register will finally be formatted.

4. Place complete registers at product level

Register occurrences are collected while ConTeXt processes the components. The completed register should normally be placed once, after the main content:

\chapter{Indexes}

\subject{Index of concepts and works}

\placeregister[index]

\subject{Index of persons}

\placeregister[persons]

Placing the registers in a dedicated component keeps the product file short while preserving a clear back-matter structure.

Recommended pattern. Define registers in the environment, insert occurrences in content components, and place the completed registers in a final back-matter component.

5. MWE 1: collect one index from two components

This first project uses the predefined index register. Its configuration is stored in the environment, two components insert entries, and a final component places the complete index.

5.1. File 1: index-environment.tex

\startenvironment index-environment

\mainlanguage[en]

\setupbodyfont
  [libertinus,10pt]

\setuppapersize[A5]

\setupregister
  [index]
  [n=2,
   balance=yes]

\define[2]\WorkEntry
  {\index[#1]{#2}}

\stopenvironment

5.2. File 2: chapter-one.tex

\startcomponent chapter-one

\chapter{Plato}

\WorkEntry
  {Plato+Republic}
  {Plato+\emph{Republic}}

Plato's \emph{Republic} examines justice, education,
and the best political order.

\index[justice]{justice}

Justice is introduced as the central question of the dialogue.

\stopcomponent

5.3. File 3: chapter-two.tex

\startcomponent chapter-two

\chapter{Aristotle}

\WorkEntry
  {Aristotle+Politics}
  {Aristotle+\emph{Politics}}

Aristotle's \emph{Politics} compares constitutions
and forms of political rule.

\index[constitution]{constitution}

The classification of constitutions structures the inquiry.

\stopcomponent

5.4. File 4: indexes.tex

\startcomponent indexes

\chapter{Index}

\placeregister[index]

\stopcomponent

5.5. File 5: index-product.tex

\environment index-environment

\startproduct index-product

\component chapter-one
\component chapter-two
\component indexes

\stopproduct

Compile the product file:

context index-product.tex

ConTeXt reads the environment once, processes both chapters, collects every occurrence, and places the combined index in the final component.

What this example demonstrates. No chapter defines or places the index. The environment controls the register globally, while the product determines the order in which components are processed.

6. MWE 2: maintain several project-wide registers

A project may need separate registers for concepts, persons, works, places, or sources. Define all of them in the same environment.

6.1. Shared environment

\startenvironment multi-register-environment

\mainlanguage[en]

\setupbodyfont
  [libertinus,10pt]

\setuppapersize[A5]

\defineregister[persons]
\defineregister[works]

\setupregister
  [index]
  [n=2,
   balance=yes]

\setupregister
  [persons]
  [n=2,
   balance=yes]

\setupregister
  [works]
  [n=2,
   balance=yes]

\define[2]\PersonEntry
  {\persons[#1]{#2}}

\define[4]\WorkEntry
  {\setstructurepageregister
     [works]
     [entries:1={#2},
      keys:1={#1},
      entries:2={\emph{#4}},
      keys:2={#3}]
     []}

\stopenvironment

6.2. Entries in a component

\startcomponent political-philosophy

\chapter{Classical political philosophy}

\PersonEntry{Plato}{Plato}

\WorkEntry
  {Plato}
  {Plato}
  {Republic}
  {Republic}

Plato's \emph{Republic} examines
\index[justice]{justice}justice and political education.

\blank[small]

\PersonEntry{Aristotle}{Aristotle}

\WorkEntry
  {Aristotle}
  {Aristotle}
  {Politics}
  {Politics}

Aristotle's \emph{Politics} compares
\index[constitution]{constitution}constitutions.

\stopcomponent

6.3. Final register component

\startcomponent project-registers

\chapter{Indexes and registers}

\subject{General index}

\placeregister[index]

\subject{Persons}

\placeregister[persons]

\subject{Works}

\placeregister[works]

\stopcomponent

The three registers remain independent, but all of their definitions and typographical settings are centralised.

No PNG output is provided for this MWE because the example is designed primarily to demonstrate a multi-file project architecture rather than a distinctive typographical result. Its essential features are distributed across an environment file, a product file, several components, and a final index component. A single screenshot would show only the compact assembled page and would not make the relationships between those source files visible. The relevant result is therefore the successful compilation of the complete product and the collection of entries from all components into one project-wide index.

7. Centralise processors and editorial conventions

A project environment should also define the vocabulary used to distinguish kinds of occurrences.

For example:

\defineprocessor
  [main]
  [style=bold]

\defineprocessor
  [passing]
  [style=italic]

Components can then record the editorial role without deciding its visual form:

\index[main->justice]{justice}

or:

\index[passing->education]{education}

Changing the processor definitions in the environment updates the complete project.

The environment is also the right place to define conventions such as:

whether work titles are italicised;
whether personal names are displayed in natural or inverted order;
whether leading articles are ignored in title sorting;
which abbreviations identify principal and secondary references;
which registers use one or two columns;
whether repeated page references are compressed.

Editorial consistency. A multi-file project should not allow each chapter to invent its own sorting keys, hierarchy, processor names, or displayed forms. Define these conventions before large-scale indexing begins.

8. Use project macros as a stable authoring interface

Low-level register syntax may expose more detail than component authors need. A shared macro can establish a stable project interface.

For example:

\define[4]\RegisterWork
  {\setstructurepageregister
     [works]
     [entries:1={#2},
      keys:1={#1},
      entries:2={\emph{#4}},
      keys:2={#3}]
     []}

A component then supplies only the data:

\RegisterWork
  {Plato}
  {Plato}
  {Republic}
  {Republic}

This approach has several advantages:

the register structure is defined once;
component files remain readable;
sorting and display data remain separate;
the implementation can change without rewriting every chapter;
XML or Lua workflows can later call the same wrapper.

Stable interface. Treat project macros as a contract between content files and the register system. Components supply data; the environment decides how that data becomes a register occurrence.

9. Compile the complete product and individual components

The complete register can only be verified when all relevant components are processed together.

Compile the product:

context index-product.tex

A second run may be required before all page references and register entries stabilise.

Individual components can still be useful for checking local text and syntax, but a component compiled alone does not necessarily contain the final page numbers or the complete register.

9.1. Keep component tests predictable

When standalone component testing is required, load the same environment used by the product. Do not create a second, slightly different set of register definitions for testing.

A small test wrapper may be preferable:

\environment index-environment

\starttext

\component chapter-one

\subject{Temporary index}

\placeregister[index]

\stoptext

This wrapper checks one chapter without changing the chapter source itself.

10. Avoid conflicting or duplicated definitions

The following patterns should be avoided.

10.1. Repeating \defineregister in several components

Do not write this in every chapter:

\defineregister[persons]

Define the register once in the environment.

10.2. Applying different setup values in different chapters

Conflicting declarations such as:

\setupregister[index][n=1]

in one component and:

\setupregister[index][n=2]

in another make the result depend on processing order.

Keep the final project-wide setup in the environment.

10.3. Placing the same complete register more than once

A chapter-level \placeregister[index] does not mean “place only the entries from this chapter” unless a local-register mechanism has explicitly been configured.

For a single project-wide index, place the register once in the back matter.

10.4. Using inconsistent sorting keys

These entries may look identical but sort differently:

\index[Plato]{Plato}

\index[plato]{Plato}

Choose one project-wide sorting convention and apply it consistently.

11. Diagnose common project problems

11.1. Entries from one component are missing

Check:

whether the component is included in the product;
whether the occurrence command is executed;
whether the correct register instance is used;
whether the product has been processed again.

11.2. The same register has different formatting in different places

Cause: Register settings are repeated or overridden in components.

Solution: Move the final \setupregister configuration to the environment.

11.3. A custom register command is undefined

Cause: The environment was not loaded before the component.

Solution: Load the environment in the product or test wrapper before processing the component.

11.4. The product shows an earlier index state

Cause: Register data has not yet stabilised across processing runs.

Solution: Process the product again.

11.5. Component compilation works, but product compilation fails

Cause: The component test may load different definitions or may not reveal naming conflicts present in the complete project.

Solution: Use the same environment for both tests and inspect duplicate macro, processor, register, or component names.

11.6. A register is defined as its own parent

Do not write:

\defineregister
  [works]
  [works]

Use:

\defineregister[works]

The second argument of \defineregister is not a repeated name; it identifies a parent register.

12. Choose where each kind of code belongs

Code	Recommended location
`\defineregister`	Environment
`\setupregister`	Environment
`\defineprocessor`	Environment
Project insertion macros	Environment
`\index` and other occurrence commands	Components
XML or Lua lookup functions shared by the project	Environment or dedicated shared file loaded by the environment
`\placeregister`	Final product or back-matter component
Temporary register placement for testing	Separate test wrapper

Project rule. Put reusable definitions in shared files, occurrences beside the content they describe, and final register placement where the complete product structure is assembled.

13. What this guide has established

A project-wide index is not produced by giving each chapter its own independent index configuration. It is produced by sharing one configuration across all components.

The recommended workflow is:

define registers, processors, and insertion macros in an environment;
load that environment before processing the product;
insert occurrences in the relevant components;
use stable sorting and display conventions throughout the project;
place the completed registers in a final back-matter component;
compile the complete product until page references stabilise.

The resulting architecture keeps responsibilities clear:

the environment defines behaviour;
components supply content and occurrences;
the product assembles the document;
the final register component places the collected results;
ConTeXt performs collection, sorting, duplicate handling, page aggregation, and typesetting.

Key conclusion. Centralising index management does more than reduce repetition. It establishes one editorial policy for the complete project and gives every component a stable interface for contributing register data.

14. See also