Overview

PubPub uses Pandoc to convert from LaTeX to HTML, and KaTeX to render LaTeX math blocks in browsers. Both Pandoc and KaTeX have limitations that can lead to issues with imported LaTeX.

Current versions:

• KaTeX: 0.13.18

• Pandoc: 2.14.2

Issues that occur during the import process itself are likely related to Pandoc’s limitations. Unfortunately, Pandoc’s documentation of these issues is not particularly robust, so if an issue occurs during import, you should first look at this list, and then contact [email protected] if it doesn’t address your problem.

KaTeX maintains three resources that should be the starting point for diagnosing most issues with rendering after a successful import. If your issues are not addressed by these documents, take a look at this list.

• Supported functions

• Support table

• Common issues

Known Incompatibility List

Custom/Obscure Packages

• Description: Use of custom packages causes the import to fail/freeze/stall, or leads to blank spaces in imported documents.

• Issue source: Pandoc/pre-import

• Workaround(s):

  • Reduce usage of custom or obscure packages

  • Follow workarounds specific custom packages listed below.

• Outlook: PubPub uses TeX Live to build its TeX environment. Because the full collection is enormous, and we have some limitations around build size, we are limited in the number of packages we can support. If your community frequently uses a TeX Live package not on the list, contact us at [email protected]. We may be able to add it. At the moment, we load the following packages:

  • collection-fontutils

  • collection-latex

Algorithmic

• Description: Figures created with the algorithmic package are not supported.

• Issue source: KaTeX/post-import

• Workaround(s):

  • Reproduce the figure in a table on PubPub

  • Screenshot the figure in the PDF and add as an image to PubPub.

• Outlook: KaTeX is taking a look at supporting the package.

Flowcharts

• Description: Figures created with the flowchart package are not supported.

• Issue source: KaTeX/post-import

• Workaround(s):

  • Reproduce the figure in a table on PubPub

  • Screenshot the figure in the PDF and add as an image to PubPub.

• Outlook: KaTeX is taking a look at supporting the package.

tikz, tikzcd, matlab2tikz, pgfplots

• Description: Figures created with the tikz, tikzcd, matlab2tikz, or pgfplots packages are not supported.

• Issue source: KaTeX/post-import

• Workaround(s):

  • Use tikz-external to create image versions of the figures

  • Screenshot the figure in the PDF and add as an image to PubPub.

• Outlook: KaTeX is unlikely to support the packages in the near future.

Align

• Description: Equations that use align, align*, alignat, alignat* will not render.

• Issue source: KaTeX/post-import

• Workaround: Switch the equation to block mode. When an equation is in inline display mode, KaTeX only supports functions that work in LaTeX’s math rendering environment, such as aligned. In block mode, align/*/at/at* are supported. See KaTeX’s common issues page for more details.

Citation Style Imports Wrong

• Description: The citation style always imports to PubPub in the way selected in the default pub — e.g. (Author, Year) — rather than the way specified in the LaTeX (normal, suppressauthor, authorintext).

• Issue source: Pandoc/post-import

• Workaround(s):

  • Use a custom citation style for the relevant citations in PubPub.

• Outlook: PubPub plans to support specified citation styles in the near future.

Multipart Figures

• Description: Figures with multiple images grouped with a single caption will import with a caption on the first or last image, depending on how it was done in LaTeX.

• Issue source: LaTeX to HTML impedence mismatch/post-import

• Workaround(s):

  • Reproduce the figure in a table, if needed, with a joined row at the bottom as the caption

  • Combine or take a screenshot of the images in the PDF and upload as one figure into PubPub, with a caption.

• Outlook: Very difficult to support natively due to HTML/LaTeX incompatibilities. Recommend authors combine multi-party figures into a single image, or that production teams use tables.

Equations Not Rendering

• Description: Imported math may not appear properly, often as LaTeX expressions with some in red blocks.

• Issue source: KaTeX/post-import

• Workaround(s):

  • Remove KaTeX unsupported functions from the math block that are not essential to the math itself (often \label or formatting/spacing functions), and compare to PDF version.

  • Find alternatives to obscure functions by googling “latex [function name] alternative”, and replace them.

• Outlook: Under review. PubPub can likely automatically strip more common errors eventually, and we may at some point be able to provide an auto-complete for supported functions. But we’ll be unable to ever fully support all of LaTeX given the sheer diversity of packages and limitations of KaTeX.

References Contain Un-Rendered LaTeX Strings

• Description: References contain latex code that is rendered as \command, rather than its output.

• Issue source: Pandoc/post-import

• Workaround(s):

  • Replace LaTeX command with desired output

  • Ask authors not to use LaTeX in references.

• Outlook: We may be able to ultimately process LaTeX code in references, but it is bad practice to include it in general, so the practice should be avoided.

Tables With Nested Multi-Line Merged Cells or Rows

• Description:

• Issue source: Pandoc/post-import

• Workaround(s):

  • Re-create the table natively in PubPub to match the desired PDF output

  • Use a screenshot of the table in lieu of a native HTML table

• Outlook: Pandoc has prioritized supporting this type of table in a future release. A fix should be imminent!

Section and Figure/Table/Equation Numbering

• Description: PubPub does not replicate the manuscript’s automated section, figure, table, or equation numbering, or numbering does not appear.

• Issue source: Pandoc/post-import

• Workaround(s):

  • For tables and figures, ask authors to modify the source LaTeX to include their \label directly after or inside the figure/table \caption, which is best practice and should reduce misnumbering. See this thread for more information.

  • For sections and equations, use manual numbering rather than PubPub’s built-in system.

  • For equations, ask authors not to use sub-numbering (e.g. 2.1)

• Outlook: PubPub is planning to add support for section and sub-section numbering, and figure, table and equation numbering that should allow documents to more closely match LaTeX.

Section and Figure/Table/Equation Internal Referencing

• Description: Internal references to certain sections/figures/tables/equations may appear with incorrect numbers, or as unresolved shortcodes (e.g. [fig1]).

• Issue source: Pandoc/post-import

• Workaround(s):

  • Double-check that all references are spelled correctly.

  • For figures and tables, ask authors to modify the source LaTeX to include their \label directly after or inside the figure/table \caption, which is best practice. See this thread for more information.

  • For sections and equations, manually correct bad references by changing the name to the proper number and copying the direct link to the element into the link.

• Outlook: PubPub is planning to enhance support for internal references for sections and figures.

Figures are blank

• Description: Figures either don’t appear at all, or appear as broken images.

• Issue source: Pandoc/post-import

• Workaround(s):

  • Make sure the LaTeX source includes file extensions for all figure images (e.g. .pdf, .png). Most of the time, PubPub will be able to find these images, but on rare occasions, an extension is required.

  • Make sure the figure image is of a supported type: pdf, png, jpg, gif.

• Outlook: PubPub may be able to expand image support, but is unlikely to at present given that this issue is rare and we support most common images types, including conversion from pdf to png.

Template

Title

• Description: ...

• Workaround(s):

• Outlook: …