Chapter 3
How to

3.1 Change design

3.1.1 Basics

By default, TeX4ht separates paragraphs by space. If you want to use text indenting instead, try the p-indent option.

3.1.2 CSS

3.1.3 Web fonts

It is easy to change fonts in web pages using CSS, but if you want to use actual font files for the distribution, for example, in an Epub file, TeX4htprovides the following configurations. This example shows how to use OTF files for the EB Garamond font.

% define font family. The first argument is family name 
% that can be used in CSS font-family rule 
% second argument is the family name declared by the font 
\Configure{FontFamily}{rmfamily}{EB Garamond} 
% declare font filenames for particular font styles. 
% the font files must be placed in the location that is 
% declared. 
% these four font styles are supported 
\Configure{NormalFont}{EBGaramond-Regular.otf} 
\Configure{ItalicFont}{EBGaramond-Italic.otf} 
\Configure{BoldFont}{EBGaramond-Bold.otf} 
\Configure{BoldItalicFont}{EBGaramond-BoldItalic.otf} 
% use CSS to use the declared font family in the document 
% serif is used as a fallback 
\Css{body{font-family: "rmfamily", serif;}}

3.2 Math

3.2.1 MathJax

3.2.2 MathML

3.2.3 Subscripts and superscripts

Subscript and superscript support in TeX4ht is a bit complicated. The catcodes of _ and ^ characters are changed and they are active characters instead. This is necessary in order to insert the markup tags for these structures. One consequence of this is that you need to use a correct grouping for content that should be affected by these operators. For example, instead of

$A_\mathit{...}$

use the following, with added group around the \mathit command:

$A_{\mathit{...}}$

If you define custom commands in the document preamble, use \sp and \sb instead of ^ and _.

For example:

\newcommand \coeffX [4][X]{\mathbf{#1}_{{#2},{#3}}(#4)}

should become:

\newcommand\coeffX [4][X]{{\mathbf{#1}}\sb{#2,#3}(#4)}

Sometimes, it is not possible to change the source files. In this situation, you can pre-process the source using custom script that reads the original file, fixes the code and then pipes the modified output to make4ht.

For example, you may want to change this input:

$k'^4_{i}$

to the correct form:

$k^{\prime 4}_{i}$

This, and other common issues, can be done using the following Lua script:

for line in io.lines() do 
  -- fix primes 
  line = line:gsub([[%'%^(.-)%_]], [[^{\prime %1}_]]) 
  -- fix \mathrm{hello}^2 
  line = line:gsub([[(\[a-zA-Z]-)(%b{})([%^%_])]], [[{%1%2}%3]]) 
  -- fix x_\mathrm{hello} 
  line = line:gsub([[([%_%^])(\[a-zA-Z]-)(%b{})]], "%1{%2%3}") 
  -- fix 10^2 
  line = line:gsub("([%d])([%_%^])", "{%1}%2") 
  -- fix {}_x 
  line = line:gsub("{}([%_%^])", "{\\HCode{}}%1") 
  print(line) 
end

It uses Lua version of regular expressions to find the code we want to fix. The command to execute it could be:

texlua filter.lua < sample.tex | make4ht -j sample - "mathml,mathjax"

The -j option is used to name the output file, which is necessary because the input comes from a pipe. The dash used in the place of filename tells make4ht to read input from the standard input.

We use MathJax to render MathML, as MathML is not supported by all browsers.

3.2.4 MathJax Node

3.3 Graphics

3.3.1 Include graphics (svg,pdf)

3.3.2 Change image size and resolution

You can use \Configure{Gin-dim} command to change the way how image dimensions are calculated. By default, TeX4ht relies on information about image dimensions provided by the Graphics package. If you use explicit dimensions (like width=0.5\textwidth), the actual dimension calculated by TeX is used.

One problem is that if you set only one dimension, for example width, the other dimension will be set to the same value. You usually don’t want this, unless your image is a square. To get the correct value for all dimensions, Graphics uses a .xbb file for image. It can be created using the following command:

ebb -x *.jpg

Run analogous command for every other supported image format you use. This will ensure that correct values are used for implicitly calculated dimensions.

3.3.3 Use relative size for images

The following configuration file example can be used to get image dimensions relative to the original page width. Thanks to the LaTeX 3 project, we can use the l3fp package to calculate the image dimensions in percents.

\Preamble{xhtml} 
\makeatletter 
\ExplSyntaxOn 
\Configure{Gin-dim} 
{style="width:\fp_eval:n{round(\Gin@[email protected]/\textwidth*100,2)}\%"} 
\ExplSyntaxOff 
\makeatother 
\begin{document} 
\EndPreamble

In this configuration, we divide the image width passed to \includegraphics by the document text width. This portion is then multiplied and rounded to get the correct percent value. The calculated value is used in the style attribute of the generated <img> element. The l3fp command \fp_eval:n is used for the calculation. LaTeX 3 is part of LaTeX kernel, so we don’t need to require packages that it provides.

The following example code:

\includegraphics[width=0.5\textwidth]{example-image.png}

produces following HTML code:

<img style='width:50%' alt='PIC' src='example-image.png' />

To disable setting of the image dimensions in HTML code completely use the following configuration:

\Preamble{xhtml} 
\Configure{Gin-dim}{} 
\Css{img { 
    max-width: 100\%; 
    height: auto; 
}} 
\begin{document} 
\EndPreamble

This configuration uses CSS to set the maximum image dimension. This ensures that the image is donwsized on devices smaller than is the actual image size.

3.3.4 Change image’s alternative text

The Graphicx package recently added alternative text support, which can be used to describe the image. This is necessary for the accessibility purposes.

If you use an older system, without support for this attribute, you can use the following example to define it yourself, and use it with the \includegraphics command. The attribute is named alt. Here is a sample file that shows how to do that:

\documentclass{article} 
\usepackage{graphicx} 
\makeatletter 
\define@key{Gin}{alt}{} 
\makeatother 
\begin{document} 
\includegraphics[alt={alt tags, information}]{example-image} 
\end{document}

The \[email protected]{Gin}{alt}{} command defines a dummy command that is used by regular LaTeX. We need to redefine this key for TeX4ht, so it uses the configuration that can specify the image alternative text, GraphicsAlt.

\Preamble{xhtml} 
\makeatletter 
\define@key{Gin}{alt}{\Configure{GraphicsAlt}{#1}} 
\makeatother 
\begin{document} 
\EndPreamble

The resulting HTML file now contains image with the alt attribute:

<!--  l. 7  --><p class='noindent'><img alt='alt tags, information' src='example-image.png' /> 
</p>

3.4 Plain TeX

TeX4ht supports Plain TeX, but it can be a bit tricky. In general, you will have to provide configurations to get good markup for your custom commands. You will also need to add few commands to your source file:

%!TEX TS-program = tex 
\input plain-4ht.tex 
\document 
Hello world 
\enddocument

The first line contains magic comment that tells make4ht to use Plain TeX instead of LaTeXfor the compilation. \document and \enddocument commands are important, because they are crucial for correct execution of TeX4ht.

They are declared in the plain-4ht.tex file:

\def\documentstyle#1{} 
\documentstyle{tex4ht} 
\csname tex4ht\endcsname 
\def\document{} 
\def\enddocument{\csname bye\endcsname}

In the PDF mode, these commands will do nothing, except for execution of the \bye command.

The document can be compiled using:

make4ht -f html5+detect_engine filename.tex

The -f html5+detect_engine requires the detect_engine extension, which uses the magic command in the source file to determine which TeX engine to use. It is necessary for the correct Plain TeX support.

3.5 Blogging

3.6 Work with external commands

3.6.1 Indexing

make4ht supports Makeindex, Xindy and Xindex indexing processors. You need to use a build file that calls them explicitly. The intermediate file with indexing information uses special format with TeX4ht, so it is not possible to just call these commands from the command line. make4ht uses some pre-processing and post-processing to make the indexing work correctly.

Here is a simple example:

\documentclass{article} 
\usepackage{makeidx} 
\makeindex 
\begin{document} 
Hello\index{hello} world\index{world} 
\printindex 
\end{document}

This file can be compiled using the following build file, build.lua:

Make:htlatex {} 
Make:makeindex {} 
Make:htlatex{}

You can use Make:xindex or Make:xindy in place of Make:makeindex.

As there are no page numbers in XML and HTML, each \index command produces unique number, and destination to the backlink from the index.

3.6.2 Bibliographies

3.6.3 R

3.6.4 Markdown

3.6.5 PythonTeX