Welcome to pandoc-latex-tip’s documentation!

Installation

Python package pre-commit Coveralls Scrutinizer Code Climate CodeFactor Codacy PyPI version Latest release Last commit PyPI format License Python version Poetry version Pandoc version Downloads Development Status Docs Code style: black Repo Size Code Size Source Rank

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

$ pipx install pandoc-latex-tip

To upgrade to the most recent release, use

$ pipx install --upgrade pandoc-latex-tip

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 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.

Contribute

Instructions

Install poetry, then run

$ poetry self add poeblix
$ poetry install
$ poetry run python download.py
$ poetry blixbuild
$ poetry run pip install dist/pandoc_latex_tip-`poetry version -s`-py3-none-any.whl
$ poetry shell

And submit your changes. When you commit, hooks will be executed to check your code.

Notes

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:

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.