Reference, Glossary: implement Hugo Taxonomy mechanisms

[cmjc]

Description

The glossary is added as a reference page with sub headings and terms linked to these headings from the docs. So, the taxonomy of terms is not structured or formally represented.

The Hugo Taxonomy model mechanism supported by the Docsy theme being used for the site is not being used. Cf. https://www.docsy.dev/docs/adding-content/taxonomy/

Other Docsy sites have developed custom {{ code-templates }} to provide:

• tool tip showing the term definition during hover
• term inclusion to pull in the term definition for content reuse (avoiding varying term explanations throughout the docs).

This is a nice-to-have feature.

Rationale

• Define once and re-use to mitigate risk of duplicate definitions in text
• Structured representation of glossary terms, i.e. terminology management is implemented using native Hugo Docsy mechanisms
• Improve UI / UX by having hover text over glossary terms

Implementation

Some nice examples and discussion threads can be found in these projects:

• Of hover and term definition inclusion (see underlined words and entry for etcd):

  • Page: https://kubernetes.io/docs/concepts/overview/components/
  • Raw md: https://github.com/kubernetes/website/blob/main/content/en/docs/concepts/overview/components.md
  • https://kubernetes.io/docs/contribute/style/hugo-shortcodes/#glossary
  • https://github.com/wowchemy/wowchemy-hugo-themes/issues/1858#issuecomment-699546523

• Hugo Docsy pages on TAxonomy:

  • Categories/Taxonomies - https://www.docsy.dev/categories/taxonomies/
  • Taxonomies - https://gohugo.io/content-management/taxonomies/

• An alternative approach

  • Implementing << Rich CSS Tooltip >> in Hugo - https://shaik.link/posts/hugo-rich-css-tooltip/

[cmjc]

@dweng0 - with the migration from Hugo to Quarto, this is looking like legacy. So, closing.

I can't locate an appropriate Quarto taxonomy mechanism that could be a replacement for the Hugo mechanisms:

• I've been looking at https://quarto.org/docs/websites/website-listings.html#categories, but this is for adding category classification(s) to a page.

• I can't find anything in https://quarto.org/docs/guide/ for structuring glossary terminology, or pulling in text to use as a tooltip when hovering over a glossary term hyperlink in a page.

If you know of a Quarto compatible taxonomy mechanism, shout out please...