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 theMarkdown
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
Built Distribution
Hashes for mkdocs_glossary-0.1.5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 45e749470ae00134741e2c3efed6dc0cc7c791660558c3b55438cdcac45a023c |
|
MD5 | 163e273512059ece853f82f260c6e57e |
|
BLAKE2b-256 | 741f3d600240969f9c545ce8bb6fba386b8f952b374817390c9fe72db8d77d4a |