dialoa / imagify

Pandoc/Quarto filter to convert selected LaTeX elements to images in other output formats

Imagify - Pandoc/Quarto filter to convert selected LaTeX into images

Lua filter to convert some or all LaTeX code in a document into images and to use .tex/.tikz files as image sources.

Copyright 2021-2023 Philosophie.ch under MIT License, see LICENSE file for details.

Maintained by Julien Dutant.

Overview

Imagify turns selected LaTeX elements into images in non-LaTeX/PDF output. This is useful for web output if you use MathJAX but it doesn't handle all of your LaTeX code.

It also allows you to use .tex or .tikz elements as image source files, which is useful to create cross-referenceable figures with Pandoc-crossref or Quarto without having to convert your LaTeX/TikZ code into images first.

Imagify tries to match your document's LaTeX output settings (fonts, LaTeX packages, etc.). Its rendering options are otherwise extensively configurable, and different rendering options can be used for different elements. It can embed its images within HTML output or provide them as separate image files.

Requirements: Pandoc or Quarto, a LaTeX installation (with dvisvgm and, recommended, latexmk, which are included in common LaTeX distributions).

Limitations

• So far designed with HTML output in mind, LaTeX to SVG conversion, and LaTeX/PDF outputs with separate .tikz or .tex files as image sources. In other output formats, the images will be inserted or linked as PDFs and may display in wrong sizes or not at all.
• Embedding within HTML output isn't compatible with Pandoc's extract-media option.

Use cases

The filter is used to produce the academic journal Dialectica. See for instance this article.

Demonstration

See the manual's example HTML output.

For a quick try-out, clone the repository and try:

Pandoc : make generate && open example-pandoc/expected.html

Or:

Quarto : make quarto && open example-quarto/example.html

You'll need either Pandoc or Quarto and a standard LaTeX distribution (that includes dvisvgm).

Installation and usage

See the manual.

Issues and contributing

Issues and PRs welcome.

Acknowledgements

Development funded by Philosophie.ch.

imagify's Issues

Demonstration run from README is not replicable

Hi @jdutant, great package, I love the idea and the potential use cases.

I tried to do the demo run you have in the README. In particular, I went down the Quarto route by cloning the repo and ran make quarto && open example-quarto/example.html and am not able to replicate the doc.

I am getting a <LaTeX content not imagified> for all the contents supposedly filtered by imagify as can be seen in the attached image below.

I am using Quarto version 1.5.55 and I have tested the output HTML on both Safari and Google Chrome and neither is working.

Best,
Salman

Quarto: LaTeX metadata review

Check and document differences in LaTeX metadata between Pandoc and Quarto.

Make sure the filter handles both.

Quarto: in LaTeX/PDF output, pass packages using the Lua API

In Quarto users shouldn't specify LaTeX packages as (LaTeX commands in) header-includes. They should put them under the imagify key.

• Metadata syntax: make sure users can use the same keys under imagify as under format: pdf:
• Metadata coverage: make sure we pick up all documented Quarto keys that are relevant for the filter (provided we can access them when rendering to other formats than PDF)
• Pass to PDF output: pass packages specified under imagify to LaTeX when targeting LaTeX or PDF. In Pandoc, generate raw header-includes. In Quarto, use quarto.doc.include_text('in-header', text) and quarto.doc.use_latex_package(pkg, opt). See Quarto Lua API.

Add support for `revealjs`

When I imagify a simple tex command in Quarto with format: html, things work as expected. However, when I change the format to revealjs, I get a 404 error that the file cannot be found (even though an absolute link is provided to the existing file). Note that I am creating this issue with a PR ready, but I'm not entirely sure if this will add the full generality of the filter to all reveal presentations.

Great filter BTW!

Parsing macros to imagify

First of all, many thanks for this extension!

I am trying to use a macro and a tikzstyle in a TikZ picture but they both seem to fail:

1. \newcommand{\env}{\mathcal{E}}
2. \tikzstyle{arrow} = [->, > = Latex, very thick]

I am going to show the problem with tikzstyle only as I suspect the problems to be similar.

---

Here is the code that works (provided imagify is installed of course):
test_work.qmd:

---
title: "Test"
lang: en-GB
pdf-engine: lualatex
filters:
  - imagify
imagify:
  header-includes: |
    \usepackage{tikz}
    \usetikzlibrary{positioning}
    \usetikzlibrary{arrows.meta}
  pdf-engine: lualatex
format:
  html:
    toc: true
  pdf:
    include-in-header:
      - text: |
          \usepackage{tikz}
          \usetikzlibrary{positioning}
          \usetikzlibrary{arrows.meta}
---

![A test](./testFig_work.tex){#fig-testFig}

testFig_work.tex:

\begin{tikzpicture}
	%% Define nodes
	\node (N0) at (0, 0) {N0};
	\node[right = of N0] (N1) {N1};

	\draw[->, > = Latex, very thick] (N0) -- (N1);
\end{tikzpicture}

---

Here is the code that does not work:
test_fail.qmd:

---
title: "Test"
lang: en-GB
pdf-engine: lualatex
filters:
  - imagify
imagify:
  header-includes: |
    \usepackage{tikz}
    \usetikzlibrary{positioning}
    \usetikzlibrary{arrows.meta}
    \tikzstyle{arrow} = [->, > = Latex, very thick]
  pdf-engine: lualatex
format:
  html:
    toc: true
  pdf:
    include-in-header:
      - text: |
          \usepackage{tikz}
          \usetikzlibrary{positioning}
          \usetikzlibrary{arrows.meta}
          \tikzstyle{arrow} = [->, > = Latex, very thick]
---

![A test](./testFig_fail.tex){#fig-testFig}

testFig_fail.tex:

\begin{tikzpicture}
	%% Define nodes
	\node (N0) at (0, 0) {N0};
	\node[right = of N0] (N1) {N1};

	\draw[arrow] (N0) -- (N1);
\end{tikzpicture}

---

I gathered in a zip the four files.

I am doing anything wrong or is there a bug in transmitting the macros and tikzstyle?
test.zip

Lazy options crashes

The lazy:true option sometimes crashes because the scr variable is nil.

Quarto: quarto.doc.pdf_engine()

Does this work when the target output is not LaTeX/PDF? If yes, use it in Quarto

Quarto error messages

Use Quarto.log for error messages when the filter is run in quarto.

Quarto: quarto.doc.is_format()

Use quarto.doc.is_format() in Quarto

Converters: provide inkscape

Provide inkscape (cli) as an alternative PDF -> SVG converter.

Converters: provide tex2pdf

The filter uses dvisvgm. Provide the tex2pdf converter too.

Embed should be deactivated when extract-media is on

Deactivate embedding when extract-media is on.

This is due to a bug in Pandoc: instead of leaving data URLs as they are, it treats them as links to non-existent media files that it tries to extract, and converts the data URLs into link URL to non-existent files.

Allow users to provide custom pandoc templates for standalone LaTeX docs

Quarto: clean metadata after processing

From this discussion:

The filter looks for them both at the root and under imagify (the latter overriding the former). Seems fine?

Yes - It seems fine to me to use same name key as default Pandoc. What I am suggesting is doing some special treatment in Lua and not just passing them through to override. This way I think you could catch a raw content in LaTeX that would be removed in HTML output and use it for your HTML processing.

In Quarto, perhaps in Pandoc, consider whether some Imagifying/LaTeX metadata picked up by the filter should be removed in non-LaTeX/PDF output. E.g. LaTeX options at the root and the like.

Quarto: use native base64 encoding

To embed SVG files in data URLs the filter use base64url encoding. In Quarto the lbase64 library is available, the filter should use it.

• Check whether the default encoding is URL-safe
• If not, create a decoder (on-demand, in case the filter is applied to a doc without imagified content)

Quarto: document usage

Improve Quarto documentation:

• How to update the filter
• Metadata locations