7.1.0 • Public • Published


Tests (Functional) Nightly Tests (Latest Dependencies)

glossarify-md is a command line tool to help Markdown writers with

  • Cross-Linking (prime use case): auto-link terms to some definition in a glossary
  • Indexes: generate indexes from glossary terms and navigate to where they were mentioned
  • Lists: generate arbitrary lists such as List of Tables, List of Figures, List of Listings, List of Definitions, List of Formulas, and so forth...

Table of Contents



Option 1: Install locally, init, configure, run (recommended):

cd ./your-project
npm install glossarify-md

npx glossarify-md --init --new --local
npx glossarify-md --config ./glossarify-md.conf.json

ⓘ Since 6.3.0 glossarify-md supports a --watch mode.

When installing locally you might want to set up a shortcut by adding a run script to your package.json:

  "scripts": {
    "glossarify": "glossarify-md --config ./glossarify-md.conf.json"

Next time you're able to use:

npm run glossarify

Option 2: Install globally, init, configure, run:

npm install -g glossarify-md

glossarify-md --init --new
glossarify-md --config ./glossarify-md.conf.json


By following the installation instructions you should be set up with a minimal configuration:

Minimal Configuration

  "$schema": "./node_modules/glossarify-md/conf/v5/schema.json",
  "baseDir": "./docs",
  "outDir": "../docs-glossarified"

More configuration options here.


We assume a sample project with the following structure:

   +- docs/
   |    +- pages/
   |    |    |-
   |    |    `-
   |    |
   |    |-
   |    |-
   |    `-
   +- docs-glossarified/  (Generated output directory)
   `- glossarify-md.conf.json


A term Term then may occur anywhere in your file set:


# Document

This is a text mentioning a glossary Term to describe something.

Your glossary is a file with terms being section headings and definitions being section content:


# Glossary

## Term

A glossary term has a short description. The full description contains both sentences.

Then run glossarify-md with a glossarify-md.conf.json:

npx glossarify-md --config ./glossarify-md.conf.json


Augmented versions of your input files have been written to the output directory:

Source: ./docs-glossarified/pages/

# [Document](#document)

This is text mentioning a glossary [Term][1] to describe something.

[1]: ../ "A glossary term has a short description."

Source: ./docs-glossarified/

# [Glossary](#glossary)

## [Term](#term)

A glossary term has a short description. The full description contains both sentences.

When rendered by some Markdown to HTML converter (not part of glossarify-md) the result may look like this:




A glossary term has a short description. The full description contains both sentences.



This is text mentioning a glossary Term to describe something.

To navigate the opposite direction from a term to sections where a glossary term got mentioned you might want to generate a Book Index.

What's not being linkified

Some syntactic positions of a term occurrence are excluded from being linked to the glossary, for example when the term occurs in:

  • HTML <a>text</a>
  • Headlines #
  • (Markdown) links []()
  • Preformatted blocks ```, ~~~
  • Blockquotes >
    • Blockquotes are excluded based on the premise that a quoted entity may not share the same definition of a term like the entity who quotes it.

ⓘ Tip: Wrap a word into some pseudo HTML tag like e.g. <x>word</x> to mark it for exclusion from term-based auto-linking.

Aliases and Synonyms

Aliases can be added by what we call term attributes. Term attributes are provided in a YAML formatted comment following a term's heading. For aliases there's the term attribute aliases whose attribute value is a string of comma-separated synonyms: with a term attribute aliases:

# Glossary

## Cat
<!-- aliases: Cats, Wildcat, House Cat, PET-2 -->
Cats are cute, ...dogs are loyal.

In the output files aliases will be linked to their related term:


# About Cats

[Cats](./ and kitten almost hidden spotting mouses in their houses. [Andreas Martin]

ⓘ Note: YAML syntax is case-sensitive as well as sensitive to tabs and whitespaces. In general term attributes will be lowercase.

Term Hints


"glossaries": [
    { "file": "./", "termHint": ""},

Glossaries can be associated with term hints. Term hints may be used to indicate that a link refers to a glossary term and in case of multiple glossaries to which one. Use "${term}" to control placement of a termHint. For example, "☛ ${term}" puts the symbol in front of a linkified term occurrence.

Multiple Glossaries

Sometimes you might whish to have multiple glossaries:


"glossaries": [
    { "file": "./",   "termHint": "" },
    { "file": "./", "termHint": "⚕${term}" }

## NC32
Fracture of forearm

## NC90
Superficial injury of knee or lower leg

With adding to the list of glossaries every mention of ⚕NC32 or ⚕NC90 in documents will have a tooltip and link to the glossary definition, too. Since v5.0.0 file can also be used with a glob file pattern:

"glossaries": [
    { "file": "./**/*.md" },

This way each markdown file matching the pattern will be processed like a glossary. More see Cross-Linking and Multiple Glossaries and Ambiguity.

ⓘ Note: termHint only works for file pointing at a particular file name.

Sorting Glossaries

Add sort with "asc" (ascending) or "desc" (descending) to glossaries you want glossarify-md sort for you:


"glossaries": [
    { "file":"./", "sort": "asc" }

Internally, glossarify-md uses Intl.Collator and falls back to String.localeCompare if the Intl API is missing. You can tweak collation by adding i18n options:


"i18n": {
   "locale": "de",
   "ignorePunctuation": true

The i18n object is passed as is to the collator function. Thus you can use additional options documented on Mozilla Developer Portal:

Advanced Topics

See here, for advanced topics:

  • Importing and exporting terms
  • Generating files, such as a book index, lists of figures, etc.
  • Cross-Linking more than just terms
  • Using glossarify-md with other tools, like vuepress, pandoc or Hugo
  • Dealing with non-standard Markdown Syntax via Plug-ins (e.g Frontmatter)

Node Support Matrix

The term support refers to runs on the given platform and is subject to the terms and conditions in LICENSE.

NodeJS glossarify-md Current Test Matrix
Current v7 Tested. Should node.js introduce breaking changes which affect glossarify-md, then we may choose to step back from supporting Current until it becomes the next LTS.
18 LTS v6, v7 Tested + Supported
16 LTS v5, v6, v7 Tested + Supported
14 LTS v4, v5, v6
12 LTS v3, v4, v5
10 LTS v2, v3, v4

Special Thanks go to


MIT © Andreas Martin

Package Sidebar


npm i glossarify-md

Weekly Downloads






Unpacked Size

597 kB

Total Files


Last publish


  • about-code-js