markdown-it-variables

When writing documentation or any markdown-based content, you might find yourself repeating a lot of text. Among these repetitive chunks of text, there might be some important units (e.g. product name, acronyms, etc.) that you would want to keep consistent and easy to write and replace. This markdown-it plugin is a straightforward way of achieving this.

• ✅ Simple variables #{productName} -> My product
• ✅ Acronyms: #{who|-} to <abbr title="World Health Organization">WHO</abbr>
• ✅ Links: #{who|#} to <a href="https://www.who.int">World Health Organization</a>

Install

# Using npm
npm i markdown-it-variables
# Using Yarn
yarn add markdown-it-variables
# Using pnpm
pnpm add markdown-it-variables

Usage

import mardownIt from 'markdown-it';
import { variablesPlugin } from 'markdown-it-variables';

const md = mardownIt().use(variablesPlugin, {
  since: '1948',
  who: {
    url: 'https://www.who.int',
    abbr: 'WHO',
    label: 'World Health Organization',
  },
});

You can then reference your variables from a markdown file: #{since} and #{who}. You can also apply a list of pipe-separated modifiers: #{who|abbr|link}, and use modifier aliases to get even more concise: #{who|-|#}.

Modifiers

Options

data: Record<string, SimpleVariable | ExpandedVariable>

List of variables you want to use.

There are two kinds of variables :

1. Simple ones, whose values can be any string.
2. Rich ones, which can define further piece of information that can later be used through modifiers.

The value of rich variables are objects with the following structure:

severity?: 'error' | 'warn' | 'silent' (optional, defaults to 'warn')

Determines the severity of the plugin.

Here is an overview of how different severities change the behaviour of the plugin:

❌ Throws │ ⏭️ Skips (does not transform) │ ✅ Transforms to fallback │ ❕ Prints a warning message

ignoreMissingVariables?: boolean (optional, defaults to false)

When set to true, prevents the plugin from throwing when encountering references to missing variables.

This basically overwrites the above behaviours with the following:

• It does not throw even if severity is set to 'error'.
• It does not print any warning even if severity is set to 'warn'.

className?: string (defaults to undefined)

When defined, the outter tags of any variable will have the specified class name. When specified and encountering variables without modifiers, the variable output will be wrapped in a span with the specified class name.

Example

Based on the options illustrated in the Usage section.

Input:

Founded in #{since}, #{who|#} is the United Nations agency that connects nations, partners and
people to promote health, keep the world safe and serve the vulnerable - so everyone, everywhere can
attain the highest level of health.

#{who|-} leads global efforts to expand universal health coverage. We direct and coordinate the
world's response to health emergencies.

Output:

Founded in 1948, <a href="https://www.who.int">World Health Organization</a> is the United Nations
agency that connects nations, partners and people to promote health, keep the world safe and serve
the vulnerable - so everyone, everywhere can attain the highest level of health.

<abbr title="World Health Organization">WHO</abbr> leads global efforts to expand universal health
coverage. We direct and coordinate the world's response to health emergencies.