Typst glossary

[!TIP] Glossarium is based in great part of the work of Sébastien d'Herbais de Thun from his master thesis available at: https://github.com/Dherse/masterproef. His glossary is available under the MIT license here.

Glossarium is a simple, easily customizable typst glossary inspired by LaTeX glossaries package . You can see various examples showcasing the different features in the examples folder.

Screenshot of a glossary output using glossarium in Typst. A heading with text "Glossary" is displayed, and below four gloss are printed. Each gloss has its short and long form in bold separated by a dash. The description follows after a colon character. A list of the backreferences is given at the end.

Fast start

#import "@preview/glossarium:0.5.10": make-glossary, register-glossary, print-glossary, gls, glspl
#show: make-glossary
#let entry-list = (
  (
    key: "kuleuven",
    short: "KU Leuven",
    long: "Katholieke Universiteit Leuven",
    description: "A university in Belgium.",
  ),
  // Add more terms
)
#register-glossary(entry-list)
// Your document body
#print-glossary(
 entry-list
)

I don't like it!

Issues, PRs, and comments are welcome! If you are unsure where to post, create an issue and I will triage it.

Take a look at:

and many others

Detailed guide

Import and setup

Import the package from the typst preview repository:

#import "@preview/glossarium:0.5.10": make-glossary, register-glossary, print-glossary, gls, glspl

To use glossarium as a vendored module, download the package files into your project folder and import glossarium.typ:

#import "glossarium.typ": make-glossary, register-glossary, print-glossary, gls, glspl

To use glossarium locally, create a new package namespace on your system:

follows the instructions at typst/packages

import glossarium (if your namespace is named local):

#import "@local/glossarium:0.5.10": make-glossary, register-glossary, print-glossary, gls, glspl

Making the glossary

After importing the package and before making any calls to gls, print-glossary or glspl, please MAKE SURE you add this line

#show: make-glossary

[!NOTE]
<h3 align="center">*WHY DO WE NEED THAT?*</h3>
In order to be able to create references to the terms in your glossary using typst reference syntax @key glossarium needs to setup some show rules before any references exist.

[!CAUTION]
<h3 align="center">*SHOW RULES CONFLICTS*</h3>
Prefer to use the selector figure.where(kind: "image") or other kinds to avoid conflicts with glossarium_entry. make-glossary can conflict with global figure show rules. Write the user figure show rule before make-glossary to avoid any conflicts.

Registering the glossary

A term is a dictionary.

#register-glossary(entry-list)

#let entry-list = (
  // Use key as short by default
  (
    key: "kuleuven",
  ),
  // Add SHORT
  (
    key: "kuleuven",
    short: "KU Leuven"
  ),
  // Add LONG
  (
    key: "unamur",
    short: "UNamur",
    long: "Namur University",
  ),
  // Add a DESCRIPTION
  (
    key: "oidc",
    short: "OIDC",
    long: "OpenID Connect",
    description: [
      OpenID is an open standard and decentralized authentication protocol promoted by the non-profit
      #link("https://en.wikipedia.org/wiki/OpenID#OpenID_Foundation")[OpenID Foundation].
    ],
  ),
  // Add a PLURAL form
  (
    key: "potato",
    short: "potato",
    // "plural" will be used when "short" should be pluralized
    plural: "potatoes",
  ),
  // Add a LONGPLURAL form
  (
    key: "dm",
    short: "DM",
    long: "diagonal matrix",
    // "longplural" will be used when "long" should be pluralized
    longplural: "diagonal matrices",
    description: "Probably some math stuff idk",
  ),
  // Add a GROUP
  (
    key: "kuleuven",
    short: "KU Leuven",
    // The terms are displayed by groups in the glossary
    group: "Universities",
  ),
  // Add a CUSTOM entry
  (
    key: "c",
    short: $c$,
    description: "Speed of light in vacuum",
    // The custom key will be ignored by the default print-glossary function
    custom: (unit: $op("m s")^(-1)$),
  ),
)

Printing the glossary

Now, you can display the glossary using the print-glossary function.

#print-glossary(entry-list)

By default, the terms that are not referenced in the document are not shown in the glossary, you can force their appearance by setting the show-all argument to true.

You can also disable the back-references by setting the parameter disable-back-references to true.

By default, group breaks use linebreaks. This behaviour can be changed by setting the user-group-break parameter to pagebreak(), or colbreak(), or any other function that returns the content you want.

You can call this function from anywhere in your document.

Referencing terms

Referencing terms can be done in different ways. The function with the largest flexibility is gls. All others are shortcuts populated with different default parameters.

// Referencing the OIDC term using gls
#gls("oidc")
// Displaying the first form forcibly
#gls("oidc", first: true)
// Do not add a link
#gls("oidc", link: false)
// Do not update the usage count. If done on first use, the next reference will trigger printing the full version.
#gls("oidc", update: false)

The graph below is an overview of the available interface groups and their individual functions/modifiers.

graph TD;
    gls;
    gls-x["**Access values**"<br>-----------------<br>gls-key<br>gls-short<br>gls-artshort<br>gls-plural<br>gls-long<br>gls-artlong<br>gls-longplural<br>gls-description<br>gls-group<br>gls-sort<br>gls-custom];
    xgls["**Capitalizing, <br>Article, Plural**"<br>-----------------<br>Gls<br>agls<br>Agls<br>glspl<br>Glspl];
    at-syntax["**@key syntax <br> modifiers**"<br>-----------------<br>@key:pl<br>@Key<br>@Key:pl<br>@key:short<br>@key:long<br>@key:description<br>@key:longplural<br>@key:custom];

    gls --> gls-x;
    gls --> xgls;
    gls --> at-syntax;

Usually, you will want to use Typst reference syntax (@ syntax). This is the most practical way to reference an entry. By default, some shorthands are made available: plural, capitalize, capitalized plural, short and long.

// Prints the full version on first usage, short afterwards
@oidc
// Will always display the long version
@oidc:long
// Display the plural form
@oidc:pl

More are available: description, longplural and custom corresponding respectively to @key:description, @key:longplural and @key:custom.

This setting is managed when you print the glossary

print-glossary(
  entry-list,
  // default shorthands
  shorthands: ("plural", "capitalize", "capitalize-plural", "short", "long"),
)

The different interfaces have different default parameters which you should keep in mind when using them. In most cases, you will not need to manually set update: false, unless you are using gls in sit

Glossarium

Install / Use

README