Letter groups in the HTML index

The HTML index prints its top-level entries in groups, each introduced by a label of its own — one Symbols group, then one group per letter, A to Z.

A group label comes from the string the entry files under: its sort key where it has one, and its printed text where it has none. If that string begins with an ASCII letter the label is that letter, uppercased. Anything else — a digit, a punctuation mark, or an accented or non-Latin letter — files under Symbols. Nothing files under an empty string: a level that would print nothing is dropped before it gets this far.
The Symbols group comes first, ahead of A, the way a printed index sets it. A sort key is how you move an entry across that boundary, exactly as it is how you move one within a group.
Grouping is always on. There is nothing to switch on and no threshold below which it stops.
Only the top level is grouped. A sub-entry files under its parent rather than under a letter of its own, so no label appears inside a nested list.

Each label is a div carrying the class qi-letter and nothing else — a hook for your own CSS, and deliberately not a heading, so the alphabet does not land in your table of contents. As everywhere else here, the extension ships no stylesheet of its own.

The extension’s job ends at correct emitted output. Whether your toolchain then runs makeindex to build the index is up to your build setup; Quarto’s default PDF pipeline does it for you.

Setting the words and marks the index prints itself

Some of what a reader sees is the extension’s own rather than yours: this Symbols heading, the see and see also in front of a cross-reference, and the punctuation inside an entry — the mark in front of an entry’s locators, between one locator and the next, and in front of the first cross-reference, whether locators precede it or not (separator), and the mark between two cross-references (xref-separator). Set any of them under index-labels:, whose five keys are symbols, see, see-also, separator and xref-separator:

index-labels:
  symbols: "Zeichen"
  see: "siehe"
  see-also: "siehe auch"
  separator: "،"
  xref-separator: "؛"

Write the map in two places. At a document’s top level it covers every index that document has; inside one entry of indexes: it covers that index alone. Where both name a key the index’s own wins, key by key — an index that resets see keeps the document’s symbols and see-also — and a key you write nowhere keeps its English default.

The map is index-labels: and not labels: because a top-level labels: is Quarto’s own map, the one holding the words for its title block, and this extension does not read it.

A value a reader could not read is refused rather than printed, and the extension says so. Four shapes are refused: an empty value; a value made only of characters that print nothing, such as a non-breaking space, a zero-width space or one of the typographic spaces; a value written as a nested map; and one written as a list. The last two are what over-indenting the map by a level produces. A refused key falls back exactly as a key you never wrote does — to the same key at the document’s top level where an index’s own map wrote it, then to your lang: for the three words, and then to the English word or, for the two marks, which follow no language at all, straight back to , and ; — so a mistake here can only ever leave a reader with what this extension printed before you wrote anything. An index-labels: written inside an indexes: entry that is itself refused as a declaration sets no word either, and that is reported beside the reason the entry was refused.

Naming this heading after a letter one of the index’s own groups is already headed by — symbols: "A" in an index that files a term under A — is reported too, but not refused: the page still prints both groups, in their own places, under the one heading you gave it.

You only need this where the extension’s own choice is wrong for you. Left alone, the three words follow your document’s lang:: Spanish, French, German and Italian are covered, German for see and see also but not for this heading, and every other language keeps the English words. So a lang: es document heads this group Símbolos with nothing written under index-labels: at all. The two marks do not follow lang: at all: written nowhere they stay , and ;, so a document wanting other punctuation writes it out here. The Arabic marks above are the case they exist for; writing them does not make a right-to-left index come out right, which is a known limitation of this extension and not something these keys reach.

These words and marks reach the HTML and EPUB indexes only. A LaTeX index takes see and see also from babel, which sets them from your document’s lang:; it has no letter groups and so prints no Symbols heading at all, which is why symbols: has nothing to override there; and its punctuation comes from makeindex, which neither separator key reaches.