mkdocs-glossary-plugin

This plugin provides a simple glossary feature for mkdocs.

What's useful?

When you are writing documents for your project, you maybe use some project-specific words.
Of course, reader cannot understand these words without any explanation, but we want to avoid linking to all the places where these words are used.

In these cases, this plugin can ...

• replace these words with a link to a specified page automatically
• control the details, such as not converting words contained in h1 or emph, but converting words contained in plain text.
• alias support. you can set alias for each word.

Requirements

• python >= 3.7
• pandoc >= 2.11
• python pandoc(https://pypi.org/project/pandoc/)

How to install

python3 setup.py install

Getting started

Plugin configuration

Edit your mkdocs.yml file as follows.

plugins:
  - mkdocs-glossary-plugin:
      glossary_dirs: ["foo", "bar"] # This plugin considers the md files in "docs/foo" and "docs/bar" as glossary files.

You can set some options, see Options section.

Register glossary

For example, let's say you want to create a glossary of the word x_word .
At first, You have to create x_word.md file like below as a glossary page for x_word .

~/mkdocs_project/docs$ tree
.
├── foo
│   └── x_word.md
└── index.md

All that remains is for you to write freely in x_word.md!
If you want to add an alias to x_word, set the glossary metadata at the beginning of the x_word.md file as follows.

---
glossary: alias_word_a
glossary: alias_word_b
---

This is the glossary page for x_word!

That's all! Now, all the x_word, alias_word_a and alias_word_b in your project will be replaced with a link to x_word.md when building.

Options