## Chapter 3How 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.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.

### 3.2 Math

TeX4ht supports multiple methods for the math conversion in the HTML output. Simple formatting and pictures for more complex elements is used by default, but you can request other methods, which usually produce output that is better looking and also better for the accessibility.

Note that in other output formats than HTML, which are usually based on XML, TeX4ht outputs math in MathML.

#### 3.2.1 Picture math

By default, pictures are used only for display math. You can pass additional options to TeX4ht to request pictures also for inline math, equations and other environments. You can also require the SVG output, to get pictures in a better quality.

For example, the following command should produce pictures in SVG:

See the TeX4ht Options chapter for other pic-… options.

If you have a large number of math content, the conversion to images can take a long time. You can use the dvisvgm_hashes extension for make4ht to reuse the images that were already generated, and to use a parallel conversion:

#### 3.2.2 MathJax LaTeX mode

You can also pass math to the HTML output and rely on the MathJax library for the rendering. MathJax is widely used for this purpose and generaly produces great results from the accessibility and rendering views.

To require the MathJax output, use the mathjax option:

There are some limitations in MathJax though:

• If you use custom commands, you need to configure MathJax to recognize them.
• Cross-references to equations should work, but other numbered math environments don’t work out of the box. You can try the Lua scripts proposed in this post on TeX.sx as a workaround.

The additional configuration for MathJax can be provided in the MathJaxConfig configuration.

The following example provides support for custom LaTeX macros.

The configuration needs to be passed as a JavaScript object, this means that you need to use extra {} brackets. The \detokenize macro is used to avoid possible issues with catcodes in the configuration. Backslashes must be doubled in the JavaScript strings, so they need to be written twice for all custom macros. Contents of this configuration is already enclosed in the \HCode command, so you cannot use this command in the configuration.

If you want to define macros with parameters, you may run to issues with the # character, used for parameters. You need to change the catcode of this character to letter before the MathJaxConfig configuration:

Note that number of opening and closing brackets is important, they need to be balanced. For example, if you use \left\\{, you need to add special closing bracket for \\{. The problem is that this closing bracket can cause syntax error in the generated JavaScript, as the opening bracket was contents of the string. You can fix that by enclosing the closing bracket in JavaScript comment string (/* } */. In this way, LaTeX will see the correct number of brackets, but JavaScript will ignore the extra ones:


Here is an example that reuses definitions in both PDF and MathJax modes:

This file includes the mymmacros.tex, which contains a definition of the ∖myspace command:

This file can be included for MathJax using this configuration file:

Custom environments in MathJax. If you want to add support for a new environment, you can use the \VerbMath command, and you will also need to pass suitable configuration to MathJax. For example for the following TeX file:

Can be configured using this configuration file:

The \VerbMath command can be used just for the dgroup* environment, as it will pass the whole contents, including the dgroup* environment, to the HTML file. But you will need to provide MathJax configuration for both of these environments, as they are not supported by default.

Math inside TikZ pictures When you use math in pitcture environments, for example TikZ pictures, you need to restore the original meanings of math environments. This can be done using the \RestoreMathJaxEnvironments command at the beginning of the environment. For example, to restore them for any environment that uses TikZ, use this configuration file:

#### 3.2.3 MathML

You can get the MathML output in HTML using the mathml option. In other formats, such as JATS, or ODT, MathML is used automatically. The support for MathML in web browsers is not great, so it usually better to load it together with MathJax, using the mathml,mathjax options:

The advantage over MathJax’s LaTeX mode is that TeX4ht expands custom commands in the MathML mode, also cross-referencing should work better.

#### 3.2.4 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

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

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

For example:

should become:

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:

to the correct form:

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

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

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

#### 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:

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.

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:

produces following HTML code:

You can also require the above method using the Gin-percent option.

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

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:

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.

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

### 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:

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:

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

The document can be compiled using:

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

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

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.

For multiple indices, you can multiple calls to indexing commands. For example:

This example contains two indices. The foo index needs an extra indexing call:

#### 3.6.2 Bibliographies

You can use either Make:bibtex or Make:biber in a build file to compile your bibliography. The following build file is meant for use with BibLaTeX.

This build file also supports the draft mode for faster compilation. Use this command when you add a new citation:

In other cases, when you just added normal text, you can compile the file faster using the draft mode:

#### 3.6.3 R

The preprocess_input make4ht extension supports