Named indexes

A document can have more than one index — a subject index and an index of names, say. Declare them in the metadata, in the order they should print:

indexes:
  - name: main
    title: Index
  - name: people
    title: Index of Names

name is what a mark writes to file in that index; title is the heading a reader sees. A name holds ASCII letters, digits, hyphen and underscore and begins with a letter, because it becomes the id of the section that index prints under; an entry declaring any other name is reported and declares no index. A mark says which index it belongs to with index=:

[Cantor]{.index index="people"}

A mark that names no index files in the first declared index. So a document that declares nothing keeps the single index it has always had, and one that declares several needs index= only on the marks that go somewhere other than the first.

A placement marker names its index the same way, and each index is placed at the first marker naming it:

::: {.qi-index-here index="people"}
:::

A marker that names no index places the first declared one, exactly as a mark that names none files there. A declared index no marker names goes at the end of the document, in declared order. A second marker for one index is reported and places nothing; two markers naming two different indexes are not second markers for each other.

Every judgement this extension makes about a mark is made inside the index the mark belongs to. A cross-reference target resolves against the terms of its own index, a sort key files a term in its own index only, and a range pairs an opening with a closing of the same index. An opening in one index and a closing in another are not a pair: each is reported and indexes as an ordinary locator. A report of one of these judgements names the index it was made in, so a warning that a target names nothing indexed is telling you nothing in that index carries the term — the term may well be marked elsewhere in the document, in another index.

Every index in a PDF. A LaTeX or PDF render builds every index you declare, each at its own marker. Two different things build them. The first declared index is built by Quarto’s own PDF loop, which runs the index tool on the main entry file. Every index after it is built by imakeidx, the LaTeX package this extension loads, which runs the index tool itself — and that run goes through TeX’s restricted shell escape. A stock TeX Live or TinyTeX permits makeindex there, so a normal installation needs nothing from you. An installation that withholds that permission builds no index after the first: each of them prints empty, imakeidx says so in the LaTeX log, and this extension neither detects that nor works around it.

imakeidx names each index’s working files after the index rather than after the document, so a render leaves <name>.idx, <name>.ilg and <name>.ind beside your project for every index after the first. Quarto’s own cleanup knows only the main document’s files, so these stay behind.

Mark above the marker, in a named index. imakeidx closes an index’s entry file where that index is printed, so a mark below the placement marker for its own index reaches no index at all. The extension reports how many such marks a render found and which block the marker stands in; move the marker below the last mark filed in that index. The first declared index has no such limit — its entry file is held open past the place it is printed, so a mark written below the first marker still reaches the first index, and a mark filed in the first index is unaffected by where any other index’s marker stands.

Every index in an HTML book. An HTML book builds every index its chapters declare and file a mark in, the same as every other format: its chapters are aggregated through a per-chapter record that carries the index each mark files in. Each index is placed at the first marker naming it, in whichever chapter that marker stands; an index no marker names is printed after them, in declared order, at the end of the book’s last chapter.

That chapter is the end of the book’s own chapter list, which every chapter of every render reads the same way, so nothing here waits for a second render: every index a marker names is printed at that marker on the first render, and every index no marker names is printed in the book’s last chapter on the first render too. Where that chapter is one an author wants no index section in, the remedy is a marker for that index somewhere else. A book whose chapters carry no marker at all places no index, and grows no section in its last chapter either.

A chapter’s stored record outlives the render that wrote it. So a record naming an index you have since removed from indexes: — or renamed — is a record the book can still read but no longer place: its marks are filed in the first index the book does declare, and the report names the chapter and the name, so nothing is dropped and nothing is silent. Render that chapter again, or the whole book, once the declaration is settled.

examples/named-indexes.qmd declares two indexes and writes every one of those judgements across both — deliberately wrongly, so that a render of it draws each report in each index; examples/named-indexes-twin.qmd is the same terms in a document that declares none.

quarto render examples/named-indexes.qmd --to html
quarto render examples/named-indexes.qmd --to latex