Create an index of terms and sections to facilitate search and discovery

Description / Summary

Although free text search provides one way of easily generating a concordance list of items that match a particular search term (from search term to results pages) and glossaries provide links from glossed item to the glossary entry, it may be hard for a reader to gain a sense of the shape, balance and substance of a document simply by reviewing the table of contents items, or within a page, the header items.

For a discussion of indexing vs. free text search, see: What is wrong with full text searches and Search, or use the index?.

In print works, indexes play a varied role:

• they capture high level concepts;
• they provide a novice reader with a rich and relevant vocabulary of relevant terms and topics;
• they give a sense of the distribution of terms across a work, both in terms of spread/location and weight/prevalence.

Are there extension that allow an author to create a notion of an index?

I’m thinking of something that would:

• allow an author to add a relative anchor within a section to associate it with an index term. For example, {index}`my index term` . Note that this might be a hidden reference link, eg to a space or   character. Significant index references might be identified as some variant of {index!}`my index term` (where the ! is positioned so as to simplify parsing and minimise potential ambiguity.
• automatically generate index terms at a particular location;

```{index}
:autogenerate: True
:order: alphabetical
```

• generate index entries; note that identifying the location of entries may be difficult if page numbers are not available. One solution might be to generate parent heading, or heading path, entries for each index location and return these rather than page numbers. Significant index items might be identified using strong emphasis, for example.

Value / benefit

Indexes provide several benefits to the reader / user who is trying to discover information.

Indexes provide a macroscopic birds eye view of the structure of a document, including:

• appropriate search terms / concepts;
• an overview of the distribution of concepts.

Implementation details

The glossary machine provides machinery for generating links between referred items and a glossary item directory.

A major issue is how to address the location of indexed items in the absence of page numbers. Faceted browsing interefaces might also suggest ways of displaying indexes as a whole, or at the index item level.

By observation, LaTex may provide clues as to how to specify and manage indexing requirements at a technical level.

Tasks to complete

This is initially proposed as a discussion topic.

[jmshea]

One practical consideration is that index terms created this way disappear when a Jupyter notebook MD cell is “run”:

[jmshea]

I can confirm that

```{index} Some index
```

works. I’ll run some tests on the other variants and report back soon!