# 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`:
``` yaml
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`.
``` yaml
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.
``` markdown
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.
``` markdown
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
``` markdown
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
- [GitLab Repo](http://www.gitlab.org/thiti-mkdocs-plugins/mkdocs-glossary/)
- [MkDocs Website](http://www.mkdocs.org/)
- [MkDocs-Material Documentation](https://squidfunk.github.io/mkdocs-material/)
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/thiti-mkdocs-plugins/mkdocs-glossary",
"name": "mkdocs-glossary",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mkdocs",
"author": "Thibaud Briard",
"author_email": "thiti517@outlook.com",
"download_url": "https://files.pythonhosted.org/packages/92/58/22a0be9c727a73a50fe051de0a85d4cda039bdb0105da4d3bd247f1fbd21/mkdocs-glossary-0.1.5.tar.gz",
"platform": null,
"description": "# mkdocs-glossary\n\nA MkDocs plugin that automatically creates references to glossary terms within italicized text from a specified glossary list file.\n\n## Setup\n\n### Installing using pip:\n\n`pip install mkdocs-glossary`\n\n## Config\n\nYou need to activate the plugin in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - glossary:\n file: \"file_name\" # Optional --> Default : glossary.md\n exclude: # Optional --> Default : None\n - 'excluded term A'\n - 'excluded term B'\n - '...'\n unknown_warning: true # Optional --> Default : false\n hide_variants: true # Optional --> Default : false\n```\n\n- `file` - The filename, from docs root folder, of the `Markdown` file containing the glossary list.\n- `exclude` - This is a list of all the terms, case insensitive, that you want the plugin to ignore.\n- `unknown_warning` - This option allow the plugin to create warning on founded term that are not in glossary list or exclude list.\n- `hide_variants` - This option allow the plugin to delete term variantes in the glossary when generating the site.\n\n## Usage\n\n### How it work\n\nThe 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.\n\nTo 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`.\n\nYou can set the `pymdownx.caret` markdown extension like this in your `mkdocs.yml`.\n\n``` yaml\nmarkdown_extensions:\n - pymdownx.caret\n```\n\nUsing the command `mkdocs build` or `mkdocs serve` will trigger the plugin.\n\n### Glossary list\n\nFor the glossary list inside the glossary file you have to respect this format\n\nFirst, create a `Markdown` ordered list like in the usual way.\n\n``` markdown\n1. Something\n2. Something else\n```\n\nSecondly 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.\n\n``` markdown\n1. **Term A**\n2. **Term B, Variant B1**\n```\n\nFinnaly you can add your description the same way you would write any text just after a space, a colon and another space\n\n``` markdown\n1. **Term A** : Term A Description\n2. **Term B, Variant B1** : *Term B* **Important Descripiton** See : [link](.)\n```\n\n### About `Extended Markdown Definition List`\n\nI'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.\n\n### Notes\n\nNote 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.\n\nBe 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.\n\nBy the way any italic words contained in the glossary file will be ignored by the plugin.\n\n## License\n\nThis project is under MIT license. See the `license` file for more details.\n\n## See Also\n\n- [GitLab Repo](http://www.gitlab.org/thiti-mkdocs-plugins/mkdocs-glossary/)\n- [MkDocs Website](http://www.mkdocs.org/)\n- [MkDocs-Material Documentation](https://squidfunk.github.io/mkdocs-material/)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A MkDocs plugin that automatically creates references to glossary terms within italicized text from a specified glossary list file.",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://gitlab.com/thiti-mkdocs-plugins/mkdocs-glossary"
},
"split_keywords": [
"mkdocs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "741f3d600240969f9c545ce8bb6fba386b8f952b374817390c9fe72db8d77d4a",
"md5": "163e273512059ece853f82f260c6e57e",
"sha256": "45e749470ae00134741e2c3efed6dc0cc7c791660558c3b55438cdcac45a023c"
},
"downloads": -1,
"filename": "mkdocs_glossary-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "163e273512059ece853f82f260c6e57e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5995,
"upload_time": "2024-10-17T10:03:26",
"upload_time_iso_8601": "2024-10-17T10:03:26.804489Z",
"url": "https://files.pythonhosted.org/packages/74/1f/3d600240969f9c545ce8bb6fba386b8f952b374817390c9fe72db8d77d4a/mkdocs_glossary-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "925822a0be9c727a73a50fe051de0a85d4cda039bdb0105da4d3bd247f1fbd21",
"md5": "ea103a594347c807f4fcf05cf480f12f",
"sha256": "b76adeca8c458bdb7e7c7b9987cf6034001bd5364876c3dab34a7126a7c6f401"
},
"downloads": -1,
"filename": "mkdocs-glossary-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "ea103a594347c807f4fcf05cf480f12f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6873,
"upload_time": "2024-10-17T10:03:28",
"upload_time_iso_8601": "2024-10-17T10:03:28.654839Z",
"url": "https://files.pythonhosted.org/packages/92/58/22a0be9c727a73a50fe051de0a85d4cda039bdb0105da4d3bd247f1fbd21/mkdocs-glossary-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-17 10:03:28",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "thiti-mkdocs-plugins",
"gitlab_project": "mkdocs-glossary",
"lcname": "mkdocs-glossary"
}
JSON