6.8 Plugins

As explained in Chapter 2, one can use command line options of configuration files to use extra packages or templates or even a full custom renderer. However this is not convenient if you want use the same extras in several projects, or want to distribute them. In order to do that, you can create a plasT_eX plugin. Such a plugin is simply a python package that contains one or several subpackages named ‘templates’, ‘Packages’ or ‘Renderers’.

In this section, we describe some minimalistic plugins demonstrating the possibilities offered. For clarity we will separate the three kinds of plugin content into three plugins but of course a sophisticated plugin can combine several kinds.

Any kind of python packaging can be used as long as it allows to put the plugin code into the Python search path and can bundle Python code with some other files, typically template files. In this documentation we will use setuptools and put all configuration into a ‘pyproject.toml’ file which is essentially the same for all three examples, differing only in the name and description metadata.

[project]
name = "my_wonderful_plastex_plugin"
version = "1.0.0"
description = "A nice plasTeX plugin."
requires-python = ">=3.7"
dependencies = ["plastex>=3.0"]

[tool.setuptools.package-data]
plastex_markdown_renderer = ["**/*.jinja2", "**/*.jinja2s"]

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

Note in particular the line about packaging Jinja files together with python files. Of course you can add CSS file of javascript files or any other kind of required file. Note also that you will need a bit more metadata if you want to upload your plugin to pypi for instance.

You can then install this python package by running pip install . from the folder containing that ‘pyproject.toml’. Then you can compile a file ‘text.tex’ using your plugin by running

plastex --plugins my_wonderful_plastex_plugin -- test.tex

In the above command, the double-dash before the file name is needed because the --plugins options takes a list of space separated plugins.