Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/angrymane/mkdocs-glossary-plugin
https://github.com/angrymane/mkdocs-glossary-plugin
documentation markdown mkdocs plugin
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/angrymane/mkdocs-glossary-plugin
- Owner: AngryMane
- License: bsd-2-clause
- Created: 2022-04-07T13:59:47.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2023-08-04T05:54:37.000Z (over 1 year ago)
- Last Synced: 2024-10-10T21:41:34.677Z (about 1 month ago)
- Topics: documentation, markdown, mkdocs, plugin
- Language: Python
- Homepage:
- Size: 961 KB
- Stars: 4
- Watchers: 4
- Forks: 1
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
| Name | Necessary | Type | Default | Detail |
|-------------------------|-----------| ----------|---------------------|-----------------------------------|
| glossary_dirs | required | List[str] | None | Specify the dirs containing the glossary md files. This plugin will only search for glossaries here. **Please fill out with relative path from docs dir.**|
| input_format | optional | str | `markdown_phpextra` | The input format of the markdown file. See [pandoc](https://pandoc.org/MANUAL.html#general-options) |
| output_format | optional | str | `markdown_phpextra` | The output format of the markdown file. See [pandoc](https://pandoc.org/MANUAL.html#general-options) |
| is_case_sensitive | optional | bool | True | If True, this plugin is case-sensitive. |
| enable_toc | optional | bool | True | If True, you can use table of contents(\[TOC\]) feature. |
| replace_emphasized_text | optional | bool | True | If True, emphaseized text includes specified word. |
| replace_header | optional | bool | False | If True, h1,h2,.. includes specified word. |
| replace_table_header | optional | bool | True | If True, table header includes specified word. |
| replace_table_body | optional | bool | True | If True, table body includes specified word. |