References notes and floats/Registers and index

🚧 Under construction — This page and its subpages are currently being revised. Contributions are welcome: feel free to correct, expand, and improve them. Existing command-reference pages remain available.

1. What this documentation is for

An index helps readers find where a person, concept, work, place, command, or other subject is discussed in a document.

In the simplest case, an author marks selected expressions in the running text and places one alphabetical index at the end:

\starttext

Plato\index{Plato} discusses justice\index{justice}
in the \emph{Republic}\index{Republic}.

\completeindex

\stoptext

ConTeXt can also manage:

principal entries and subentries;
explicit sorting keys;
“see” cross-references;
several independent registers;
selected entry and page-reference formatting;
explicit page ranges and compressed references;
registers limited to a chapter or section;
language-sensitive sorting;
right-to-left and bidirectional registers;
entries generated from XML or other structured data;
project-wide indexing conventions.

Purpose of this page

Use this page to identify the indexing mechanism you need and choose the appropriate tutorial, how-to guide, reference page, explanation, or glossary entry.

It is an orientation page, not a complete command reference.

Basic vocabulary: index and indexing

An index is a structured finding aid placed in a document. It brings together selected names, concepts, works, places, or other subjects and associates them with the pages or locations where they are discussed.

Indexing is the editorial process of constructing that finding aid. It involves:

deciding what readers may need to find;
selecting significant occurrences;
choosing consistent entry forms;
distinguishing principal entries from subentries;
defining sorting forms and cross-references;
associating entries with pages or page ranges;
reviewing the resulting index for clarity and consistency.

An index entry is one item recorded in the index, such as “justice”, “Plato”, or “Plato — Republic”.

In ConTeXt, the standard index is implemented as the predefined register named index. A register is the more general technical mechanism used to collect, sort, group, and place entries with references.

Indexing is therefore not merely the insertion of \index commands. It is an editorial activity in which ConTeXt records, organises, and typesets decisions made by the author or editor.

2. Documentation map

The documentation is organised according to the Diátaxis method. Choose the page that corresponds to the kind of help you need.

Documentation type	Page	Use it when you need to...
Tutorial	Creating and formatting your first index	Learn the basic workflow by creating, placing, and formatting a complete index step by step.
How-to guide	Structuring index entries and cross-references	Create principal entries, subentries, sorting keys, and “see” cross-references.
How-to guide	Formatting an index	Control columns, alphabetical indicators, entry styles, page-reference styles, colours, spacing, alignment, and headings.
How-to guide	Creating multiple registers	Create separate indexes of people, concepts, works, places, sources, or other editorial categories.
How-to guide	Formatting selected entries and page references with processors	Apply special formatting to selected entries or selected page references.
How-to guide	Managing page ranges and compressed references	Create explicit page ranges and combine repeated references occurring on consecutive pages.
How-to guide	Creating local and sectional registers	Place a register limited to the current chapter, section, or local structural context.
How-to guide	Sorting multilingual registers	Configure language-sensitive sorting, letter case, diacritics, and specialised sorting methods.
How-to guide	Typesetting bidirectional registers	Typeset Arabic, Hebrew, or mixed-direction registers and control the physical order of columns.
How-to guide	Managing structured register data	Generate and manage register entries from XML or other structured sources.
How-to guide	Managing indexes in a project environment	Centralise register definitions, processors, sorting conventions, and formatting in a multi-file project.
Reference	Index and register command reference	Look up command syntax, parameters, accepted values, and related command pages.
Explanation	Explanation of indexes and registers	Understand how entries, sorting forms, processors, references, registers, and placement interact.
Glossary	Glossary of index and register terminology	Check the precise meaning of the principal technical and editorial terms.

Documentation still to be completed

Some advanced how-to guides and the glossary may not yet exist or may still be under construction. Red links identify pages that remain to be created.

Where should you begin?

If you have never created an index in ConTeXt, begin with the tutorial.

If you already have a working index and need to solve one particular problem, choose the corresponding how-to guide in the table above.

If you need command syntax or accepted parameters, consult the reference.

3. Indexes and registers in ConTeXt

In ConTeXt, the standard index is the predefined instance named index of the more general register mechanism.

The command:

\index{entry}

adds an entry to that predefined register.

Conceptually:

\index
    ↓
predefined instance named "index"
    ↓
general register mechanism

A new named register can be created with:

\defineregister[author]

ConTeXt then provides register-specific entry and placement commands corresponding to the general register interfaces.

For example:

\author{Plato}
\placeauthor

The standard index and a named register therefore follow the same general workflow:

Operation	Standard index	Named register
Define	Predefined as `index`	`\defineregister[name]`
Add an entry	`\index{...}`	Generated register command
Configure	`\setupregister[index][...]`	`\setupregister[name][...]`
Place	`\placeindex` or `\completeindex`	Generated placement command or `\placeregister[name]`

Key distinction

The standard index is not a separate mechanism. It is the predefined register named index.

Learning how the standard index works therefore provides the basis for creating registers of people, concepts, works, places, commands, sources, or any other editorial category.

For a fuller account of the collection, sorting, reference, and placement workflow, see:

Explanation of indexes and registers.

4. Choose the mechanism you need

Not every collected list of information should be implemented as a register.

You need to collect...	Use...	Typical commands or mechanisms
Terms, names, or subjects sorted alphabetically and linked to locations	A standard index	`\index`, `\placeindex`
Several independent alphabetical indexes	Named registers	`\defineregister`, generated register commands
Titles or sections kept in document order	A structural list	Section heads, lists, `\placelist`
Figures or tables kept in document order	A float list	`\placelistoffigures` and related list commands
Bibliographical records ordered and formatted according to a citation style	The bibliography subsystem	Bibliographical datasets, styles, and renderings

A register is not simply any list

Choose a register when entries must be sorted and associated with locations in the document.

Choose a structural list when entries must remain in document order and preserve structural information such as titles, authors, subtitles, or section numbers.

5. Start with a simple index

A first index requires only two operations:

mark entries in the running text;
place the collected index.

5.1. Mark an entry

Use:

\index{justice}

to record an occurrence and associate it with the current page.

Attach the command directly to the relevant text:

The argument concerns justice\index{justice}.

5.2. Place the index

Place the index without an automatically generated heading:

\placeindex

Or place it as a complete titled division:

\completeindex

5.3. Minimal working example

\starttext

Plato\index{Plato} discusses justice\index{justice}
in the \emph{Republic}\index{Republic}.

\completeindex

\stoptext

Recompile the document if the collected entries or page references are not yet resolved.

For a guided introduction, continue with:

Creating and formatting your first index.

6. How the documentation progresses

The practical guides move from ordinary editorial tasks to specialised workflows:

create a first index
        ↓
structure entries and cross-references
        ↓
format the index
        ↓
create several registers
        ↓
format selected entries and page references
        ↓
manage page ranges and local scope
        ↓
configure multilingual and bidirectional registers
        ↓
generate structured data and manage project-wide conventions

This progression separates three kinds of work:

Editorial decision	ConTeXt mechanism	Result
Decide what readers should be able to find	Entry commands and named registers	A selected set of index entries
Decide how entries relate and sort	Sorting keys, hierarchies, cross-references, and language settings	A coherent navigational structure
Decide how the index should appear	Register setup, processors, ranges, and placement	A readable final index

Indexing is both editorial and technical

ConTeXt can collect, sort, group, and typeset entries, but it cannot decide which concepts matter to the reader or which occurrences deserve indexing.

The quality of the final index depends on consistent editorial decisions as much as on correct commands.

7. Essential principles

7.1. Attach entries to running text

Prefer:

The concept of justice\index{justice} is central here.

Avoid placing an entry alone after vertical spacing or on an otherwise empty line. An unattached entry may not be associated with the intended page or text location.

7.2. Separate displayed form from sorting form

The displayed entry is what readers see. The sorting key determines where the entry is placed.

For example:

\index[CONTEXT]{\ConTeXt}

The entry is printed as \ConTeXt but sorted under CONTEXT.

Sorting keys control individual entries. The general sorting policy belongs to the register’s language and method settings.

7.3. Separate general formatting from selected formatting

Use \setupregister for formatting that applies to the whole register.

Use processors for selected entries or selected page references.

A processor applied to the entry text affects the displayed entry:

\index{important->concept}

A processor applied in the optional argument affects the page reference:

\index[important->]{concept}

7.4. Separate explicit ranges from compressed occurrences

An explicit range records one continuous discussion:

\startregister[index][justice-range]{justice}

The discussion of justice begins here.

\page

The discussion continues here.

\stopregister[index][justice-range]

Compression combines repeated occurrences recorded on consecutive pages:

\setupregister
  [index]
  [compress=yes]

These mechanisms are related, but they express different editorial decisions.

7.5. Separate language, sorting, and writing direction

Language-sensitive sorting, text direction, paragraph alignment, and the physical order of columns are related but distinct settings.

A multilingual or bidirectional register should therefore be tested with:

the exact languages used in the document;
the selected fonts;
the intended number of columns;
the current ConTeXt version.

7.6. Test specialised workflows with the current version

Structured interfaces, XML processing, Lua-generated entries, and historical examples may depend on the current ConTeXt version and the exact document structure.

Before adopting an advanced construction:

compile a minimal example;
test it in a realistic multi-page document;
verify sorting and page references;
inspect direction and column behaviour;
confirm that the commands are still active in the current version.

8. Related documentation

The following pages cover neighbouring mechanisms:

Page	Relation to indexes and registers
References notes and floats	General orientation for document elements that create references, annotations, and collected lists.
Footnotes	Notes may coexist with indexes and may themselves require separate placement and reference mechanisms.
PDF navigation	Page references in interactive documents may also act as PDF links.
Languages	Language settings influence sorting, labels, and writing direction.
Project structure	Project, product, component, and environment files can centralise register definitions and placement rules.
XML	XML workflows can generate structured register entries.
ConTeXt and Lua programming	Lua can validate, transform, or generate register data in advanced workflows.

Looking for command syntax?

Consult the index and register command reference for the syntax and principal parameters of \index, \defineregister, \setupregister, \placeregister, and related commands.

The existing command pages remain the detailed syntax layer of the documentation.

9. What this page has established

This orientation page has established that:

an index is a structured finding aid, while indexing is the editorial process that constructs it;
\index is the standard instance of the general register mechanism;
registers are appropriate for sorted entries associated with document locations;
structural lists, float lists, and bibliographies serve different purposes;
the documentation is divided into a tutorial, task-oriented how-to guides, a reference, an explanation, and a glossary;
entry selection, entry structure, sorting, reference collection, and final presentation are distinct stages of the workflow;
specialised multilingual, bidirectional, structured, and project-wide workflows should be tested with the current ConTeXt version.

The central principle is that indexing is not a single formatting operation but a coordinated editorial and technical workflow.

Indexes and registers in ConTeXt · Overview · Tutorial · How-to guides · Reference · Explanation · Glossary