Author/s: Ramiro Checa-Garcia
Language: en | Translations:
computing
sourcehut

General information

There are reasonable limitations in SourceHut pages regarding loading external content. One of the consequences is that traditional methods to include equations using MathJax or KaTeX is not posible unless you decide to include these packages in your website rather than load css and javascript files stored in CDN servers.

Alternatives

There are still other reasonable options that can be easily used in SourceHut like asciimath, however my requirements is to be as close as possible to LaTeX which is the syntax I know well to type maths. So I arrived to another option named jqmath which actually works well and it's fast. It only need small a javascript open-source code that can be included easily. Actually, I finally have chosen the jqmath-vanilla that doesn't need the jquery javascript and it's self included.

How to include

In my case, this blog is created using the open-source (gnu-affero v3 license) Pelican which a custom theme/template that I named narigudo. So only it is need to add two archives of jqmath-vanilla to the static files of the theme, and 3 lines to my base.html template:

 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=UnifrakturMaguntia">
 <link rel="stylesheet" href="/theme/css/jqmath-0.4.3.css">
 <script src="/theme/js/jqmath-vanilla.js"></script>

Note that if you prefer the original jqmath you can simply add:

<link rel="stylesheet" href="/theme/mathscribe/jqmath-0.4.3.css">
<script src="/theme/mathscribe/jquery-1.4.3.min.js"></script>
<script src="/theme/mathscribe/jqmath-etc-0.4.6.min.js" charset="utf-8"></script>

Some tricks

Yes, I know, jqMath uses a TeX-like syntax, with MathML semantics, but it is not able to reproduce all the features of LaTeX, which means that for some cases you need to learn a new syntax for the equations:

This is a short list of features:

$, or \( and \), to delimit inline mathematics
$$, or \[ and \], to delimit block or display mathematics
^ for superscript
_ for subscript
{ and } for grouping
 for overscript
 for underscript
\ or ` to quote the next character (turning off its special meaning)
      alsostart a macro or multi-letter name, or make a name non-italic
\bo, \it, or \bi for a bold, italic, or bold-italic variable
\sc or \fr for a script or Fraktur letter
\ov for an overbar
\table for a matrix, table, or simply tabular alignment - separate entries with , and rows with ;
\text  for plain text  - specify the text inside quote
(you can also use html instead of text for html code but only works inside a trusted source)
spaces, tabs and newlines are ignored - jqMath formats the mathematics
you can use \$ for a real $, or \\ for a \ if necessary.

But, $\alpha$ for example will not work, you need to introduce as an Unicode character. If you are, like me, a LaTeX user for many years this can be an issue. A nice solution that works for me is to use just the TeX mode in Emacs to introduce greck characters, infinity etc...

For further example of this syntax you may check jqMath test page, and look to the source code of this webpage to see how each case is introduced (also you may do the same with pages in like the Energy Budget