Welcome to pandoc-latex-tip’s documentation!

pandoc-latex-tip

license icon by Daniel Bruce, format icon by Picol, status icon by Just Icon, code style icon by Google Material Design icons

pandoc-latex-tip is a pandoc filter for adding icon tooltips in the margin using popular icon collections. It uses the icon_font_to_png package to generate on-fly images.

Instructions

pandoc-latex-tip 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-tip using the bash command

$ pip install pandoc-latex-tip

To upgrade to the most recent release, use

$ pip install --upgrade pandoc-latex-tip

To upgrade the icon collections add the --force and --no-cache flags

$ pip install --upgrade --force --no-cache pandoc-latex-tip

pip is a script that downloads and installs modules from the Python Package Index, PyPI. It should come installed with your python distribution. If you are running linux, pip may be bundled separately. On a Debian-based system (including Ubuntu), you can install it as root using

$ sudo apt-get install python3-pip

Make sure you have required packages for Pillow installation. On linux you have to install some extra libraries before pandoc-latex-tip. On a Debian-based system (including Ubuntu), you can install it as root using

$ sudo apt-get build-dep python-imaging
$ sudo apt-get install libjpeg8 libjpeg62-dev libfreetype6 libfreetype6-dev

Getting Help

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

Usage

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

$ pandoc --filter pandoc-latex-tip

Explanation

In the metadata block, specific set of classes can be defined to decorate HTML span, div, code or codeblock elements by icons generated from popular icon collections:

• Font-Awesome (4.7, 5.x) Dave Gandy (SIL OFL 1.1)

• Glyphicons (3.3 Jan Kovarik (MIT)

• Material Design (2.x) Austin Andrews & Google (SIL OFL 1.1)

It’s also possible to specify a tip on such an element using description by attribute.

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

pandoc-latex-tip:
  - classes: [tip, error]
    icons: [bug]
  - classes: [tip]

The metadata block above is used to add a bug icon to span, div, code or codeblock elements which have tip and error classes and a generic icon to span, div, code or codeblock elements that have only a tip class.

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

• classes: the set of classes of the span, div, code or codeblock elements to which the transformation will be applied. This parameter is mandatory.

• icons: the list of icons that will decorate the span, div, code or codeblock elements ([exclamation-circle] by default)

• size: the size of the rendered icons (18 by default)

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

• color: the default color for icons which do not have a color description by themselves

Each icon is either:

• an icon name taken from the Font-Awesome icons collection 4.7.0

• a YAML object containing

  • a name property (for the icon)

  • a color property taken from the X11 color collection

  • an icon collection property (either fontawesome, glyphicons or materialdesign)

  • an icon collection version property (4.7 or 5.x for fontawesome, 3.3 for glyphicons and 2.x for materialdesign)

  • an icon collection variant property (Font-Awesome 5.x version define 3 variants brands, regular, solid)

  • a link property to make the icon clickable

If only an icon name is specified (in this case, you can simply put its name instead of inserting it in a list), the color is assumed to be Black, the version is assumed to be 4.7 and the variant is assumed to be regular.

It’s also possible to specify a tip for individual elements using attribute description:

• latex-tip-icon: the name of the icon

• latex-tip-size: the size of the rendered icon (18 by default)

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

• latex-tip-color: the color for the icon (black by default)

• latex-tip-name: the collection name property (fontawesome by default)

• latex-tip-version: the collection version property (4.7 by default)

• latex-tip-variant: the collection variant property (regular by default)

• latex-tip-link: a link for the clickable icon

The following LaTeX packages are required:

• marginnote

• etoolbox

• changepage

• needspace

Example

Demonstration: Using pandoc-latex-tip-sample.txt as input gives output file in pdf.