You can define Terms and generate reference pages for them with Glossaries and Index Pages. This allows you to centralize definitions and pointers to where various items are mentioned throughout your documents.
Glossaries¶
Glossaries are a collection of definitions for Terms in your documents. Below is the example of a glossary defining the terms glossary, term, and index
- glossary
- A glossary is a list of terms and their definitions.
- term
- A term is a word with a specialized meaning.
- index
- An organized list of information in a publication.
- index entry
- A word or phrase that has been marked for inclusion in the index with the
indexdirective or role.
To add a glossary to your content, add the {glossary} directive with the content as definition lists.
You can define multiple glossaries in your documents, as long as they do not re-define the same term.
Compatibility with Sphinx and reStructuredText
The glossary is very similar to the reStructuredText glossary, but uses definition lists instead of indentation to indicate the terms[2]. For working with glossaries in Sphinx, you can use the following syntax:
```{glossary}
Term one
An indented explanation of term 1
A second term
An indented explanation of term 2
```Terms¶
To reference a term in a glossary use the {term} role:
{term}`MyST`produces MyST{term}`MyST Markdown <MyST>`produces MyST Markdown
The label that you use for the term should be in the same case/spacing as it appears in the glossary. If there is additional syntax (e.g. a link) in the term, the text only representation will be used. The term is rendered as a cross-reference to the glossary and will provide a hover-reference.
Index pages¶
Index pages show the location of various terms and phrases you define throughout your documentation. They will show an alphabetized pointer to all Terms and Index entries that you define.
Index entry directive¶
You can define index entries with Directives like so:
:::{index} my first index item
:::In this case, no text will be displayed with the directive, but an index entry will be created in your index that points to the location of the directive.
You can define a nested index entry with a semicolon (;)
:::{index} index parent; index child
:::Also, you can define multiple, non-nested index entries in the directive argument by delimiting with a comma:
:::{index} index one, index two, index three
:::Pairs and Triples¶
You can generate two reciprocal, nested index entries with pair:, like so:
:::{index}
pair: index one; index two
:::or for three related items:
:::{index}
triple: index one; index two; index three
:::You can define multiple index entries in a single directive by putting them on multiple lines. In this case each entry must have a prefix of (single, pair, or triple to distinguish what specific nested entries are created).
:::{index}
single: index one
single: index parent; index child
pair: index two; index three
pair: index four; index five
triple: index six; index seven; index eight
:::See and See Also¶
For one index entry to reference another index entry, you may use the see or seealso prefix. For example,
:::{index}
see: index 1; index one
:::This creates an entry like “index 1: See index one”
The prefix seealso: behaves identically but uses the text “See also” instead of “See.”
Emphasis¶
To emphasize any index entry, add an exclamation point before the index term. This will style the entry as either bold or italic and move it before other entries that refer to the same term but are not emphasized.
:::{index} ! index one
:::Index entry role¶
You can define an index entry with a role like so: {index}`my second index`.
This includes the text “my second index” in your content and creates an entry.
If you want the text to be different than the index entry, you may use the syntax {index}`text on the page <index term>`.
Index roles can use all the same prefixes as described for the {index} directive, including single, pair, triple, see, and seealso. For example, {index}`pair: index one; index two` or {index}`text on the page <pair: index one; index two>`.
Generate an index¶
You can show an index on a MyST page with the {show-index} directive.
For example:
```{show-index}
```See the index for this documentation for what this generates.
Abbreviations¶
To create an abbreviation, you can explicitly do this in your document with an abbreviation role, for example, {abbr}`HR (Heart Rate)`. You can also use the page or project frontmatter:
The abbreviations are case-sensitive and will replace all instances[1] in your document with a hover-tooltip and accessibility improvements. Abbreviations in cross-references, code, and links are not replaced. For example, in this project we have a lot of abbreviations defined in our myst.yml:
Our OA journal ensures your VoR is JATS XML with a PID (usually a DOI) to ensure LTS.
- TLA Soup
Order of Abbreviations¶
Abbreviations defined in your frontmatter are applied in longest-sorted order. If you have two abbreviations with the same suffix (e.g. RHR and HR), the longer abbreviation will always take precedence.
To have longer abbreviations not be transformed, or if that string is included in another word, explicitly set them to null in your frontmatter. In the following example, HTML will not have the letters ML as an abbreviation.
