3 How to

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

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:

$ make4ht foo.tex "pic-m,pic-equation,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:

$ make4ht -f html5+dvisvgm_hashes foo.tex \ 
"pic-m,pic-equation,svg"

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:

$ make4ht foo.tex "mathjax"

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.

\Preamble{xhtml} 
\Configure{MathJaxConfig}{{ 
    tex: { 
      tags: "ams", 
      \detokenize{% 
      macros: { 
        sc: "\\small\\rm", 
        sl: "\\it", 
      } 
  } 
} 
}} 
\begin{document} 
\EndPreamble

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:

\Preamble{xhtml} 
% change catcode of # to letter 
% in order to support #1 in custom 
% MathJax macros 
\catcode`\#=11 
\Configure{MathJaxConfig}{{ 
    tex: { 
      \detokenize{% 
      macros: { 
        % our sample macro takes a parameter 
        hello: ["\\sqrt{#1}",1], 
      } 
  } 
} 
}} 
% don't forget to change the catcode 
% back to the original value 
\catcode`\#=6 
\begin{document} 
\EndPreamble

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:

\Preamble{xhtml} 
\catcode`\#=11 
\Configure{MathJaxConfig}{{ 
    tex: { 
      macros: { 
      leftbracket: ["\\left\\{#1\\right.",1], /*} */ 
    } 
  } 
}} 
\catcode`\#=6 
\begin{document} 
\EndPreamble

Loading LaTeX command definitions from a file. MathJax has basic support for macro definition using the \newcommand command. You can put these definitions inside a math environment in the HTML page, and MathJax should be able to recognize these commands subsequently. You can use the \Configure{@BODY} command to put it at the beginning of the document, but we provide an easier solution, \Configure{MathJaxMacros}. This command expects path to a file with macro definitions for MathJax. The file needs to contain only definitions using \newcommand, \def, \newenvironment and few others. It cannot contain other commands, so for example inclusion of .sty files will probably not work.

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

\documentclass{amsart} 
\input{mymacros} 
\begin{document} 
\begin{align*} 
 p_{i-1} &= -(p_{i})' - \theta p_i  \myspace \text{if} \hspace{10pt} i=n 
\end{align*} 
\end{document}

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

\newcommand\myspace{\quad}

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

\Preamble{xhtml} 
\Configure{MathJaxMacros}{mymacros.tex} 
\begin{document} 
\EndPreamble

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:

\documentclass[12pt]{book} 
\usepackage{amsmath} 
\usepackage{breqn} 
 
\begin{document} 
\begin{dgroup*} 
\begin{dmath*} 
     A = B 
   \end{dmath*}     %error is around here 
\end{dgroup*} 
\end{document}

Can be configured using this configuration file:

\Preamble{xhtml} 
\Configure{MathJaxConfig}{{ 
    tex: { 
      tags: "ams", 
      \detokenize{% 
        environments: { 
          "dgroup*": ["", ""], 
          "dmath*": ["", ""], 
        } 
      } 
    } 
}} 
\VerbMath{dgroup*} 
\begin{document} 
\EndPreamble

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:

\Preamble{xhtml} 
\tikzset{every picture/.append code={\RestoreMathJaxEnvironments}} 
% you can also use LaTeX hooks: 
\AddToHook{env/foopicture/begin}{\RestoreMathJaxEnvironments} 
\begin{document} 
\EndPreamble

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:

$ make4ht foo.tex "mathml,mathjax"

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

$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.5 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@req@width/\textwidth*100,2)}\char_generate:nn { `\% } { 12 }"} 
\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.

Instead of a configuration, you can require this method using the Gin-percent option.

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' />

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:

\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 \define@key{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.

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

\documentclass{book} 
\usepackage{imakeidx} 
\makeindex 
\makeindex[name=foo,title=Test] 
 
\begin{document} 
Test1\index{Test1} 
Test2\index[foo]{Test2} 
\newpage 
Test3\index{Test3} 
Test4\index[foo]{Test4}. 
And Test1\index{Test1} again. 
 
\printindex 
\printindex[foo] 
\end{document}

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

Make:htlatex {} 
Make:xindy {} 
Make:xindy {idxfile = "foo.idx"} 
Make:htlatex {}

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.

if mode=="draft" then 
  Make:htlatex {} 
else 
  Make:htlatex {} 
  Make:biber {} 
  Make:htlatex{} 
  Make:htlatex{} 
end

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

$ make4ht filename.tex

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

$ make4ht -m draft filename.tex

3.6.3 R

The preprocess_input make4ht extension supports

Chapter 3
How to

3.1 Change design

3.1.1 Basics

3.1.2 CSS

3.1.3 Web fonts

3.2 Math

3.2.1 Picture math

3.2.2 MathJax LaTeX mode

3.2.3 MathML

3.2.4 Subscripts and superscripts

3.2.5 MathJax Node

3.3 Graphics

3.3.1 Include graphics (svg,pdf)

3.3.2 Change image size and resolution

3.3.3 Use relative size for images

3.3.4 Change image’s alternative text

3.4 Plain TeX

3.5 Blogging

3.6 Work with external commands

3.6.1 Indexing

3.6.2 Bibliographies

3.6.3 R

3.6.4 Markdown

3.6.5 PythonTeX

Chapter 3How to

3.1 Change design

3.1.1 Basics

3.1.2 CSS

3.1.3 Web fonts

3.2 Math

3.2.1 Picture math

3.2.2 MathJax LaTeX mode

3.2.3 MathML

3.2.4 Subscripts and superscripts

3.2.5 MathJax Node

3.3 Graphics

3.3.1 Include graphics (svg,pdf)

3.3.2 Change image size and resolution

3.3.3 Use relative size for images

3.3.4 Change image’s alternative text

3.4 Plain TeX

3.5 Blogging

3.6 Work with external commands

3.6.1 Indexing

3.6.2 Bibliographies

3.6.3 R

3.6.4 Markdown

3.6.5 PythonTeX

Chapter 3
How to