Skip to article content

To add a glossary to your content, add the {glossary} directive with the content as definition lists.

The glossary can be in a different page, as long as it is parsed by your project. See an example glossary.

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:

Term one
  An indented explanation of term 1

A second term
  An indented explanation of term 2

Referencing a Term

To reference a term in a glossary use the {term} role:

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.


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

The order of abbreviations in your frontmatter should specify the longer abbreviations first (e.g. RHR) and then the shorter abbreviations (e.g. HR). If you do this in the opposite order, you will have an abbreviation for RHR.

MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication