Metadata-Version: 2.1
Name: foliantcontrib.admonitions
Version: 1.0.1
Summary: Preprocessor for admonitions
Home-page: https://github.com/foliant-docs/foliantcontrib.admonitions
Author: Daniil Minukhin
Author-email: ddddsa@gmail.com
License: MIT
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Documentation
Classifier: Topic :: Utilities
Description-Content-Type: text/markdown
Requires-Dist: foliant (>=1.0.8)
Requires-Dist: foliantcontrib.utils (>=1.0.2)

[![](https://img.shields.io/pypi/v/foliantcontrib.admonitions.svg)](https://pypi.org/project/foliantcontrib.admonitions/)  [![](https://img.shields.io/github/v/tag/foliant-docs/foliantcontrib.admonitions.svg?label=GitHub)](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



