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.

Fast start

#import "@preview/glossarium:0.5.1": 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!

Take a look at:

• acrostiche
• glossy

and many others

Detailed guide

Import and setup

Import the package from the typst preview repository:

#import "@preview/glossarium:0.5.1": 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.1": 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

*WHY DO WE NEED THAT?*

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

*SHOW RULES CONFLICTS*

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.

Key	Type	Required/Optional	Description
key	string	required	Case-sensitive, unique identifier used to reference the term.
short	string	semi-optional	The short form of the term replacing the term citation.
long	string or content	semi-optional	The long form of the term, displayed in the glossary and on the first citation of the term.
description	string or content	optional	The description of the term.
plural	string or content	optional	The pluralized short form of the term.
longplural	string or content	optional	The pluralized long form of the term.
group	string	optional	Case-sensitive group the term belongs to. The terms are displayed by groups in the glossary.

#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",
  ),
)

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 is done using the key of the terms using the gls function or the reference syntax.

// referencing the OIDC term using gls
#gls("oidc")
// displaying the long form forcibly
#gls("oidc", long: true)

// referencing the OIDC term using the reference syntax
@oidc

Handling plurals

You can use the glspl function and the references supplements to pluralize terms. The plural key will be used when short should be pluralized and longplural will be used when long should be pluralized. If the plural key is missing then glossarium will add an 's' at the end of the short form as a fallback.

#glspl("potato")

Please look at the examples regarding plurals.

Overriding the text shown

You can also override the text displayed by setting the display argument.

#gls("oidc", display: "whatever you want")

Styling references links

I recommend setting a show rule for the links to that your readers understand that they can click on the references to go to the term in the glossary.

#show link: set text(fill: blue.darken(60%))
// links are now blue !