Defining acronyms in external file(s)

Learn how to define acronyms in one or several external files, which can be reused throughout documents or projects (rather than directly in the YAML metadata).

Whereas defining acronyms directly in the YAML metadata is the most straightforward way, acronyms also support reading definitions from one (or several) pseudo-YAML file.

Referring to an external definition file in a Quarto document

To do so, simply specify the file path in the fromfile attribute of the YAML metadata. This behaviour is particularly useful if you want to define acronyms in the same file for multiple projects, or generate it automatically, in a similar way to the .bib files for LaTeX citations.

This attribute may be either a single path, for example:

---
acronyms:
  fromfile: ./acronyms.yml
---

or a list of paths, for example:

---
acronyms:
  fromfile:
    - ./acronyms1.yml
    - ./acronyms2.yml
---

Note that the path may be either absolute or relative. If the path is relative, it is resolved with respect to the current working directory of Pandoc. By default, when using Quarto, this working directory is set to the directory containing the source qmd file.

In our examples, we thus assume that the acronyms.yml (respectively, acronyms1.yml and acronyms2.yml) live in the same folder as the qmd document.

Content of the definition file(s)

These files support 2 different formats.

  1. The “original”, metadata-like format:
---
acronyms:
  keys:
  # Define your keys here
    - shortname: qmd
      longname: Quarto document
---

This format is exactly as you would write in the “main” Quarto document, except that only the acronyms.keys field is used. Any other field or content will be ignored.

  1. The “simplified” format, key-value like:
---
# Define your acronyms directly here as shortname: longname
qmd: Quarto document
---

This format is much shorter and easier to read; however, you cannot define the acronyms’ keys, and cannot use spaces in the shortname (but you should avoid doing so anyway).

Please note that these formats are not really YAML; instead, the files are read as Quarto documents themselves, hence the presence of the --- fences.

However, only the acronyms’ definitions are used in fromfile external documents. No other option is taken into account. The eventual document body is ignored as well.

Loading order for acronyms

The acronyms are read in the following order:

  1. Acronyms in the acronyms.key field of the source qmd document, in sequential order.
  2. Acronyms in each of the acronyms.fromfile files.
    1. Files are read in sequential order.
    2. Acronyms inside each file are also read in sequential order.

This order is meaningful in 2 cases:

  • When a duplicate key is found, the behaviour (keep or replace) depends on the order in which acronyms are read.
  • When the initial sorting is used, the List Of Acronyms displays acronyms in the same order as they were defined.