Rendering LaTeX in Hakyll

Table of Contents

• 1 What is Hakyll?
• 2 Rendering Markdown in Hakyll
  • 2.1 Compiling to HTML
• 3 Rendering LaTeX in Hakyll
  • 3.1 Special Characters
  • 3.2 Compiling to HTML

1 What is Hakyll?

Hakyll is a Haskell library for generating static sites, mostly aimed at small-to-medium sites and personal blogs. It is written in a very configurable way and uses an xmonad-like DSL for configuration.

When I first started putting together this site, I wanted more flexibility for rendering the Markdown posts in HTML. For my particular needs, LaTeX offered everything I wanted to show here. Now, this site as you see it uses Markdown and Hakyll-specific formatting within LaTeX.

2 Rendering Markdown in Hakyll

As Hakyll is integrated with pandoc, it is capable of rendering Markdown with proper formatting in HTML. For example, to produce header text ¹ we can simply use:

# Header Text
## Subheader Text

Similarly, we can produce code blocks with syntax highlighting:

```haskell
main :: IO ()
main = putStrLn "Hello, world!"
```

which produces:

main :: IO ()
main = putStrLn "Hello, world!"

2.1 Compiling to HTML

Using Markdown files on a Hakyll site is as simple as placing them in a directory, say posts, and then compiling them to HTML like so:

match "posts/*.md" $ do
    route $ setExtension "html"
    compile $ pandocCompiler
        >>= relativizeUrls

3 Rendering LaTeX in Hakyll

While TeX files are already supported by Hakyll as it uses pandoc, the compilation process is a bit different than the case of Markdown. We can use support files with our LaTeX, like class or style files², however, in its simplest form we can start by using a TeX file like so:

\title{Some Title}
\section{Some Section}
Some text.

3.1 Special Characters

As we are using LaTeX, that provides us with a simple way of defining mathematical expressions, among other things. Next, we show some examples of how to use native LaTeX commands in Hakyll:

\newtheorem{theorem}{Theorem}
\newtheorem{corollary}[theorem]{Corollary}
\newtheorem{lemma}[theorem]{Lemma}
\theoremstyle{definition}
\newtheorem{definition}[theorem]{Definition}
\theoremstyle{remark}
\newtheorem{remark}{Remark}

which can be used like so:

\begin{definition}[right-angled triangles]
    A \emph{right-angled triangle} is a triangle whose sides of length~\(a\), \(b\) and~\(c\), in some permutation of order, satisfies \(a^2+b^2=c^2\).
\end{definition}

which produces:

Definition 1 (right-angled triangles). A right-angled triangle is a triangle whose sides of length \(a\), \(b\) and \(c\), in some permutation of order, satisfies \(a^2+b^2=c^2\).

Similarly:

\begin{definition}[Prime numbers]
    A \emph{prime number} is a natural number greater than 1 that has no positive divisors other than 1 and itself.
\end{definition}

\begin{lemma}[Infinitude of primes]
    There are infinitely many prime numbers.
\end{lemma}

\begin{proof}
    Suppose there were only finitely many prime numbers. List them as \(p_1, p_2, \ldots, p_n\). Consider the number \(P = p_1p_2\ldots p_n + 1\). This number \(P\) is not divisible by any of our listed primes, since it leaves a remainder of 1 when divided by any of them. Therefore, \(P\) is either prime or has a prime divisor which is not on our list. This contradicts our assumption that \(p_1, p_2, \ldots, p_n\) were all of the primes. Therefore, there must be infinitely many primes.
\end{proof}

produces:

Definition 2 (Prime numbers). A prime number is a natural number greater than 1 that has no positive divisors other than 1 and itself.

Lemma 3 (Infinitude of primes). There are infinitely many prime numbers.

Proof. Suppose there were only finitely many prime numbers. List them as \(p_1, p_2, \ldots, p_n\). Consider the number \(P = p_1p_2\ldots p_n + 1\). This number \(P\) is not divisible by any of our listed primes, since it leaves a remainder of 1 when divided by any of them. Therefore, \(P\) is either prime or has a prime divisor which is not on our list. This contradicts our assumption that \(p_1, p_2, \ldots, p_n\) were all of the primes. Therefore, there must be infinitely many primes. ◻

3.2 Compiling to HTML

This is where we need to handle things a bit differently. Using Hakyll’s pandoc integration, we can compile our TeX files to HTML like so:

match "*/*.tex" $ do
    route   $ constRoute "*/index.html"
    compile $ getResourceString
        >>= withItemBody (unixFilter "pandoc" ["-f", "latex", "-t", "html5","--mathjax"])
        >>= relativizeUrls