org-latex-impatient

org-latex-impatient provides instant preview of LaTeX snippets via MathJax outputed SVG. Unlike webkit-katex-render, this does not need xwidget support. Currently org-mode and its derived modes, e.g. org-journal, are fully supported. Markdown-mode support is new, but seems decent as long as you have correct highlight for math fragments. Support for latex-mode is experimental and under construction (no support for custom \newcommand yet).

Dependencies

• Names
• MathJax-node
• MathJax-node-cli
• posframe

Installation

You can install MathJax-node-cli via npm:

npm install mathjax-node-cli

You need to set org-latex-impatient-tex2svg-bin to the location of the executable tex2svg.

Usage

(use-package org-latex-impatient
  :defer t
  :hook (org-mode . org-latex-impatient-mode)
  :init
  (setq org-latex-impatient-tex2svg-bin
        ;; location of tex2svg executable
        "~/node_modules/mathjax-node-cli/bin/tex2svg"))

Or just enable minor mode org-latex-impatient-mode manually when it is needed.

Customization

• org-latex-impatient-delay: change the number of seconds to wait before re-compilation after Emacs is idle. Default to be 0.1.
• org-latex-impatient-tex2svg-bin: set the location of tex2svg executable.
• org-latex-impatient-border-color: border color.
• org-latex-impatient-border-width: border width (an integer), 0 will disable border.
• org-latex-impatient-scale: set the scale of the preview. Due to limitations in the way Emacs handles SVG pictures, it is implemented by manipulating SVG directly.
• org-latex-impatient-posframe-position: at which point shall the posframe be positioned. Can take two choices, point at the current point, or tex-end at the end of the LaTeX snippet. See the next option for detail.
• org-latex-impatient-posframe-position-handler: set the posframe position handler. Default value is org-latex-impatient-poshandler, which uses end point of current LaTeX fragment for inline math, and centering right below the end point otherwise. You might want to use posframe-poshandler-point-bottom-left-corner for showing it using the point specified by org-latex-impatient-posframe-position, or posframe-poshandler-point-window-center for a position centering right below the end point. Check the documentation of posframe-show for other options.
• org-latex-impatient-user-latex-definitions: custom LaTeX definitions used in the preview. Should be a list of strings. Default: '("\\newcommand{\\ensuremath}[1]{#1}" "\\renewcommand{\\usepackage}[2][]{}"), which handles \ensuremath correctly for MathJax. In general, it is recommended to add your custom LaTeX command via the following:

  #+LATEX_HEADER: \newcommand{\someNewCommand}{Some Definition}
      

• org-latex-impatient-inhibit-envs: a list of LaTeX environments. If a LaTeX fragment contains one of them, preview will be disabled. This exists to avoid previewing environments unsupported by MathJax, e.g. tikzpicture.
• org-latex-impatient-inhibit-commands: a list of LaTeX commands. If a LaTeX fragment contains one of them, preview will be disabled. This exists to avoid previewing commands unsupported by MathJax, e.g. \tikz

FAQ

TeX parse error: Undefined control sequence

There are many LaTeX commands that are not supported by MathJax, therefore also unsupported by org-latex-impatient-mode. Mostly, such commands are not important for a preview.

If this is the case, you can ignore it by override its definition with a place holder in org-latex-impatient-user-definitions. For example, if you are using beamer, you would be calling \setbeamertemplate in the setup file or header. You will see errors like “TeX parse error: Undefined control sequence \setbeamercolor”. This is a command that receives two parameters, so you can run

(add-to-list 'org-latex-impatient-user-latex-definitions "\\renewcommand{\\setbeamertemplate}[2]{}" t)

It is recommended to override top level commands for obvious reasons. Repeat this process for every such command.

Since most LaTeX packages are not relevant in math preview, we assume that all package usage are not necessary in producing a preview, and override the \usepackage call in the header. If this prevents you from using certain commands defined by an external package, add this in the *front* of ~org-latex-impatient-user-latex-definitions~ like the following:

Known Issue

• Some SVG files get cropped slightly more than it should. This happens with librsvg 2.45 or below. It can also happen on Emacs 28, problem introduced in commit 8f42b94f and fixed in b42481e2. (bug #44065)
• Some report problem of showing scaled SVG on Mac OSX. A workaround is to avoid customization of org-latex-impatient-scale.
• For latex-mode, currently we do not support customized newcommand or renewcommand. One workaround is to manually add the definitions to org-latex-impatient-user-latex-definitions.

Future Plans

• Add support for latex-mode. There is experimental support, but it does not support any customized commands. Such a support would require either parsing tex file, or actually compiling a tex file with latex/pdflatex/xelatex.
• Use latex/pdflatex/xelatex for image generation instead of mathjax. Some progress made, but needs refactoring to make things consistent.
• Support for scaling in different Emacs versions.

License

This piece work is licensed under GPLv3.