Feature request: Glossary

[debruine]

I'd like to suggest a first-class glossary in quarto, where you can link terms in the text to definitions (perhaps displayed on hover) and collect defined terms into an optional glossary table or section at the end of a chapter or the end of a book.

See this twitter thread for discussion about this with Thomas Mock and the psyTeachR glossary package for a model of what I'm thinking about, implemented in R.

Some ideas

It could require defining terms somehow in the text each time, like:

{{< gls [term](This is my definition.) >}}

Or there could be a glossary file similar to _variable.yml that you can use to link terms to:

{{< gls [text-term](file-term) >}}

This letter option might be better, as you often want to link the same term several times, or link different forms (e.g., the definition might be for "argument", but your sentence is "There are several arguments you need to set.").

[jthomasmock]

This could build off existing mental model as a combination of a custom listing and extended footnotes, but more specialized key: value pairs and from my interpretation of Lisa's request, maybe a final glossary as well as singular inline "definitions".

I agree that some inspiration for an external JSON file or a YAML file, like custom listings or _pkgdown.yml implementation might work here. You’re going to write lots of other documents/shortcodes/definitions but can control the organization of combined glossary OR in-line glossary elements if desired. Otherwise, defaults to a fully combined glossary.

pkgdown example: https://github.com/r-lib/pkgdown/blob/main/pkgdown/_pkgdown.yml#L50-L64

@batpigandme also had an internal suggestion for MDN macros and their glossaries/indices: https://developer.mozilla.org/en-US/docs/MDN/Structures/Macros/Commonly-used_macros

The RStudio Connect team and @aronatkins create a pseudo-glossary for the Connect configuration settings: https://docs.rstudio.com/connect/admin/appendix/configuration/#Server.Settings but the formatting has been a bit of frustration.

[SHogenboom]

This is exactly the feature request I wanted to post!

I believe the latter option is the preferred solution - at least for books and other large projects. A specified glossary (e.g., _glossary.yml) with terms & definitions which upon rendering converts all terms to internal hyperlinks and adds a final glossary pages akin to what happens with the references.

I believe this method is preferred over manually adding glossary items because it prevents author(s) from forgetting to mark relevant terms. This becomes especially relevant when multiple authors work on different parts of a book/website or when chapters are added over time.

With regards to styling I could see two ideas for presenting the definitions: either with a hover effect (similar to rerefenced psyTeachR glossary package) and/or as a note in the side column.

Really hope this can become an internal feature of Quarto. For now, I'll use the very handy glossary package I did not know yet existed :)

[debruine]

@SHogenboom those are great ideas, but I have some caveats about auto-linking (based on a lot of experience implementing glossary links in educational materials):

• The auto-linking of terms should let you add variants so you can link the same definition to different verb forms or plural and singular versions.
• It would be good to have a manual option in addition to auto. When I write educational materials, I might want to link the term "argument" the first few times I use it, or the first time each chapter, but probably not 10 times in 1 paragraph.
• Auto-linking probably only makes sense in main text, not in tables or figure captions or code chunks. Working out the scope of where it is and isn't appropriate to auto-link might be more work than a manual demarcation option, like only link words marked by {{:term:}}.

P.S. I'm glad you think the glossary package will be helpful! I'd planned on sending it to CRAN after a little more development to make it easier to set up your own glossary website (it's currently pretty specialised for our PsyTeachR purposes), but I'm putting that plan on hold now until I find out what quarto is doing with built-in glossaries. I'd definitely add a way to easily make _glossary.yml files to it, if that's the direction quarto goes.

[SHogenboom]

@debruine you make some very good arguments against auto-linking! I understand now that manual option would be preferred. And if I really wanted to highlight a term across the entire project a search & replace would suffice (which excludes figures, tables, captions etc).

In the coming weeks I will likely adapt the PsyTeachR code so that it functions within the scope of a project with a csv or .RData file. And then also adjust the generated code to differ the output based on the document type. After all the hover over effect won't work in a PDF file and I also like the idea of showing definitions in the margins.

[cscheid]

@krionical when there are changes you'll see them here. We appreciate the enthusiasm, but do note that because we try hard to keep up with the issues here, every such question like this is time we don't get to work on quarto :)

[salim-b]

To potentially avoid over-engineering this glossary thing: Pandoc already supports definition lists, which for HTML output render to description list (<dl>) elements. I think it would really make sense semantically for Quarto to build upon this.

Currently, one has to manually add fragment identifiers to the definition terms to be referenceable in HTML output.
Example glossary.qmd:

# Glossary {.unnumbered}

[Term 1]{#term-id-1}

:   Definition 1... bla bli bla
    blup.

[Term 2]{#term-id-2}

:   Definition 2... bla bli bla
    blup.

With the above, we can link to glossary term 1 anywhere in our Quarto project via bla bla [Term 1](glossary.qmd#term-id-1) bla bla.

Now what's missing the most for a definition-list-based glossary are

1. auto-identifiers for definition list terms, so they don't have to (but still can) be manually set. Pandoc (and hence Quarto) already produces them for headings. A relatively simple Lua filter should be able to inject those identifiers in the Pandoc AST. Maybe this could even be something that Pandoc devs would incorporate upstream (I dunno).

2. proper cross reference support with autonumbering that produces human-parseable navigation hints (especially relevant for PDF output). To create such definition-list-cross-references, a new cross reference type @def- (or the like) would be nice, so we could link to a glossary term with ID term-id-1 via @def-term-id-1.

---

Update: Hugo (or it's underlying Markdown renderer Goldmark respectively) also supports the same definition list syntax as Pandoc. Hugo 0.144.0 brought auto-identifiers as outlined in point 1) above (via the parser.autoDefinitionTermID setting), so Quarto would be in good company supporting this, too.