make4ht

make4ht provides built-in modes to change the compilation behavior:

• draft mode: Invokes ext{LaTeX} only once instead of the default three times. This is useful for quick iterations where cross-references are not critical. Use -um draft.
• clean mode: Executes the Make:clean() command to remove all generated and temporary files from the current directory. No compilation occurs in this mode. Use -m clean.

# Fast draft compilation
$ make4ht -um draft filename.tex

# Clean up generated files (using -a info to see what was removed)
$ make4ht -m clean -a info filename.tex

Build files are Lua scripts that allow you to adjust the build process, such as requesting external applications (BibTeX, Makeindex), passing options, or post-processing files.

make4ht automatically looks for a file named filename.mk4 (where filename is your input file). You can specify a custom build file using the -e or --build-file flag.

-- Sample filename.mk4
Make:htlatex()
Make:match("html$", "tidy -m -xml -utf8 -q -i ${filename}")

When working with input files, be aware of the following constraints:

• Spaces: tex4ht cannot handle filenames containing spaces. make4ht automatically mitigates this by replacing spaces in input filenames with underscores. Consequently, generated XML filenames will also use underscores instead of spaces.
• Non-ASCII characters: If you are generating odt output, avoid using accented or non-ASCII characters in filenames, as the odt output format does not support them.

The mode variable contains the value of the --mode command line option. You can use it to execute different build sequences conditionally (e.g., a faster 'draft' mode vs. a full production mode).

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

Before installing make4ht, ensure your system meets the following requirements:

• A TeX distribution (e.g., TeX Live or MikTeX) that includes:
  • tex4ht system
  • Noto fonts
  • texlua script
• Pandoc
• latexmk (usually included with TeX distributions)

You can specify where generated files are placed using the -d or --output-dir option. make4ht will automatically create the directory if it does not exist. Paths can be relative or absolute.

To ensure proper directory structure preservation (especially for images), use the make4ht output directory routines rather than passing arguments directly to htlatex style strings.

Recommended usage: make4ht -d <dir> <filename>

Advanced separation: You can separate auxiliary files from final output files using the -B or --build-dir option. This puts .aux, .4tc, and other temporary files in the build directory, while keeping .html and .css in the output directory.

# Create output in a specific directory
$ make4ht -d outputdir filename.tex

# Separate auxiliary files into a 'build' directory
$ make4ht -B build -d outputdir filename.tex

By default, make4ht is quiet, showing only status, warnings, and errors. If a compilation fails, you can increase the verbosity using the --loglevel or -a option. Useful levels for debugging include info and debug.

$ make4ht -a debug faulty.tex

To perform a basic conversion of a LaTeX file to HTML, run make4ht followed by the filename. If successful, it will produce a file named filename.html.

$ make4ht filename.tex

To install make4ht on Unix-like systems, use the provided Makefile. By default, it installs to /usr/local/bin. You can specify a custom installation directory using the BIN_DIR variable.

make
make install

# To install to a custom directory:
make install BIN_DIR=~/.local/bin/

You can globally modify build settings using a make4ht configuration file. This allows you to declare new commands, load default filters, specify build sequences, and enable/disable extensions globally.

File Locations:

• $HOME/.config/make4ht/config.lua (Global)
• .make4ht in the current or parent directory (Project-specific, up to $HOME).

Available Commands in Config Files:

• Make:enable_extension(name): Requires a specific extension.
• Make:disable_extension(name): Disables a specific extension.
• Make:add(name, command): Adds a new command.
• settings_add { ... }: Adds global settings.

Make:add("biber", "biber ${input}")
Make:enable_extension "common_domfilters"
settings_add {
  tex4ht_sty_par ="=mathml"
}

You can modify the build process without a build file by using extensions. Extensions are enabled or disabled by appending +EXTENSION or -EXTENSION to the output format name using the -f flag.

Example: To use the tidy extension with html5 format: $ make4ht -f html5+tidy filename.tex

Note: In xhtml and html5 formats, the common_domfilters extension is enabled by default. To disable it, use html5-common_domfilters.

$ make4ht -f html5+tidy filename.tex
$ make4ht -f html5-common_domfilters filename.tex

On Windows, you can install make4ht by creating a batch file and placing it in a directory that is included in your system PATH. The batch file should invoke texlua with the full path to the make4ht script and pass through all arguments using %*.

texlua "C:\full\path\to\make4ht" %*