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...

• 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

• node.js with npm

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 

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:

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

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 

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.

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 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.

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.

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.

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:

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)

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

• 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.

MIT © Andreas Martin