5.5 HTML5 Renderer

The HTML5 Renderer is a subclass of the Page Template Renderer (Section 5.3). Therefore most of the work is done in its collection of templates, all written using the Jinja2 template engine. In particular Jinja2 must be installed on your system to use this renderer.

In addition, this renderer allows packages to override certain templates, add css or javascript files, and push output files through various filters, see Section 5.5.2.

Options described in Section 2.1.7 provide easy ways to customize output. In particular the --extra-css option allows to override CSS styles. Since the generated HTML contains no inline style (except for some size specification for images and tables), these CSS overrides allow to completely change the output style.

For large scale CSS changes, one can create a new CSS theme, either from scratch or by customizing an existing theme. Existing themes are generated using the CSS extension language SASS (see http://sass-lang.com/). Their sources are located in ‘plasTeX/Renderers/HTML5/sources/sass/’. One way to use customize them is to do the following (assuming SASS is available on your system). Copy the above directory somewhere else, say in ‘mysass’, copy ‘theme-blue.scss’ to ‘theme-custom.scss’ and replace “blue” in the first line by “custom”, copy ‘_variables_blue.scss’ to ‘_variables_custom.scss’, modify a number of values in this file and compile using

sass --update --sourcemap=none mysass:build

This will create ‘build/theme-custom.css’ which can be copied to your project and used by plasTeX using

plastex ---no-theme-css --extra-css=theme-custom.css mytexfile.tex

Of course one can also change other ‘scss’ files for larger changes. Note that distributed theme css also went through autoprefixer (https://autoprefixer.github.io/) to ensure cross browser compatibility and cssnano (http://cssnano.co/) to reduce their size (all those steps are performed by ‘plasTeX/Renderers/HTML5/sources/build-css.sh’). If CSS modifications are not enough, one can override templates as discussed in Section .

The normal way to handle mathematics in this renderer is to use MathJax (see https://www.mathjax.org) to render mathematics on client side. This is controlled by the --use-mathjax option which is set to true by default. Option --mathjax-url indicates where to find the MathJax library. By default it uses a CDN which ensures using the latest version but prevents offline use. Instead of client-side rendering, one can use filters to handle mathematics on the author side. For instance one can use mathjax-node (https://github.com/mathjax/MathJax-node) or KaTeX (https://khan.github.io/KaTeX/). In this case, one can disable inclusion of MathJax using option --no-mathjax and use option --filters to call the author-side mathematics renderer.