LaTeX to HTML with lwarp

1 The problem and how to solve it

As mathematicians, we are accustomed to writing papers, lecture notes and exercise sheets in LaTeX and distributing the resulting PDF files. However, PDF is not a good option from the accessibility point of view: it does not play well with screen-readers, for example, and there is now a legal requirement to provide alternatives. To a first approximation, a good alternative is HTML along with MathJax to render the mathematics so the question is how to produce this.

One possibility is to start again and write from scratch in bookdown. However, if you already have a large amount of LaTeX material, there is another, perhaps, easier path: the lwarp package.

The lwarp package produces an html version of your document with accessibly rendered mathematics while allowing you to use macros, theorem environments, tikz pictures and all the other bells and whistles you are used to. This note tells you how to get started with lwarp.

2 Long story short

Starting with file.tex, add the following snippet right after the \documentclass line:

\usepackage[mathjax]{lwarp}

Run pdflatex on file.tex as usual enough times to resolve references.

Now, in a terminal, invoke this incantation:

lwarpmk html

If everything goes to plan, you should now find the your working directory contains file.html and also a css file called lwarp.css. Put both of these where you usually put your web-pages and you are good to go.

Read on if you have pictures, macros or long documents that need to be spread over many web-pages.

3 Carrying on

lwarp has an extensive manual (over 1000 pages but you only need sections 5 and 6 to get started). Here we collect some tips for rapid deployment.

3.1 Graphics

How your pictures and diagrams work will depend on their format:

• 1. Graphics created on board with LaTeX picture or tikz will Just Work. Simply run the following in a terminal as a final step:

  lwarpmk limages
  

• 2. Graphics in pdf or eps format need a conversion step first:

  lwarpmk epstopdf *.eps   # only for .eps files
  lwarpmk pdftosvg *.pdf
  

For more details, see section 8 of the manual.

3.2 Maths macros

If you are like me, you use a lot of LaTeX macros to help with writing mathematics. MathJax will not understand these out of the box but can be taught about them.

Given a list of macros in the preamble like this:

\newcommand{\R}{\mathbb{R}}
\newcommand{\C}{\mathbb{C}}
\newcommand{\Z}{\mathbb{Z}}

you need to add a second block for MathJax:

\begin{warpHTML}
\CustomizeMathJax{\newcommand{\R}{\mathbb{R}}}
\CustomizeMathJax{\newcommand{\C}{\mathbb{C}}}
\CustomizeMathJax{\newcommand{\Z}{\mathbb{Z}}}
\end{warpHTML}

If you have a lot of macros, this could be tedious but your text editor should be able to help you.

3.3 Lecture notes and friends

You now know enough to make exercise sheets but what about lecture notes and other long documents that don’t fit on a single web-page? You can get lwarp to split your document into sections, each getting its own page. To achieve this, replace the \usepackage{lwarp} line with something like::

\usepackage[
   HomeHTMLFilename=index,     % Filename of the homepage.
   HTMLFilename={node-},       % Filename prefix of other pages.
   mathjax                     % Use MathJax to display math.
]{lwarp}

and then customise with:

\boolfalse{FileSectionNames}     % If false, numbers the files.
\setcounter{tocdepth}{2}         % Include subsections in the \TOC.
\setcounter{secnumdepth}{3}      % Number down to subsections.
\setcounter{FileDepth}{1}        % Split \HTML\ files at sections
\booltrue{CombineHigherDepths} % Combine parts/chapters/sections
\setcounter{SideTOCDepth}{1}     % Include subsections in the side\TOC
\HTMLTitle{MA20216: Algebra 2A} % Overrides \title for the web page.
\HTMLAuthor{Fran Burstall}       % Sets the HTML meta author tag.
\HTMLLanguage{en-UK}             % Sets the HTML meta language.
\HTMLDescription{Lecture notes for MA2016: Algebra 2A}% Sets the HTML meta description.

Now lwarpmk html will generate index.html, lots of files of the form node-1.html containing the sections and a table of contents for navigation.

See the manual for more details.

4 More maths tips

Sometimes lwarp or MathJax needs a little help to do what you want. Here are some examples I have found:

• 1. If MathJax does not understand a LaTeX construct it will display the offending item in red. Often a simple replacement is all that is needed:

  • (a) Replace \dag with \dagger.

  • (b) Replace \,, with \, ,.

• 2. Help is needed with tikzcd environments: wrap them in a {\displaymathother ...} group. Example:

  {\displaymathother
    \begin{equation*}
       \begin{tikzcd} V \arrow{r}{\phi}& W \\
       \F^{n}\arrow{r}{\phi_A} \arrow{u}{\phi_{\cB}} &\F^m
       \arrow{u}[right]{\phi_{\cB'}}
       \end{tikzcd}
    \end{equation*}}
  

• 3. You can give different content for the pdf and html versions by wrapping things in warpprint or warpHTML environments. For example, lwarp does not support the amsmath package’s \intertext construct very well. See Figure 1 for the work-around.

  Warning: the \end{warp...} part must be placed at the start of the line for this to work.

\begin{warpprint}
  \begin{align*}
    \ip{\phi^{*}(v),w}&=\ip{v,\phi(w)}\\
    \intertext{or, equivalently, by conjugate symmetry,}
    \ip{w,\phi^{*}(v)}&=\ip{\phi(w),v}.
  \end{align*}
\end{warpprint}
\begin{warpHTML}
  \begin{equation*}
    \ip{\phi^{*}(v),w}=\ip{v,\phi(w)}\\
  \end{equation*}
  or, equivalently, by conjugate symmetry,
  \begin{equation*}
    \ip{w,\phi^{*}(v)}=\ip{\phi(w),v}.
  \end{equation*}
\end{warpHTML}

5 Advanced configuration

5.1 Styling

lwarp provides bare-bones styling via lwarp.css. You can provide your own css and load it by putting

\CSSFilename{my-classy-style.css}

in the preamble.

If you do this, it is a good idea to start from lwarp.css by putting

@import url("lwarp.css");

at the top of your own style sheet. See section 6 for examples.

5.2 Javascript

Again, lwarp gives bare-bones navigation for multi-page web-sites. If you want to improve things with javascript, you can inject some into the document with these steps:

• 1. Copy the auto-generated file lwarp_mathjax.txt to something like my_mathjax.txt.

• 2. At the end of my_mathjax.txt, put something like:

     <script type="text/javascript"
     src="my-clever-nav.js">
     </script>
  

• 3. Load it by adding

  \MathJaxFilename{my_mathjax.txt}
  

  to the preamble.

See section 6 for an example.

6 Resources

Here are some examples: