Chapter 7
Configurations

7.1 Private Configuration Files

It is highly recommended to leave source LaTeX and TeX files intact, and not introduce TeX4ht configurations there. The configurations should be introduced indirectly in private configuration files. Source files containing just native LaTeX and TeX code permit their compilation to different output formats, including PostScript and PDF, by TeX4ht and other tools.

Packages used by the general LaTeX community typically provide better support than one can expect from tailoring private commands and configurations for such commands. It is also expected to take less effort to learn the features of existing packages than designing new ones. Consequently, one is advised to investigate available resources before committing to work on private features.

7.1.1 Requesting Private Configuration Files

Private configuration files can be requested by passing the -c option to make4ht: 

make4ht -c mycfg.cfg myfile

A configuration file should take the following form for LaTeX files: 

...early definitions... 
\Preamble{xhtml,options} 
...definitions... 
\begin{document} 
...insertions into the header of the html file... 
\EndPreamble

The ∖Preamble command should always use xhtml as the first option. Otherwise, TeX4ht switches to the HTML 4 mode and XML post-processing tools used by make4ht to fix some common issues will fail! For more information about available options, see the List of options section (6.1). 

\Preamble{xhtml} 
\begin{document} 
  \Css{body { color : red; }} 
\EndPreamble

Notes 

\documentclass{...} 
\newcommand\mycommand{...} 
\begin{document} 
Use \mycommand{...} 
\end{document}

7.1.2 Configuration file management

It is possible to reuse common TeX4ht configurations used in several configuration files. They can be inserted in a custom LaTeX package, but there is one important thing to be aware of. The configuration hooks are inserted to the patched commands when the compilation reaches the \begin{document} command, so configurations for these hooks declared before the hook definition have no effect. It is necessary to include them in the ∖AtBeginDocument command.

Sample package, commonconfigurations.sty: 

\ProvidesPackage{commonconfigurations} 
\AtBeginDocument{% 
\Configure{@HEAD} 
{\HCode{<meta name="test" content="test"/>\Hnewline}} 
} 
\endinput

It can be requested in a configuration file using ∖RequirePackage command. 

\Preamble{xhtml} 
\RequirePackage{commonconfigurations} 
\begin{document} 
\EndPreamble

7.2 Custom output formats

7.3 tex4ht Commands

7.3.1 Low-level TeX4ht Commands

∖Configure{name}{arg 1}…{arg n}

The ∖Configure command declares code that is inserted into hooks related to the name configuration. It is possible to define up to nine hooks, so number of arguments is variable.

∖ConfigureEnv{<environment name>}{before env}{after env} {before-list}{after-list}

∖HCode{output format markup} is a basic command for insertion of the output format markup, as it’s content is not escaped for the < and >.

This command allows only for the expansion of macros, before sending its content to the output. The instruction \Hnewline may be introduced there for requesting line breaks, and the command \# may be used for the sharp symbol #. 

First line\HCode{<br />} 
second line 
 
You don't want to include tags directly into the document '<br>'.

∖Tg<markup> is a variation of the ∖HCode command that don’t require braces, and it does some additional processing.

∖ifOption{name of the option to be checked}{true part}{false part}

This command can be used in the private configuration files to test if a custom option was used

∖Link[target-file arguments]{target-loc}{cur-loc} text inside link∖EndLink

This command requests an anchor that links to target-file#target-loc, and marks the current location with the name cur-loc.

The component in square brackets [...] is optional when it is empty, the target file does not need to be specified if it will be created as part of the source file compilation.

For example, if we are creating separate HTML files for each chapter, we can use \Link in this form: 

\chapter{First} 
\Link{secondlink}{firstlink}Go to second chapter\EndLink 
\chapter{Second} 
\Link{firstlink}{secondlink}Go to first chapter\EndLink

The link from the first chapter will lead correctly to the second, even though they are each in a different file.

∖LinkCommand creates a ∖Link-like command. It has variable number for parameters:

  1. tag name
  2. href-like attribute
  3. name-like attribute
  4. insertion
  5. /, if empty element
  6. replacement for # character (ignored if absent)

Example: 

\LinkCommand\JSLink{a,\noexpand\jsref,name} 
\def\jsref="#1"{href="javascript:window.open('#1')"} 
 
% example of use of the defined command: 
\JSLink{a}{}xx\EndJSLink % link to a destination 
\Link{}{a}\EndLink       % set link destination (or by \JSLink{}{a}\EndJSLink)

∖Tag{label}{content}

∖Ref{label}

∖LikeRef{label}

∖Tag and ∖Ref are commands introduced cross-referencing content through .xref auxiliary files.

∖LikeRef is a variant of ∖Ref which doesn’t verify whether the labels exit. It is mainly used in ∖Link and ∖edef environments.

∖ifTag{label}{true part}{false part}

Test existence of a tag, and execute code depending on that.

7.3.3 Cross references

For correct support of cross-references, you need to place link destinations for labels. TeX4ht handles labels defined by the ∖refstepcounter command, but links for labels that use a direct setting of the ∖@currentlabel command needs to be inserted manually.

∖AnchorLabel inserts link destination for the current ∖label command. It will be used in ∖ref, ∖pageref, and other cross referencing commands that point to the label. It should be placed after change of ∖@currentlabel.

∖SkipRefstepAnchor don’t insert anchor for the next ∖refstepcounter.

∖ShowRefstepAnchor show anchor for the next ∖refstepcounter.

7.3.4 Paragraph Handling

Paragraph handling is one of the more complicated areas in TeX4ht. You must handle insertion of tags for paragraph opening and closing, to prevent wrong nesting of XML tags. Mismatch of tags leads to issues with LuaXML post-processing of the generated files, preventing many fixes that are necessary for correct conversion.

∖HtmlParOff turns off insertion of paragraph tags in the following text.

∖HtmlParOn enables insertion of paragraphs tags.

∖IgnorePar asks to ignore the next paragraph.

∖ShowPar asks to take into account the following paragraphs.

∖IgnoreIndent asks to ignore indentation in the next paragraph.

∖ShowIndent asks to check indentation in the following paragraphs.

∖SaveEndP saves the content of ∖EndP, and sets it to empty content.

∖RecallEndP resets the content of ∖EndP.

∖SaveHtmlPar saves current configuration for paragraphs. It can be useful before local declaration of ∖Configure{HtmlPar}.

∖RecallHtmlPar resets configuration for paragraphs to the value saved by ∖SaveHtmlPar.

The following example adds <div>...</div> tags around contents of the document body. The \ifvmode\IgnorePar\fi commands will prevent insertion of the <p> tag before <div> if we are in TeX’s vertical mode. The \EndP closes currently opened paragraph, if it is opened. The \par\ShowPar commands start new paragraph after the inserted <div> tag. It is necessary to explicitly start paragraphs sometimes. 

\Configure{@BODY} 
{\ifvmode\IgnorePar\fi\EndP 
 \HCode{<div>}\par\ShowPar} 
\Configure{@/BODY} 
{\ifvmode\IgnorePar\fi\EndP 
 \HCode{</div>}}

∖Configure{HtmlPar}{content at the start non-indented paragraphs} {content at the start indented paragraphs}{insertion into ∖EndP, at the start of non-indented paragraphs}{insertion into ∖EndP, at the start of indented paragraphs}

Example: 

\Configure{HtmlPar} 
{\EndP\HCode{<p class="indent">}} 
{\EndP\HCode{<p class="noindent">}} 
{\HCode{</p>}} 
{\HCode{</p>}}

7.3.5 Logical Document Structure Commands

I’ve created an alternative commands to ∖HCode or ∖Tg. The idea is to define semantic names for logical blocks of the document, such as titles, authors, sections etc. HTML elements and attributes can be assigned to these logical blocks. There are commands for inline and block level elements, eliminating need for constructs like \ifvmode\IgnorePar\fi\EndP etc.

∖NewLogicalBlock{name} create a new logical block.

∖SetBlockProperty{name}{attribute name}{value} set block attribute .

∖SetTag{name}tag name assign element name to the logical block

∖BlockElementStart{name}{additional attributes} start block level element.

∖BlockElementEnd{name} close block level element.

∖InlineElementStart{name}{additional attributes} start inline level element.

∖InlineElementEnd{name} close inline level element.

The default tag name for declared logical blocks is <span>. You need to use the ∖SetTag command only when you want to use a different element.

The attributes can be set either using ∖SetBlockProperty, or in the second argument to ∖BlockElementStart and ∖InlineElementStart commands. First method should be used for static attributes that don’t change, for instance class. The second method is preferred for dynamic attributes, such as id, which should be different for every element.

The main idea behind this mechanism is to allow easy work with new HTML5 elements and attributes for WAI-ARIA or Schema.org properties. I hope that this should allow us to make somehow more clear configurations for basic document building blocks.

Example: 

\NewLogicalBlock{textit} 
\SetBlockProperty{textit}{class}{textit} 
 
\NewLogicalBlock{maketitle} 
\SetTag{maketitle}{header} 
 
\NewLogicalBlock{titlehead} 
\SetTag{titlehead}{h1} 
\SetBlockProperty{titlehead}{class}{titleHead} 
 
% configure \textit using inline level elements 
\Configure{textit} 
{\NoFonts\InlineElementStart{textit}{}} 
{\InlineElementEnd{textit}\EndNoFonts} 
 
% configure \maketitle using block level elements 
\Configure{maketitle}{% 
{\Configure{maketitle}{}{}{}{}% 
\Tag{TITLE+}{\@title}} 
\BlockElementStart{maketitle}{}} 
{\BlockElementEnd{maketitle}} 
{\NoFonts\BlockElementStart{titlehead}{}} 
{\BlockElementEnd{titlehead}\EndNoFonts}

7.4 Document Styling Using CSS

TeX4ht provides several commands that can be used for changing of the document appearance using Cascading Style Sheets (CSS). Only basic styling for the document is provided by default. Additional styles are added by configurations for the fonts, packages and commands used in the document. Full control of the document styling can be achieved using following commands and configurations.

∖Css{content}

This command sends its content to the CSS file of the document.

∖Configure{AddCss}{CSS file name}

Add local CSS file. 

\Css{body{max-width:70ch;margin: 1rem auto;}} 
\Configure{AddCss}{custom.css} 
% link to a CSS on some web: 
\Configure{@HEAD}{\HCode{<link type="text/css" rel="stylesheet" href="https://example.com/style.css" />}}

\CssFile[list-of-css-files]content\EndCssFile

The CSS file TeX4ht used by default initially consists just a single line, /* css.sty */. This line is later replaced with the code submitted by the \Css{...} commands.

The \CssFile command allows to specify an alternative to the initial CSS file. The alternative file consists of the code loaded from listed files, and of the content explicitly specified in its body. 

\ConfigureList{mylist} 
{\HCode{<div class="mylist">}} {\HCode{</div>}} {* }{} 
 
\begin{document} 
 
\CssFile 
/* css.sty */ 
.mylist { color : red; } 
\EndCssFile

The names in the list of files should be separated by commas, and the rectangular brackets are optional when the list is empty.

The file should include a line having the content of /* css.sty */. If more than one such line is included, the content of the \Css{...} commands replace the first occurrence of this line. Arbitrary many space characters may appear around the substrings /* and */.

7.5 Webfonts

The declared font family is not used automatically, it is necessary to select it using the font-family Css property.

The default font family name which should be used in the Css font-family command for a declared font is rmfamily. It use the Latin Modern font installed on the viewer’s system.

∖Configure{FontFamily}{cssfamilyname}{LocalFontName}

Change default CSS font family name. Example: 

\Configure{FontFamily}{rmfamily}{Latin Modern}

The font shapes can be configure using ∖Configure{NormalFont}, ∖Configure{ItalicFont}, ∖Configure{BoldItalicFont} and ∖Configure{BoldFont}. The argument should be font file in the format supported by browsers, such as woff or otf.

Full example of font CSS configurations: 

\Configure{NormalFont}{normal-font-file.otf} 
\Configure{BoldFont}{bold-font-file.otf} 
\Configure{BoldItalicFont}{bold-italic-font-file.otf} 
\Configure{ItalicFont}{italic-font-file.otf} 
% Add another font family 
\Configure{FontFamily}{hello}{Linux Libertine O} 
\Configure{NormalFont}{hello-font-file.otf} 
\Css{body{ 
  font-family: rmfamily, "AnotherFontFamilyName", serif; 
}} 
\Css{span.hello{font-family: hello, sans-serif;}}

7.6 Use JavaScript

∖Configure{AddJs}{filename of JS file to be included}

This configuration inserts link to a local JavaScript file.

∖JavaScript ... ∖EndJavaScript insert JS code in the verbatim mode. This command is available only when the javascript option is active. It can put JS code directly to the document. If used in the configuration file, it should be placed after \begin{document}.

Full example of configuration file that use both of these methods: 

\Preamble{xhtml,javascript} 
\Configure{AddJs}{sample.js} 
\begin{document} 
\JavaScript 
console.log("Hello JS"); 
\EndJavaScript 
\EndPreamble

7.7 Basic document structure and metadata

7.7.1 File extension

∖Configure{ext}{default extension name for target files (recorded in ∖:html)}

It can also be requested through a command line option ext=....

7.7.2 HTML header

∖Configure{PROLOG}{Comma separated list of hooks to appear before HTML}

Each hook E is declared to be configurable by an instruction of the form \NewConfigure{E}{1}

Example: 

\Configure{PROLOG}{VERSION,DOCTYPE,*XML-STYLESHEET} 
\Configure{VERSION}{\HCode{<?xml version="1.0"?>}}

A star ’*’ prefix calls for accumulative configurations

7.7.3 Document structure

The following configurations are used to declare tags for basic structure of generated documents.

∖Configure{DOCTYPE}{doctype definition}

∖Configure{HTML}{HTML start}{HTML end}

∖Configure{HEAD}{HEAD start}{HEAD end}

∖Configure{@HEAD}{content added to HEAD}

∖Configure{BODY}{BODY start}{BODY end}

∖Configure{TITLE}{TITLE start}{TITLE end}

∖Configure{Preamble}{code executed at the very beging}{code executed at ∖EndPreamble}

The \Configure{@HEAD}{...} command is additive, concatenating the content of all of its appearances. An empty parameter requests the cancellation of the earlier contributions.

For instance, 

\Configure{@HEAD}{A} 
\Configure{@HEAD}{} 
\Configure{@HEAD}{B} 
\Configure{@HEAD}{C}

contributes ‘BC’.

∖Configure{@BODY}{additive insertions at start of BODY}

∖Configure{@/BODY}{additive insertions at end of BODY}

Variants of \Configure{@HEAD} which contribute their content, respectively, after <body> and before </body>.

The document structure hooks are placed in the following sequence: 

<DOCTYPE> 
<HTML 1> 
  <HEAD 1> 
     <TITLE 1> 
        <@TITLE> 
        <TITLE+> 
     <TITLE 2> 
     <@HEAD> 
  <HEAD 2> 
  <BODY 1> 
  <@BODY> 
  ...... 
  <@/BODY> 
  <BODY 2> 
<HTML 2>

7.7.4 Titles

∖Configure{TITLE+}{Title contents}

Set contents of the <title> element.

There are also similar configurations for pages split on sectioning commands. For example, for document that is split on chapters, use: 

\Configure{TITLE+}{My web site |\@title} 
\Configure{chapterTITLE+}{My web site | \thechapter\space#1} 
\Configure{likechapterTITLE+}{My web site | #1}

likechapter prefix is used for \chapter* command. The text of sectioning command can be accessed using #1.

∖Configure{@TITLE}{redefinitions of commands in the title group}

Acts as a hook for introducing localized configurations. As is the case for \Configure{@HEAD}, the contribution of \Configure{@TITLE} is also additive.

∖Configure{CutAtTITLE+}{an insertion just before the content of TITLE}

∖Configure{HPageTITLE+}{an insertion just before the content of TITLE}

If #1 is a one parametric macro, it gets the title content for an argument.

7.8 Page Breaks

TeX4ht can break the generated document to separate files, each containing contents of sectioning unit. The 1, 2, …,8 options asks for a tree-structured set of files, reflecting on the sectioning of the document to the specified depth.

Sequential prev-next links within the hierarchy, instead of the default hierarchical ones, can be requested with the next option. The option sections+ creates titles for the sectioning commands that link to the tables of contents. The sec-filename option requests that split files will be named according to the section titles, instead of sequential numbers. The cut-fullname option will prevent truncating of generated filenames.

Finer control is possible with the following commands and configurations:

∖CutAt{at-unit,until-unit-1,until-unit-2,…}

This directive asks the sectioning commands ∖at-unit to place their units in separate hypertext pages. The pages are to terminate upon encountering any of the commands in the list ∖at-unit, ∖until-unit-1, ∖until-unit-2,….

Within the ∖CutAt instruction, the starred commands of LaTeX should be referenced with the prefix like instead of the postfix of *, and appendices through the entry appendix.

A plus character +, before the leading parameter, requests buttons that link to the hypertext pages; e.g., ∖CutAt{+likesection}.

The end points of sections not specified within the ∖CutAt commands can be made known with instructions of the form ∖Configure{endunit}{unit,unit,...}. 

\CutAt{section,chapter} 
\tableofcontents 
\chapter{...}  ......  \section{...}  ......  \section{...}  ...... 
\chapter{...}  ......  \section{...}  ......

Cut points at arbitrary points can be introduced by introducing section-like commands in a manner similar to 

\NewSection\mysection{} 
\CutAt{mysection}

∖Configure{CutAt}{unit}{before-button}{after-button}

∖Configure{+CutAt}{sectioning type}{before}{after}

Requests delimiters for the ∖CutAt buttons of the specified sectioning type

Example: 

\Configure{+CutAt}{mysection}{[}{]}

∖PauseCutAt{section type}

∖ContCutAt{section type}

Pause and continue page breaking for the given section type. Note that it can be used for multiple section types.

For example, if you use the command line option ‘4’, with the book class, which breaks pages up to the subsection level, and you want to stop breaking sections, you need to use: 

\PauseCutAt{section} 
\PauseCutAt{subsection}

To resume breaking, use: 

\ContCutAt{section} 
\ContCutAt{subsection}

∖Configure{CutAt-filename}{filename for the next cut file}

A 2-parameter hook for tailoring section-based filenames. The section type is available through #1. The section title is accessible through #2.

Example: 

\Configure{CutAt-filename}{\NextFile{#1-#2.html}}

Cross-links provide navigation between HTML pages broken into multiple files from a single source document.

The following configurations modify behaviour of cross-links between pages in a multi page document.

∖Configure{crosslinks}{left-delimiter}{right-delimiter}{next}{prev} {prev-tail}{front}{tail}{up}

This command configures the appearance of the cross-links between hypertext pages obtained for sectioning commands. 

 \Configure{crosslinks} 
   {}{}{$\scriptstyle\Rightarrow$} 
   {$\scriptstyle\Leftarrow$} 
   {}{}{}{$\scriptstyle\Uparrow$}

∖Configure{crosslinks*}{1--7 arguments}

Links to be included and their order. Available options: next, prev, prevtail, tail, front, up. The last argument must be empty.

Default values: 

\Configure{crosslinks*}{next} 
   {prev}{prevtail} 
   {tail}{front} 
   {up}{}

∖Configure{crosslinks+}{before-top-links}{after-top-links} {before-bottom-links}{after-bottob-links}

The top cross links are omitted, if both #1 and #2 are empty. The bottom cross links are omitted, if both #3 and #4 are empty.

∖Configure{next}{the anchor of the next button of the front page}

Default: The value provided in \Configure{crosslinks}

∖Configure{next+}{before}{after}

#1

before the next button of the front page, when the ‘next’ option is active.

#2

after the button

Default: The values provided in \Configure{crosslinks}

∖Configure{crosslinks:next}{local configurations for the delimiters and hooks}

∖Configure{crosslinks:prev}{local configurations for the delimiters and hooks}

∖Configure{crosslinks:prevtail}{local configurations for the delimiters and hooks}

∖Configure{crosslinks:tail}{local configurations for the delimiters and hooks}

∖Configure{crosslinks:front}{local configurations for the delimiters and hooks}

∖Configure{crosslinks:up}{local configurations for the delimiters and hooks}

∖Configure{crosslinks-}{before}{after}

Asks to show linkless buttons with the following insertions.

The default values are used, if both #1 and #2 are empty

Examples: 

\Configure{crosslinks-}{}{} 
 
\Configure{crosslinks-} 
    {\HCode{<span class="hidden">}[} 
    {]\HCode{</span>} } 
\Css{span.hidden {visibility:hidden;}}

7.10 Tables of Contents

TeX4ht supports tables of contents created using the ∖tableofcontents command in the converted document. In addition, it can add local tables of contents to the

Created from the entries collected in the previous compilation within a ∖jobname.4tc file.

∖Configure{tableofcontents}{before-toc}{end-of-toc}{after-toc} {before-nonindented-par}{before-indented-par}

The end-of-toc is inserted at the end of the internal environment of the tables. The after-toc is included after leaving the internal environment.

∖tableofcontents[unit-1,unit-2,…]

∖TableOfContents[unit-1,unit-2,…]

The ∖tableofcontents command may be followed by a comma separated list of sectioning unit names to be included in the table of contents. The list should be enclosed within square brackets. Alternatively, a command of the form ∖TableOfContents[…] might be used.

∖Configure{writetoc}{definitions-for-the-writing-environment}

TeX4ht expands and then writes the sectioning titles into an auxiliary file, and it might encounter there problems from macros that are not fit for such conditions or for inclusion in the table of contents. The current configuration instruction allows to locally modify the behavior of macros for the writing phase.

New configurations are added to those request earlier by the command. An empty argument cancels the earlier contributions.

For instance, the instruction \section{Foo \\ bar} suggests a configuration similar to \Configure{writetoc}{\let\\\space}.

7.10.1 Local tables of contents

The following commands and configurations can produce tables of contents for chapters or sections.

∖ConfigureToc{unit-name}{before unit number}{before content}{before page number}{at end}

Example: 

\ConfigureToc{section} 
   {} 
   {\Picture[*]{pic.jpg width="13"  height="13"}~} 
   {} 
   {\HCode{<br />}}

As an alternative to ∖ConfigureToc, you can also use the following alternative: 

\def\toc<unit-name>#1#2#3{<before unit number>#1<before content>#2% 
    <before page number>#3<at end>}

∖Configure{TocLink}{∖Link like command}

Configures the link offered in the third arguments of ∖ConfigureToc

Example: 

\Configure{TocLink}{\Link{#2}{#3}#4\EndLink}

∖TocAt{#1,#2,#3,…}

#1

section type for which local tables of contents ∖Toc#1 are requested

#2,#3,…

sectioning types to be included in the tables of contents

The non-leading arguments may be preceded by slashes ’/’, in which cases the arguments specify end points for the tables.

The default setting requests automatic insertion of the local tables immediately after the sectioning heads.

A star ‘*’ character may be introduced, between the ∖TocAt and the left brace, to request the appearances of the tables of contents at the end of the units’ prefaces.

A hyphen ‘-’ character, on the other hand, disables the automatic insertions of the local tables.

In case of a single argument, the command removes the existing definition of ∖Toc#1.

Example: 

\TocAt{mychapter,mysection,mysubsection,/myappendix,/mypart} 
\TocAt-{mysection,mysubsection,/mylikesection} 
\section{...}...\Tocmysection

The definition of the local table of contents can be redefined within \csname Toc#1\endcsname.

Example: 

\TocAt{section} 
\def\Tocsection{\TableOfContents[section]} 
 
\Css{div.sectionTOCS { 
                    width : 30\%; 
                    float : right; 
               text-align : left; 
           vertical-align : top; 
              margin-left : 1em; 
                font-size : 85\%; 
         background-color : \#DDDDDD; 
    }}

Example: Table of content before the section title. 

\Configure{section}{}{} 
   {\Tocsection \let\saveTocsection=\Tocsection 
    \def\Tocsection{\let\Tocsection=\saveTocsection}% 
    \ifvmode \IgnorePar\fi \EndP\IgnorePar 
    \HCode{<h3 class="sectionHead">}\TitleMark\space\HtmlParOff} 
   {\HCode{</h3>}\HtmlParOn\ShowPar \IgnoreIndent \par}

∖Configure{TocAt}{before the tables of contents}{after the tables of contents}

∖Configure{TocAt*}{before the tables of contents}{after the tables of contents}

These configurations can be used to execute code before and after ∖TocAt, respective ∖TocAt*.

∖Configure{tableofcontents*}{section types}

A non-empty parameter asks to implicitly introduce a ∖tableofcontents upon reaching the first sectioning command, if no ∖tableofcontents command is encountered earlier. The parameter assumes a colon-separated list of sectioning types to be included in the output of ∖tableofcontents. Starred variants of sectioning types should be referenced with the ‘like’ prefix.

An empty parameter cancels earlier requests for implicit calls to ∖tableofcontents (e.g., embedded within requests to package options 1, 2, 3, 4)

Example: 

\Configure{tableofcontents*}{part,likepart,% 
           section,likesection,subsection,likesubsection}

∖contentsname A LaTeX macro stating the title for a table of contents division.

7.11 Sectioning commands

∖Configure{unit-name}{start}{end}{before title}{after title}

This command determines the content to be inserted at the mentioned locations of the specified units.

Example: 

\Configure{chapter} 
{\HCode{<section class="chapter">}}  {\HCode{</section>}} 
{\HCode{<h2 class="chapterHead">}\chaptername ~\TitleMark 
\HCode{<br />}} 
{\HCode{</h2>}}

∖ConfigureMark{unit-name}{print section number}

Defines a macro ∖<<unit-name>>HMark to hold the given argument. Upon entering the unit, ∖TitleMark command gets the content of this macro.

Some built-in configurations of TeX4ht require an argument for the ∖<<unit-name>>HMark commands. For safety, these commands should always be followed by a, possiblely empty, argument. The argument should be a separator between the title mark and its content.

Example: 

\Configure{section} 
   {}{} 
   {\HCode{<h3>}\TitleMark\space}    {\HCode{</h3>}} 
\ConfigureMark{section}{\thesection}

∖NewSection∖unit {mark-for-toc}

This directive introduces a sectioning command ∖unit, which submits mark-for-toc to the tables of contents. 

\newcounter{c} 
\NewSection\X {\thec} 
\Configure{X} 
{}{} 
{\refstepcounter{c}\ifvmode\IgnorePar\fi\EndP\HCode{<h2>}\TitleMark\space} 
{\HCode{</h2>}} 
\ConfigureMark{X}{\arabic{c}}

∖Configure{toTocLink}{start link}{end link}

Each unit title contains a ∖Link{…}{…}…∖EndLink command. The first argument of ∖Link points to the first table of contents referencing the title. The second argument provides an anchor for references to the title (mainly from tables of contents).

The package option section+ requests the inclusion of the title within the anchor. Without this option, the link command resides between the title mark and its content.

The ∖Configure{toTocLink} command is provided for configuring the ∖Link and ∖EndLink instructions. In the default setting, when the sections+ option is not activated, the ∖Link command is altered to replace its first argument with an empty argument.

Example: 

\Configure{toTocLink} 
     {\Link} 
     {\ifx \TitleMark\sectionHMark 
        \Picture[\up]{haut.jpg align="right"}% 
        \EndLink 
        \TitleMark\space 
      \else \EndLink \fi 
     } 
  \def\up{[up]}

∖Configure{toToc}{unit type}{desired contents type (if empty, ‘unit type’ is assumed)}

You can also pass special values to unit type:

empty

stop adding entries of ‘unit type’ to toc

@

add entries of ‘unit type’ to toc

?

resume mode in effect before the last stop

Example: 

\Configure{toToc}{chapter}{likechapter}

Introduces chapter as likechapter into TOC.

Example that temporarily suppresses inclusion of chapter to TOC: 

\Configure{toToc}{}{chapter} 
\chapter{...} 
\Configure{toToc}{@}{chapter}

∖NoLink{section name}

Ignore option section+ for sections of type #1

∖Configure{NoSection}{before}{after}

Insertions around the parameters of sectioning commands, applied when the parameters are not used to create titles for the divisions.

7.12 Lists

7.13 Tables

7.14 Fonts

7.14.1 Basic font commands

Information about the fonts option and MathML issues. Example configuration: https://tex.stackexchange.com/a/416613/2891

7.15 Multi-lingual support

RTL support in the ODT output: https://tex.stackexchange.com/a/470434/2891.

7.15.1 Right-to-left text

There is a difference in the RTL support for HTML and ODT output formats. In HTML, RTL can be requested using:

∖Configure{LRdir}{ value for the dir attribute}

Example: 

\ConfigureEnv{arab} 
{\Configure{LRdir}{ dir="rtl"}} 
{\Configure{LRdir}{}}{}{}

This configuration sets the direction to rtl inside the arab environment and resets it after the environment end.

In the ODT output, different mechanism is used: 

\ConfigureEnv{arab}{\@rltrue}{\@rlfalse}{}{}

7.15.2 Unicode

Generally speaking, TeX4ht supports Unicode, but there are some issues to be aware of. Most complete support exists for LuaLaTeX, thanks to special Lua script which is automatically loaded during the compilation. No additional packages are necessary.

PDFLaTeX doesn’t support nativelly, but it is possible to emulate it using the inputenc and fontenc packages: 

\documentclass{article} 
\usepackage[utf8]{inputenc} 
\usepackage[T1]{fontenc} 
\begin{document} 
Unicode text 
\end{document}

XeLaTeX is an Unicode format, similarly to LuaLaTeX. The supporting mechanism for TeX4ht is different in this case and full Unicode range is not supported out of the box. By default, only most Latin based characters are supported. For other scripts, such as Greek or Cyrillic, two ways to enable support exists.

First option is to define new font family using fontspec \newfontfamily with the Script option. 

\newfontfamily\greekfont{Linux Libertine O}[Script=Greek]

The second option is to declare load support for a script in the custom config file using the \xeuniuseblock: 

\xeuniuseblock{Greek}

The block names are based on Unicode blocks.

It is also possible to declare all characters in an Unicode range. The command \xeuniregisterblockhex takes two hexadecimal parameters with Unicode range to be declared. 

\xeuniregisterblockhex{0100}{017F}

Individual character can be declared using the \xeuniregisterchar command: 

\xeuniregisterchar{"1F00}

In contrast to \xeuniregisterblockhex, it uses decimal numbers by default, so it is necessary to use the " character in front of a hexadecimal number.

Warning: It is possible to run into issues because of the way how XeLaTeX Unicode support works. Common problem is filename support, for example in included graphics. In general, it is better to avoid such filenames. If it is not possible, try to use the \detokenize command. 
  \includegraphics{\detokenize{háek.jpg}}

7.16 Colors

Information about the \color command: https://tex.stackexchange.com/a/195677/2891. Example of possible configuration for the \color command: https://tex.stackexchange.com/q/470179/2891.

Example of extracting color information to the CSS and custom color environment support: https://tex.stackexchange.com/a/422281/2891. Extracting of color information to the HTML attributes: https://tex.stackexchange.com/a/390151/2891.

7.17 Graphics and Pictures

7.17.1 Low level features

The next command imports external pictures, and the two commands that follow request pictorial representations for local content. The attributes, and the replacement parameters with their enclosing rectangular brackets, are optional.

∖Picture[replacement-for-textual-browser]{file-name attributes}

This command references the specified pictorial file. 

\Picture[picture description]{foo.png class="picture"}

∖Picture+[replacement-for-text-browsers]{file-name attributes} content ∖EndPicture

∖Picture*[replacement-for-text-browsers]{file-name attributes} content ∖EndPicture

These commands produce a picture for the provided content, store the outcome within a file of the specified name, and create a reference to the picture within the document. The starred variant should be used in the vertical mode, the variant with the plus sign can be used inside paragraphs.

Typical usage of these commands is for support of diagrams in the TeX code, such as TikZ or PSTricks.

The component [replacement-for-textual-browser] and the file name can be omitted. If no name is provided for the file, the system assigns a name of its own. 

\Picture+{ align="right"}% 
Text within a picture. 
\EndPicture

∖Configure{Picture}{Extension name pictures generated by DVI conversion, stored in ∖PictExt}

Default: 

\Configure{Picture}{.png}

The extension names of bitmap files of glyphs of htf fonts may be determined within a g-entry in the environment file tex4ht.env, or a g-flag of the tex4ht utility.

∖Configure{Picture-alt}{alt value for ∖Picture+{...} and ∖Picture*{...}}

∖Configure{Picture+}{before the dvi picture code}{after the dvi picture code}

∖Configure{Picture*}{before the dvi picture code}{after the dvi picture code}

Typically, the plus ‘+’ variant is introduced as an inline contribution into paragraphs, and the star ‘*’ variant as an independent block between paragraphs.

∖Configure{PictureAlt}{definitions before alt}{definitions after alt}

∖Configure{PictureAlt*+}{definitions before alt}{definitions after alt}

∖Configure{PictureAlt*+[]}{definitions before alt}{definitions after alt}

Apply to ∖Picture, ∖Picture*+, and ∖Picture*+[...]

∖Configure{IMG}{before file name}{between file name and alt}{close alt for ∖Picture without * or +}{close alt for ∖Picture with * and +}{right delimiter}

Example: 

\Configure{IMG} 
  {\ht:special{t4ht=<img src="}} 
  {\ht:special{t4ht=" alt="}} 
  {" } 
  {\ht:special{t4ht=" }} 
  {\ht:special{t4ht=/>}}

∖NextPictureFile{filename}

Requests a file name for the next created picture.

∖PictureFile

Records the filename of the most recent created picture.

7.17.2 Configurations for the Graphics package bundle

∖Configure{graphics}{before graphics}{after graphics}

Examples: 

\Configure{graphics} 
   {\Picture+[PIC]{ class="graphics"}} 
   {\EndPicture }

∖Configure{graphics*}{extension name}{insertion}

Allows to configure TeX4ht for graphics files named in the ∖includegraphics macro, based on the type of the files.

An empty insertion for the second argument cancels previous requests for the specified extension.

You can utilise the macros that contain information about the image, for example ∖Gin@base (file name), ∖Gin@ext (extension), ∖Gin@req@width (requested image width), ∖Gin@req@height (requested image height), ∖noBoundingBox (defined iff bounding box is unknown)

Example: 

\Configure{graphics*} 
{jpg} 
{\Picture[pict]{\csname Gin@base\endcsname.jpg}} 
 
\Configure{graphics*} 
{wmf} 
{\Needs{"convert \csname Gin@base\endcsname.wmf 
 \csname Gin@base\endcsname.gif"}% 
 \Picture[pict]{\csname Gin@base\endcsname.gif 
 width="\expandafter\the\csname Gin@req@width\endcsname" 
 height="\expandafter\the\csname Gin@req@height\endcsname"}% 
} 
 
\Configure{graphics*} 
{eps} 
{\openin15=\csname Gin@base\endcsname\PictExt\relax 
 \ifeof15 % test if the converted file already exists 
 \Needs{"convert \csname Gin@base\endcsname.eps 
 \csname Gin@base\endcsname\PictExt"}% 
 \fi 
 \closein15 
 \Picture[pict]{\csname Gin@base\endcsname\PictExt}% 
}

7.17.3 PDF support

∖Configure{PdfConvert}{}{}

∖Configure{Ghostscript}{name of the executable for GhostScript}

7.17.4 TikZ

Animations using Animate package: https://tex.stackexchange.com/a/404600/2891

Issues with drivers: https://tex.stackexchange.com/a/471460/2891.

7.17.5 Pstricks

7.18 Math

7.18.1 Default math handling

Default method for displaying math in the HTML output is a mixture of HTML elements and pictures. Pictures are used for display math and elements that are hard to display using HTML and CSS only, like fractions or square roots.

The downside of this method is that pictures may not align properly to the text baseline in inline math. Furthermore, by default, bitmap graphics is produced, which cannot be resized without losing of quality. To use vector SVG graphics instead, use the svg option. To prevent mixing of HTML, use the pic-m option. There are also similar options for requiring pictures for equations and various math environments. See the chapter TeX4ht Options.

7.18.2 MathML

MathML is a XML markup for the math encoding. It is supported in many aplications including OpenOffice Writer or Firefox web browser. In the HTML output, you can enable MathML using the mathml option. In other output formats, for example ODT, MathML is used by default.

The advantage over use of images is that the rendered math fits style of the surrounding text, and it can be resized without losing of quality.

Disadvantage is that it is not fully supported by some Web browsers fully, in particular by Google Chrome and other browsers that are derived from Chrome’s engine. Fortunatelly, the support can be added using JavaScript. Popular option is to use MathJax: 

$ make4ht filename.tex "mathml,mathjax"

MathML troupbleshooting The MathML code produced by TeX4ht may contain some issues. For example, one common issue may happen when the math contain unmatched delimiters: 

 Mail address: $\lparen$[email protected]$\rparen$

In such cases, the matml- may help.

The common_domfilters extension (see section 4.2.4 for more information about make4ht extensions), fixes some common MathML errors that cannot be easily fixed on the TeX level.

Additional information If you want to add original LaTeX source as an annotation to your MathML formulas, you can try a configuration from this answer.

7.18.3 MathJax

TeX4ht supports MathJax, library for math rendering in HTML documents. It supports two modes – LaTeX math and MathML.

The MathJax processing can be required using the mathjax option.

∖Configure{MathJaxSource}{MathJax URL}

The address of the MathJax script and its configuration string. Default value of this configuration is: 

\Configure{MathJaxSource} 
{https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml-full.js}

7.18.4 MathJax’s LaTeX mode

In the LaTeX math mode, TeX macros used in the math mode are preserved in the output HTML document. By default, inline and display math, as well as math environments should work. They are parsed and rendered by MathJax when the document is displayed by a web browser.

The downside of this mode is that commands unknown to MathJax must be configured in a special configuration for MathJax. See the how-to MathJax LaTeX mode for the examples on how to configure MathJax for custom commands, new environments, cross-references and other issues.

∖Configure{MathJaxConfig}{JavaScript object}

See the MathJax documentation for the possible configuration options.

∖Configure{MathJaxMacros}{path to file with macro definitions}

Load file with declarations of custom commands, so they can be recognized by MathJax. Note that you need to escape characters that could cause issues in the HTML post-processing, namely <, > and &. Use HTML entities instead.

∖VerbMath{environment name}

Redefine the given environment so it pass its contents verbatim to the output HTML file. You may need to configure MathJax to recognize it.

Table of contents issues Some math commands may cause issues when they are used in section titles in the MathJax mode. This can be fixed using the \fixmathjaxtoc command: 

\fixmathjaxtoc\int

7.18.5 MathJax’s MathML mode

Math is converted to MathML by TeX4ht, MathJax then renders it. Custom commands and cross-references work in this mode.

The MathML MathJax mode can be required using the mathml,mathjax option.

7.19 Bibliographies

7.20 Indexing

7.21 OpenDocument Format

The OpenDocument Format uses XML configuration file for document styling. To declare new document style, TeX4ht provides command \NewConfigureOO. The declared style then needs to be configured using command \ConfigureOO.

Usage of these commands can be illustrated by the following example: 

  \Configure{SectionTitleTest}{\ifvmode\IgnorePar\fi\EndP\HCode{<text:p text:style-name="section-title">}}{\HCode{</text:p>}} 
 
\NewConfigureOO{section-title} 
\ConfigureOO{section-title}{<style:style style:name="section-title" style:family="paragraph" style:class="text"> 
      <style:text-properties style:text-underline-style="solid" 
       style:text-underline-width="auto" 
       style:text-underline-color="font-color" 
       /> 
</style:style>}

Document style section-title had been declared in this example. The XML code for this style can be used without the \HCode command in \ConfigureOO.

The configuration SectionTitleTest inserts element <text:p>. The text:style-name corresponds to attribute style:name of style:style element in the style configuration.

7.21.1 Extra Configurations for OpenDocument Format

To use default ODF styles for sectioning commands, use the following configurations: 

\Configure{Heading-2}{Heading 1} 
\Configure{Heading-3}{Heading 2}