Using jargon

Jargon are terms that could throw off new users. Rather than create a glossary on every page, we use MDX to manage jargon terms for us. This page shows you how to use it.

Adding jargon terms

To add a new jargon term, you first need to document it, then you can add it to the jargon component for the website you’d like to add it to:

The file holds a jargon object that consists of key/value pairs per language.

The key is the jargon term. It should always be lowercase because we lowercase the term before matching it. So in your text, you can use ESM, esm, or even eSm, but the key in the jargon file should be esm.

The value is the URL path to the documentation page for the term. You do not need to include the language prefix in the doc path. Note that this should point to a page that holds MDX content.

An example will make this more clear:

const jargon = {
  en: {
    basting: 'docs/sewing/basting',
  },
  nl: {
    driegen: 'docs/sewing/basting',
  },
}

Using jargon terms in MDX content

To use jargon inside MDX content (like the markdown of our documentation, blog posts, and so on), it’s sufficient to emphasize the term:

We are migrating from _cjs_ to _esm_ modules

Which renders as:

We are migrating from cjs to esm modules

Using jargon terms outside MDX content

Outside MDX content — more precisely, in React components — you can achieve the same effect with the Term component:

import { Term } from 'site/components/jargon.mjs'

export const MyComponent = () => (
  <p>Look, it works here too: <Term>esm</Term></p>
)