📚 Add directive to show list of abbreviations across pages

[haroldcampbell]

The PR add an {abbreviations} block-directive that renders a list of known abbreviations. Abbreviations will be collected from the project.abbreviations in the myst.yml and from the frontmatter of all the pages in the site.

The abbreviations as sorted alphabetically. As implemented, page-level abbreviations override project abbreviations when duplicated duplicate keys. The implementation adds the directive without replacing the existing inline abbreviation mechanism.

Usage

```{abbreviations} Optional title

```

Support was also added for common directive options :label: and :class:. Which allows you to write:

:label: abbreviations-list
:class: compact

Tests

I've included a test case in mystmd/packages/mystmd/tests/abbreviations-directive with a README.md

Implementation

Given a myst.yml with the following (see mystmd/packages/mystmd/tests/abbreviations-directive):

project:
  title: Abbreviations Directive Sample
  abbreviations:
    API: Application Programming Interface

...and a page with the following frontmatter (e.g. page-3.md):

---
abbreviations:
  Algo: Algorithm
---

You'd get the following mdast

{
  "type": "definitionList",
  "children": [
    {
      "type": "definitionTerm",
      "children": [{ "type": "text", "value": "Algo" }]
    },
    {
      "type": "definitionDescription",
      "children": [
        {
          "type": "paragraph",
          "children": [{ "type": "text", "value": "Algorithm" }]
        }
      ]
    },
    {
      "type": "definitionTerm",
      "children": [{ "type": "text", "value": "API" }]
    },
    {
      "type": "definitionDescription",
      "children": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "value": "Application Programming Interface"
            }
          ]
        }
      ]
    }
  ]
}

Closes #1098

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6b3ee26

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[haroldcampbell]

Disclosure: OpenAI's CodexCLI was used to help with the development of this directive. I'm happy to share the prompts/specs if folks are interested.

[stefanv]

Also see #2979 which should make it easier to gather frontmatter in these types of plugins.

[choldgraf]

@stefanv do you think I makes sense to get that multi doc metadata PR in before finishing this one?

[choldgraf]

In the meantime - @haroldcampbell can you add user facing docs for this so that it's easier to understand the UX and so that users can discover this?

[stefanv]

This getmdast magic is new to me, but yes: I think if we can get all front matter included in what we provide plugins (which that PR does), it would avoid some shenanigans in this one.

[haroldcampbell]

@stefanv is the call to the cache.$getMdast(...) function an internal API that we shouldn't be using?

If it is I can explore a different way to get the abbreviations in the collectAbbreviations(...) in mystmd/packages/myst-cli/src/process/mdast.ts:102

[agoose77]

We should check this — I think there's a race condition here implying that we need another sync point.

This is also true for the ToC transform I think.

Actually.... it might be fine — we read mdast only to get the custom placeholder node, which is not modified after referencing.

[haroldcampbell]

@choldgraf, I've added user facing docs for the directive. Specifically, to the following files:

• docs/directives.md
• docs/glossaries-and-terms.md

Can you have a look and let me know if this works?