The principal mention of a term

A term is usually discussed properly in one place and mentioned in passing in others. mention="principal" says which occurrence is the proper one, and the index emphasizes that locator alone — the convention a printed index uses for what it calls a principal reference.

Cats are mentioned here: [cats]{.index}.

Cats are discussed here: [cats]{.index mention="principal"}.

In a PDF that prints as cats, 3, **7**; in HTML the numbered link for the principal mention is emphasized and carries the class qi-principal, and the others do not. Mark as many other mentions as you like — only the ones you give the role to are emphasized, and a term with no role anywhere is unchanged.

Redefining the emphasis. The LaTeX back-end wraps the locator in \quartoindexprincipal, defined with \providecommand as \textbf and injected, with the machinery that applies it, only into a document that uses it. Define your own in the document’s preamble and yours is kept — a document’s own header text lands above what a filter injects, so the extension’s definition steps aside:

\newcommand*\quartoindexprincipal[1]{\textit{#1}}

In HTML the extension ships no stylesheet, so the link carries a <strong> as well as the class; style .qi-principal to change it.

One case prints unemphasized. makeindex folds three or more consecutive pages under one entry into a range of its own, and the emphasis is applied by looking a page up by the number the index prints — which a range like 3--5 is not. So a principal mention whose page is anywhere in such a folded range, its first page included, prints plain, silently. Nothing else about the entry changes and no other locator is affected. This is only about a range the tool folded for itself: a range you wrote with range= is one the extension knows about, and it prints emphasized whole (see A discussion that spans pages).

Deleting marks never breaks the next render on a leftover build file. The emphasis machinery writes its page registrations into the document’s .aux, and the compiled index in the .ind carries the commands that print a locator and a cross-reference. Either file can outlive the marks that wrote it — latex-clean: false, or a failed render, leaves it in place. A document whose principal, range or cross-reference marks have since been deleted — every mark included — still defines every command those leftover files name, so the next render builds cleanly: the .aux lines are read and do nothing, and the pages and targets a stale index holds print as the ordinary locators and cross-references they now are. The leftovers are gone as soon as that render rewrites the two files.

A role needs a locator to apply to. A cross-reference takes the place of a locator, so mention="principal" on a mark that also carries see= or see-also= has nothing to emphasize. The role is reported and dropped, and the mark indexes exactly as it would without it.

There is one exception, and it can differ between the back-ends. A target naming the entry it is written on says nothing, so it is dropped — and the mark then does have a locator, and keeps its role. The PDF index stores three levels and folds anything deeper into the third, so a target can match the entry only once folded: there the target is dropped and the role applies, while in HTML and EPUB, which fold nothing, the same target stands and the role is dropped. The same mark can therefore be emphasized in the PDF and plain in the other two. The reports say which happened in each render.

Only principal is recognized. Any other value is reported and the mark indexes as though the attribute were absent — including an empty one, since mention="" is a value you wrote rather than an attribute you left off.