glossarify-md

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

• Prerequisites
• Install
• Configuration
• Sample
  • Input
  • Output
• What's not being linkified
• Aliases and Synonyms
• Term Hints
• Multiple Glossaries
• Sorting Glossaries
• Advanced Topics
• Node Support Matrix
• Special Thanks go to
• License

Prerequisites

• node.js with npm

Install

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

Configuration

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.

Sample

We assume a sample project with the following structure:

${root}
   +- docs/
   |    +- pages/
   |    |    |- page1.md
   |    |    `- page2.md
   |    |
   |    |- README.md
   |    |- who-icd-codes.md
   |    `- glossary.md
   |
   +- docs-glossarified/  (Generated output directory)
   `- glossarify-md.conf.json

Input

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

./docs/pages/page1.md...

# 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:

docs/glossary.md

# 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

Output

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

Source: ./docs-glossarified/pages/page1.md

# [Document](#document)

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

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

Source: ./docs-glossarified/glossary.md:

# [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:

./docs-glossarified/glossary.html:

Glossary

Term

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

./docs-glossarified/pages/page1.html

Demo

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:

glossary.md 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:

./docs-glossarified/pages/page2.md

# About Cats

[Cats](./glossary.md#cat) and kitten almost hidden spotting mice of any size. [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

glossarify-md.conf.json

"glossaries": [
    { "file": "./glossary.md", "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:

glossarify-md.conf.json

"glossaries": [
    { "file": "./glossary.md",   "termHint": "↴" },
    { "file": "./who-icd-codes.md", "termHint": "⚕${term}" }
]

who-icd-codes.md

## NC32
Fracture of forearm

## NC90
Superficial injury of knee or lower leg

With adding who-icd-codes.md 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:

glossarify-md.conf.json

"glossaries": [
    { "file":"./glossary.md", "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:

glossarify-md.conf.json

"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	v8	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.
24 LTS	v7, v8	Tested + Supported
22 LTS	v7, v8	Tested + Supported
20 LTS	v6, v7
18 LTS	v6, v7
16 LTS	v5, v6, v7
14 LTS	v4, v5, v6
12 LTS	v3, v4, v5
10 LTS	v2, v3, v4

Special Thanks go to

• John Gruber, author of the Markdown syntax
• John MacFarlane et al., initiators and authors of the CommonMark specification
• Titus Wormer, author of unifiedjs, remarkjs and so much more
• All the other great people publishing modules of value for the tool, be it directly or transitively.

License

MIT © Andreas Martin