Welcome to pandoc-latex-admonition’s documentation!

Installation

pandoc-latex-admonition is a pandoc filter for adding admonition to divs or codeblocks elements.

It uses the tcolorbox LaTeX package to generate admonitions and the footnote LaTeX package to handle correctly footnotes in admonition.

Instructions

pandoc-latex-admonition requires python, a programming language that comes pre-installed on linux and Mac OS X, and which is easily installed on Windows.

Install pandoc-latex-admonition using the bash command

$ pipx install pandoc-latex-admonition

To upgrade to the most recent release, use

$ pipx upgrade pandoc-latex-admonition

pipx is a script to install and run python applications in isolated environments from the Python Package Index, PyPI. It can be installed using instructions given here.

Make sure you have the

• tcolorbox

• footnote

• xcolor

• ifthen

LaTeX packages. On linux you have to install some extra libraries before pandoc-latex-admonition. On a Debian-based system (including Ubuntu), you can install it as root using

$ sudo apt-get install texlive-latex-extra

Getting Help

If you have any difficulties with pandoc-latex-admonition, please feel welcome to file an issue on github so that we can help.

Notes

• format icon by Picol

• license icon by Icooon Mono

• download icon by zest

• status icon by Just Icon

• code style icon by Google Material Design icons

• size icon by Iconscout

Usage

To apply the filter, use the following option with pandoc:

$ pandoc --filter pandoc-latex-admonition

Explanation

In the metadata block, specific set of classes can be defined to decorate div or codeblock elements by admonition generated from the tcolorbox LaTeX package

The metadata block add information using the pandoc-latex-admonition entry by a list of definitions:

pandoc-latex-admonition:
# order is important
  - color: firebrick
    classes: [admonition, danger]
  - color: gray
    classes: [admonition]

The metadata block above is used to add a red admonition to divs or codeblocks which have admonition and danger classes and a gray admonition to divs or codeblocks that have only a admonition class.

Each entry of pandoc-latex-admonition is a YAML dictionary containing:

• classes: the set of classes of the divs to which the transformation will be applied. This parameter is mandatory.

• color: the color name taken from the X11 color collection.

• position: the position of the admonition (left by default or right, inner, outer)

• liwewidth the line width (2 by default)

• margin the margin from the text (-4 by default)

• innermargin the innermargin from the text (5 by default)

• localfootnotes use local footnotes inside the admonition (false by default)

• nobreak force no break at end of pages

It’s also possible to set an admonition on a specific div or codeblock element using these attributes:

• latex-admonition-color: the color name taken from the X11 color collection. This attribute is mandatory.

• latex-admonition-position: the position of the admonition (left by default or right, inner, outer)

• latex-admonition-liwewidth the line width (2 by default)

• latex-admonition-margin the margin from the text (-4 by default)

• latex-admonition-innermargin the innermargin from the text (5 by default.)

• latex-admonition-localfootnotes use local footnotes inside the admonition (false by default)

• latex-admonition-nobreak force no break at end of pages

For correct LaTeX output, figures (an image with nonempty alt text, occurring by itself in a paragraph) must be shifted after the div.

The following LaTeX packages are required:

• tcolorbox

• xcolor

• footnote

• ifthen

Example

Demonstration: Using pandoc-latex-admonition-sample.txt as input gives output file in pdf. You must have the Markdown-mark.svg.png image for correct testing.