Add support for global abbreviations/acronyms

[gavlinski]

Hi! After searching a lot, I couldn't find a way to define terms like abbreviations/acronyms in a single file, like a glossary, and import it on all pages with content using Hugo. Could you please tell me if it would be possible to implement this in your framework? Or maybe give me some tips on how to do this using shortcodes or partials.

It could be something similar to what was done in Material for MkDocs:

• https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-abbreviations
• https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary

Thank you very much.

[razonyang]

Yep, it's possible, will create a PR/module for this those two day.

[razonyang]

I added a new abbr shortcode, to use it, you'll need to upgrade the module to latest version.

hugo mod get github.com/hugomods/shortcodes@v0.13.1

See https://hugomods.com/docs/shortcodes/abbr/ for detail usage.

This shortcode use native HTML without Bootstrap tooltips component, let me know if your want to apply the tooltips on it.

The tooltips abbr will be provided in new module, since it introduces a new JS component, which may not used by others users.

[gavlinski]

I've just tested the new abbr shortcut and it's working great. But reading the data file is not. Do I need to wait a little longer for the next publication, or mabe update some other module? I named the data file as data/abbreviations/pt-br.toml.

Another question: is there any way to reference the term/expression just by using brackets like [term]? Because using the shortcode syntax {{< abbr "term" >}} ends up making the readability of the markdown file's source code a little difficult.

[razonyang]

I think it's a case-sensitive issue on lanagugeCode, upgrade to /~https://github.com/hugomods/shortcodes/releases/tag/v0.13.2 should fix it.

is there any way to reference the term/expression just by using brackets like [term]?

Yep, you can extend the link syntax using render-link hook, I need to think carefully about having this in HB, since it's non-standard CommonMark syntax. I'm not sure if it will break things or there is side-affect.

I can provide the working render hook if you want to use it on you site without waiting this feature.

1. Please create your own layouts/_default/_markup/render-link.html with following content.

{{- $dest := .Destination -}}
{{- if eq $dest "ABBR" }}
  {{- $text := .Text | string }}
  {{- $title := .Title }}
  {{- if eq $title "" }}
    {{- with index site.Data.abbreviations (lower site.Language.LanguageCode) }}
      {{- with index . $text }}
        {{- $title = . }}
      {{- end }}
    {{- end }}
  {{- end }}
  {{- if eq $title "" }}
    {{- warnf "[abbr] missing title for %q" $text }}
  {{- end }}
  <abbr title="{{ $title }}">{{- $text -}}</abbr>
{{- else }}
  {{/* See /~https://github.com/hbstack/base/blob/main/layouts/_default/_markup/render-link.html. */}}
  {{- if hasPrefix $dest "#" -}}
    {{- $dest = printf "%s%s" .Page.RelPermalink $dest -}}
  {{- end -}}
  {{- $target := $dest | safeURL -}}
  {{- $external := partial "base/functions/is-url-external" $target -}}
  <a
    href="{{ $target }}"
    {{ with .Title }}title="{{ . }}"{{ end }}
    {{ if $external }}target="_blank" rel="noopener noreferrer"{{ end }}>
    {{- .Text | safeHTML -}}
  </a>
{{- end }}

2. Create data files like the abbr shortcode requires.

// data/abbreviations/pt-br.toml
hello = "world!"

3. Syntax: [TERM](ABBR TITLE)

• TERM the key/term of abbr.
• ABBR indicates it's an abbr element instead of link, of course, you can modify it to be empty string in template to simplify the syntax.
• TITLE optional title, if present, it'll override the one taken from data file.

[hello](ABBR) and [hello](ABBR "anohter world")

Please feel free to share your feedback, it would be helpful to decide whether we should have it in HB.

[gavlinski]

Confirmed that version 0.13.2 fixed the issue. Thank you very much!

I agree that using [hello](ABBR) is better than using the shortcuts syntax. Your instructions worked perfectly. Thank you for providing all the details with examples of how to use it.

However, if the person responsible for editing the content needs to manually reference each term, I consider it better to declare the terms on the same page, even if they are repeated across several pages.

In the Glossary solution implemented by the Material for MkDocs theme that I mentioned earlier, there is no need to make any references. All terms declared in the abbreviation file are automatically replaced on all pages of the site.

[razonyang]

Yes, that's a much easiler syntax, but I can confirm that it's not supported by Hugo and goldmark currently.

I created a discussion on goldmark, you can follow that to track latest response, but I don't think it will happen fast, so for now I'd suggest using shortcode way until this feature was added.

[razonyang]

I'm closing this, please subscribe the discussion instead.