Skip to main content

A MkDocs plugin that automatically creates references to glossary terms within italicized text from a specified glossary list file.

Project description

mkdocs-glossary

A MkDocs plugin that automatically creates references to glossary terms within italicized text from a specified glossary list file.

Setup

Installing using pip:

pip install mkdocs-glossary

Config

You need to activate the plugin in mkdocs.yml:

plugins:
  - glossary:
      file: "file_name" # Optional --> Default : glossary.md
      exclude: # Optional --> Default : None
        - 'excluded term A'
        - 'excluded term B'
        - '...'
      unknown_warning: true # Optional --> Default : false
      hide_variants: true # Optional --> Default : false
  • file - The filename, from docs root folder, of the Markdown file containing the glossary list.
  • exclude - This is a list of all the terms, case insensitive, that you want the plugin to ignore.
  • unknown_warning - This option allow the plugin to create warning on founded term that are not in glossary list or exclude list.
  • hide_variants - This option allow the plugin to delete term variantes in the glossary when generating the site.

Usage

How it work

The plugin will look for Markdown italic text. It will ignore italic placed in headers, links text, images alt text, code and code blocks. It will then check if the text is part of the glossary list from the glossary file and create a reference next to the text.

To create that reference to the definition it will use a superscript number inside a Markdown link element. To correctly render superscript this plugin require a way to render them. I recommend using pymdownx.caret markdown extension via mkdocs-material.

You can set the pymdownx.caret markdown extension like this in your mkdocs.yml.

markdown_extensions:
  - pymdownx.caret

Using the command mkdocs build or mkdocs serve will trigger the plugin.

Glossary list

For the glossary list inside the glossary file you have to respect this format

First, create a Markdown ordered list like in the usual way.

1. Something
2. Something else

Secondly place each terms between Markdown bold characters. you can separate variantes that have the same description by using comma. The hide_variants option allow you to hide them on the generated site so that only the first term appear.

1. **Term A**
2. **Term B, Variant B1**

Finnaly you can add your description the same way you would write any text just after a space, a colon and another space

1. **Term A** : Term A Description
2. **Term B, Variant B1** : *Term B* **Important Descripiton** See : [link](.)

About Extended Markdown Definition List

I'm aware of the Extended Markdown Definition List element but it's supposed to generate a definition at the end of a page/document and since i don't want to interfere with any plugins that would use it the proper way i had to come up with another way to write and read the glossary list.

Notes

Note that most Markdown interpreter will automaticaly manage numbers or ordered list so it have no importance if you use accurate number on the glossary list. The plugin just do a simple increment at each new entry.

Be aware that multiple ordered list that follow the glossary list rules would work but would create confusion with user since the numbers shown on the glossary lists would not correspond to the ones used by the plugin to reference terms in the documentation.

By the way any italic words contained in the glossary file will be ignored by the plugin.

License

This project is under MIT license. See the license file for more details.

See Also

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs-glossary-0.1.5.tar.gz (6.9 kB view details)

Uploaded Source

Built Distribution

mkdocs_glossary-0.1.5-py3-none-any.whl (6.0 kB view details)

Uploaded Python 3

File details

Details for the file mkdocs-glossary-0.1.5.tar.gz.

File metadata

  • Download URL: mkdocs-glossary-0.1.5.tar.gz
  • Upload date:
  • Size: 6.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.10.12

File hashes

Hashes for mkdocs-glossary-0.1.5.tar.gz
Algorithm Hash digest
SHA256 b76adeca8c458bdb7e7c7b9987cf6034001bd5364876c3dab34a7126a7c6f401
MD5 ea103a594347c807f4fcf05cf480f12f
BLAKE2b-256 925822a0be9c727a73a50fe051de0a85d4cda039bdb0105da4d3bd247f1fbd21

See more details on using hashes here.

File details

Details for the file mkdocs_glossary-0.1.5-py3-none-any.whl.

File metadata

File hashes

Hashes for mkdocs_glossary-0.1.5-py3-none-any.whl
Algorithm Hash digest
SHA256 45e749470ae00134741e2c3efed6dc0cc7c791660558c3b55438cdcac45a023c
MD5 163e273512059ece853f82f260c6e57e
BLAKE2b-256 741f3d600240969f9c545ce8bb6fba386b8f952b374817390c9fe72db8d77d4a

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page