Enable more advanced math rendering by default

[dhimmel]

The current default math used in our pandoc build command is severely limited: see the "TeX math in HTML" section of the pandoc demos. Pandoc has support for several more advanced methods for math rendering in HTML.

The question is which one to choose? I've seen MathJax used before in scholarly publishing. However, KaTex is faster to render. There are also several more options.

@slochower did you look into the math options at all for b03e1c3?

[dhimmel]

--mathjax worked for @zietzm in zietzm/Vagelos2017@8a3a633. See https://zietzm.github.io/Vagelos2017/ (versioned). The conversion to PDF via wkhtmltopdf was okay, not great: manuscript.pdf.

[slochower]

No, I didn't really look at options, but I'm using the --katex option myself and it's okay but not great.

HTML:

This is on Safari 10.1.2 and I've changed to HTML5 output because it looks better on my phone. I can't tell a difference between the HTML and HTML5 output on a desktop browser.

PDF:

This is using the built-in Safari PDF renderer.

My impression was that I'd probably just produce a PDF through LaTeX when the time came, because I often rely on LaTeX macros that aren't available as javascript libraries, for example, using mhchem to render chemistry.

[slochower]

(Digression from the main topic, but I see a table rendering bug in the manuscript PDF you linked. It looks like the header gets reproduced across page breaks -- nice -- but overwrites a row in the process. We may want to report upstream.)

[dhimmel]

One benefit of MathJax is that you can right-click the equation to show the MathML or TeX Commands. Since Manubot manuscripts are entirely open source (you can always get back to the source TeX), this is not essential (but is still nice). What really is annoying is when you can't get the TeX out of an online equation and hence have no way to copy it.

I've changed to HTML5 output because it looks better on my phone.

Is Manubot Rootstock not using the HTML5 output?!?! Want to fix this with a PR?

Nice to see your in-progress manuscripts

• https://github.com/slochower/nonequilibrium-barrier
• https://slochower.github.io/synthetic-motor-literature

We may want to report upstream

See wkhtmltopdf/wkhtmltopdf#3557. I wonder if we could implement the td, tr { page-break-inside: avoid; } fix.

[slochower]

right-click the equation to show the MathML or TeX Commands

Fair point. I've always enjoyed that on Wikipedia, for example.

Is Manubot Rootstock not using the HTML5 output?!?! Want to fix this with a PR?

By default, build.sh uses html as the format.
https://github.com/greenelab/manubot-rootstock/blob/03de82178edfc62f43feb57add42739c39b3b7e0/build/build.sh#L31
I'm actually not sure what the difference is between --html and --html5 (I couldn't find clear guidance in the pandoc documentation) and how it plays out through the CSS that's applied, but the --html5 output zooms to an easily readable font size on my phone and the --html does not. I'll submit the single line change in a PR and hope there aren't any unintended consequences.

I wonder if we could implement the td, tr { page-break-inside: avoid; } fix.

Not sure about that, but worth a shot.

[dhimmel]

This github code embed feature you triggered is rad!

As a screenshot:

As quoted text:

By default, build.sh uses html as the format.
https://github.com/greenelab/manubot-rootstock/blob/03de82178edfc62f43feb57add42739c39b3b7e0/build/build.sh#L31
I'm actually not sure what the difference is between --html and --html5 (I couldn't find clear guidance in

Never knew this existed.

[slochower]

This github code embed feature you triggered is rad!

Just navigate to the file, hit y for current commit URL (not sure if necessary), and click three dots to get permalink.

[dhimmel]

I often rely on LaTeX macros that aren't available as javascript libraries, for example, using mhchem to render chemistry.

It looks like you may be able to extend MathJax to support mhchem. However, KaTex does not support mhchem... yet.

Are there other macros that you have in mind specifically? If the overhead for enabling these extensions is low, we may want to consider enabling some by default. I imagine they could provide compelling incentives to use the Manubot. My only worry is that they will increase the HTML lockin, when the longterm best option may be to create JATS XML (see #51) as that may become the standard for scholarly content and the best route to a nice frontend.

[slochower]

It looks like you may be able to extend MathJax to support mhchem. However, KaTex does not support mhchem... yet.

Exactly. I saw that thread but I haven't had time to play around with it yet.

Are there other macros that you have in mind specifically?

In my latest stuff, I think I used mhchem, siunitx, and some packages for long tables in the SI, I think it was booktabs and threeparttable. I can double check later on (see below).

the longterm best option may be to create JATS XML (see #51)

Neat! I didn't know about that. One pain point right now (for me) is not being able to see the figures while writing. One of my use cases at the moment is more of a notebook than a manuscript (with the goal that I could turn the notebook into an article without much trouble). It's much easier to write about images when they are rendered; I've been using vscode to write. Does Texture render URL images in Markdown by any chance?

Edit: the full preamble for a scientific manuscript in LaTeX with all the macros I used, for reference.

\documentclass[12pt]{extarticle}
\usepackage[english]{babel}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{csquotes}
\usepackage{siunitx}           
\usepackage{helvet}            % to make the document Helvetica
\renewcommand{\familydefault}{\sfdefault}
\usepackage[EULERGREEK]{sansmath} % to get Greek units to behave
\sansmath
\usepackage{amsmath, amsfonts} % math
\usepackage{bm}
\usepackage[version=4]{mhchem} % for formatting magnesium and ATP
\usepackage[varioref=false]{chemstyle}         % symbols
\usepackage{graphicx}          % images
\usepackage{hyperref}          % for TOC
\usepackage[usenames, dvipsnames]{xcolor}
\definecolor{purple}{RGB}{112,48,160}
\usepackage{booktabs, multirow, threeparttable} % For the tables
\usepackage{etoolbox}
\robustify\tnote               % for tnote with siunitx
\usepackage{esdiff}            % derivatives
\usepackage{comment}           % to hide stuff in drafts
\usepackage{setspace}
% \usepackage{lineno}
% \setstretch{1.2}
\setstretch{2}
% Comment below for easier editing on small screens (makes document narrower)
\usepackage[left=0.4in, right=0.4in, top=1in, bottom=1in, headheight=13.6pt]{geometry}
\usepackage[backend=biber, style=nature, doi=false, isbn=false, url=false]{biblatex}

[dhimmel]

It's a difficult decision between mathjax and katex. I'm thinking we should go with mathjax because it:

• supports more of latex math (not sure whether katex is fully caught up at the moment, but has had more limited support in the past)
• enables copying the raw TeX
• due to its maturity has a nice extensions, such as mhchem

See also https://www.bersling.com/2016/05/10/displaying-math-on-the-web/. If MathJax becomes too slow, users can always swap it out for katex.

Neat! I didn't know about that. One pain point right now (for me) is not being able to see the figures while writing.

Can you preview the markdown in your text editor? vscode claims to support side-by-side markdown preview.

Does Texture render URL images in Markdown by any chance?

Texture only reads JATS XML (not markdown). We'd be converting markdown to JATS in pandoc and then feeding that to Texture... but we'd still be writing in markdown.

[agitter]

One pain point right now (for me) is not being able to see the figures while writing.

The Atom editor also shows local images in the side-by-side Markdown preview. It doesn't resize them according to the {height="13px"} annotation though so the icons in the author list are huge.