https://github.com/foliant-docs/foliantcontrib.admonitions
https://github.com/foliant-docs/foliantcontrib.admonitions
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/foliant-docs/foliantcontrib.admonitions
- Owner: foliant-docs
- License: mit
- Created: 2019-06-10T09:27:59.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2023-02-02T07:32:58.000Z (over 3 years ago)
- Last Synced: 2025-09-28T00:22:51.661Z (9 months ago)
- Language: Python
- Size: 5.86 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://pypi.org/project/foliantcontrib.admonitions/) [](https://github.com/foliant-docs/foliantcontrib.admonitions)
# Admonitions preprocessor for Foliant
Preprocessor which tries to make admonitions syntax available for most backends.
Admonitions are decorated fragments of text which indicate a warning, notice, tip, etc.
We use [rST-style syntax for admonitions](https://python-markdown.github.io/extensions/admonition/) which is already supported by mkdocs backend with `admonition` extension turned on. This preprocessor makes this syntax work for pandoc and slate backends.
## Installation
```bash
$ pip install foliantcontrib.admonitions
```
## Config
Just add `admonitions` into your preprocessors list. Right now the preprocessor doesn't have any options:
```yaml
preprocessors:
- admonitions
```
## Usage
Add an admonition to your Markdown file:
```
!!! warning "optional admonition title"
Admonition text.
May be several paragraphs.
```
Currently supported backends:
- `pandoc`
- `mkdocs`*
- `slate`
\* for admonitions to work in mkdocs, add `admonition` to the `markdown_extensions` section of your mkdocs.yml config:
```yaml
backend_config:
mkdocs:
mkdocs.yml:
markdown_extensions:
- admonition
```
### Notes for slate
Slate has its own admonitions syntax of three types: `notice` (blue notes), `warning` (red warnings) and `success` (green notes). If another type is supplied, slate draws a blue note but without the "i" icon.
Admonitions preprocessor transforms some of the general admonition types into slate's for convenience (so you could use `error` type to display same kind of note in both slate and mkdocs). These translations are indicated in the table below:
original type | translates to
------------- | -------------
error | warning
danger | warning
caution | warning
info | notice
note | notice
tip | notice
hint | notice