22

It seems to me that all (static) blogging frameworks, e.g. Jekyll and Hugo use Markdown as format for blog posts. But according to

Hartl’s Tenth Rule of Typesetting

Any sufficiently complicated typesetting system contains an ad hoc, informally specified, bug-ridden, slow implementation of half of LATEX. (http://manual.softcover.io/book/softcover_markdown)

Markdown (plus it's numerous extensions) is not a good format in comparison to LaTeX (especially when it comes to long-term stability). So are there any static blogging frameworks out there which use LaTeX as format for blog posts? Or are there any LaTeX to markdown converter which could be used in conjunction with common static blogging frameworks?

  • I hope everybody realises that Hartl's Tenth Rule is tongue-in-cheek (as is Greenspun's, and I daresay it's even further from being literally true). – leftaroundabout Sep 2 at 15:36
  • 1
    There is hackage.haskell.org/package/blatex that may be interesting. – Marijn Sep 2 at 16:13
17

You can utilize the fact that Markdown also supports HTML, so to support LaTeX in static site generators you just need to convert LaTeX to HTML. It is then necessary to extract just the contents of the <body> element and add an YAML header, just like in the Markdown file. make4ht can do this automatically.

In my planned blog, I have the following directory structure:

 texposts/
   .make4ht
   first_post/
     hello.tex
   second_post
     world.tex
 build/
 www/

There are three top level directories, texposts for LaTeX documents, build where HTML files to be processed are saved and www, which is populated by the static site generator.

The .make4ht file is a special configuration file for make4ht:

local outdir = os.getenv "kodymirus_root" or "out"
local domfilter = require "make4ht-domfilter"

-- remove the \maketitle environment from the HTML file, title will be inserted in the template
local domprocess = domfilter{function(dom)
  local maketitles = dom:query_selector(".maketitle")
  for _, el in ipairs(maketitles) do
    print "removing maketitle"
    el:remove_node()
  end
  return dom
end}

filter_settings "staticsite" {
  site_root = outdir, 
  map = {
    [".css$"] = "css/"
  },
  header = {
     layout="post",
     date = function(parameters)
       return os.date("!%Y-%m-%d %T", parameters.time)
     end
  }
}

Make:enable_extension "common_domfilters"
if mode=="draft" then
  Make:htlatex {}
elseif mode=="publish" then
  -- Make:htlatex {}
  Make:match("html$", domprocess)
  Make:enable_extension "tidy"
  Make:enable_extension "staticsite"
  Make:htlatex {}
else
  Make:htlatex {}
  Make:htlatex {}
  Make:htlatex {}
end

It is a Lua script which drives the conversion from LaTeX to HTML. There are few interesting things:

local outdir = os.getenv "kodymirus_root" or "out"

This reads an environmental variable set in my .bashrc that contains path to the build directory.

filter_settings "staticsite" {}

This contains settings for the staticsite extension:

  site_root = outdir, 

set the output directory

  map = {
    [".css$"] = "css/"
  },

move the generated files that match the regular expression to a specified directory. This example moves CSS files to the css subdirectory in the build dir.

  header = {}

In the header we can set additional fields for the YAML header.

elseif mode=="publish" then
  -- Make:htlatex {}
  Make:match("html$", domprocess)
  Make:enable_extension "tidy"
  Make:enable_extension "staticsite"
  Make:htlatex {}

make4ht supports so called modes. These modes can be selected on the command line using the -m option. By default, this configuration file will create a standalone HTML file. Only when the post is done, you can execute the publish mode, which enables the staticsite extension and publishes the document to the build dir.

To publish the document execute the following command in the texposts/first directory:

 make4ht -um publish hello.tex

Regarding math, tex4ht supports several methods for the conversion. By default, it uses ordinary HTML text + images for more complex cases, like display math etc. The default image format is PNG. To request SVG images, it is possible to pass special option to tex4ht:

 make4ht -um publish hello.tex "svg"

Math images are not really good solution, it is used by default mainly for compatibility. Better solutions is to use either MathML using the "mathml" option or raw LaTeX code and render it using MathJax. The raw LaTeX can be requested using the "mathjax" option. Note that MathJax itself must be included in the static site template.

Here is an example TeX file:

\documentclass{article}
\title{Blogging with \LaTeX}
\author{Michal}
\begin{document}

\maketitle

\tableofcontents

\section{Introduction}

\textit{příliš žluťoučký}

\printbibliography

\end{document}

And this is the generated document:

---
layout: 'post'
updated: 1524600200
styles:
- '2018-04-18-blogging-with-latex.css'
meta:
- content: 'HTML Tidy for HTML5 for Linux version 5.4.0'
  name: 'generator'
- charset: 'utf-8'
- content: 'TeX4ht (http://www.tug.org/tex4ht/)'
  name: 'generator'
- content: 'width=device-width,initial-scale=1'
  name: 'viewport'
- content: '2018-04-18-blogging-with-latex.tex'
  name: 'src'
title: 'Blogging with LaTeX'
date: '2018-04-18 20:31:14'
time: 1524083474
---

<h3 class='likesectionHead'><a id='x1-1000'></a>Contents</h3>
<div class='tableofcontents'><span class='sectionToc'>1 <a id='QQ2-1-2' href='#x1-20001'>Introduction</a></span></div>

<!--  l. 17  -->
<p class='noindent'></p>
<h3 class='sectionHead'><span class='titlemark'>1</span> <a id='x1-20001'></a>Introduction</h3>
<!--  l. 19  -->
<p class='noindent'><span class='rm-lmri-10'>příliš žluťoučký</span></p>
  • Would math-mode contents in LaTeX be rendered as images? If so, that's a bit unfortunate for accessibility and copy-pastability. – ComFreek Sep 2 at 10:07
  • 1
    @ComFreek math can be rendered as images, either png or svg, MathML, or raw LaTeX math for MathJax. – michal.h21 Sep 2 at 10:26
5

What you want to do is, in the abstract, no problem at all, but you need a bit of background to understand the ecosystem so you can search for and choose the correct tools.

Background

There's a huge variety of static site generation tools out there. The core of any static site generator is to read files and either copy them to the output directory holding the generated site or process them in some way to generate new files in the output directory.

Upon this basic framework are built additional features such as using different kinds of transformation tools (e.g., Markdown to HTML, LaTeX to HTML, image resizing, etc.) combining information from multiple sources (e.g., the YAML header and the marked-up content of a source file), and producing multiple output files (e.g., a blog "top page" with the title and first paragraph of multiple blog posts, each from the individual file for that post).

Any of the above operations may be either integrated into the core code or be added as "plugins" that you can add as options to the base system. Even the functions integrated into the core code, if they're moderately sophisticated (such as Markdown to HTML rendering or image resizing) will generally not be done by code writting by the author of the static site generator but will be libraries written by others that he calls.

What You Need

So what you need is a static site generation tool that supports two things, either built-in or with plugins for that tool:

  1. Handy facilities for blog sites, such as being able to set titles, authors, dates and tags for blog posts, being able to generate the top page, indexes by date and so on (as well as the blog posts pages themselves), and perhaps some support for commenting or other features you're interested in.

  2. A rendering engine that will read LaTeX and render HTML from it.

For the latter, the two obvious options are to use Pandoc, if that will handle the LaTeX code you're writing, or to actually use TeX itself to do the rendering if that's necessary.

Many static site generators provide support for Pandoc, though often they're designed to use LaTeX-syntax math embedded in Markdown and may need some convincing to render whole LaTeX files.

Most static site generators can probably be convinced (possibly with a small amount of programming) to run external programs, such as TeX, and use the output they generate. (After all, that's already pretty much the processing chain they're using anyway: read file, run some code on it or part of it, and write the resulting output somewhere.)

Unfortunately, I'm not familiar with more than the names of the popular JS/Ruby/etc. static site generators (I use Hakyll for my own sites), so I can't point you to the exact one that comes closest to doing what you need. But I hope that this background information gives you what you need to do a successful search for something that will work for you.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.