latex.js

latex.js is a LaTeX to HTML5 translator written in JavaScript using a PEG.js parser. It is designed to be uncompromisingly exact and compatible with LaTeX, ensuring that the generated HTML output is precise. The accompanying CSS is designed to make the HTML output resemble standard LaTeX output.

For an interactive way to test LaTeX snippets, you can use the latex.js playground.

The translation process follows a specific pipeline:

1. Parsing: A PEG parser (defined in src/latex-parser.pegjs) parses the <latex/> code.
2. Generation: As the parser runs, it calls generator functions. The generator manages the state, including the stack, lengths, counters, fonts, and references.
3. Macro Execution: The generator uses the Macros class to execute macros encountered during parsing.
4. DOM Construction: Both the parser and the macros build the resulting HTML DOM tree by calling HtmlGenerator functions.

Key source files for the translation engine include:

• Parser: src/latex-parser.pegjs
• Generator: src/generator.ls and src/html-generator.ls
• Macros/DocumentClasses: src/latex.ltx.ls, src/symbols.ls, and files in src/documentclasses/*.ls
• Packages: src/packages/*.ls

Certain TeX features cannot be accurately translated to HTML/CSS due to the fundamental differences between TeX's layout engine and the web model:

Layout and Spacing

• Whitespace Handling: TeX's ability to remove specific whitespace from the beginning/end of lines (including special characters like \ or ~) is not fully possible in HTML.
• Glue: Horizontal glue (\hfill) and vertical glue cannot be emulated in HTML (except within boxes of fixed height).
• Negative VSpace: Using \vspace{} with a negative value inside a paragraph (horizontal mode) is not supported.
• Box Depth: TeX boxes have a specific 'depth' below the baseline. CSS boxes only recognize height, which can cause minor visual discrepancies in baseline alignment.

Pagination

• Pagebreaks: Since HTML is a continuous flow document, any macros related to pagebreaks will be ignored.

To develop on the LaTeX.js source, clone the repository and follow these steps:

Setup and Testing

npm install
npm run build   # or devbuild
npm test

Note: To verify CSS screenshots, you must have ImageMagick installed. The project uses puppeteer with Chromium to take screenshots.

Documentation and Playground To build the documentation website and the interactive playground:

npm run docs

To use the LaTeX to HTML5 translator from the command line, install the package globally using npm.

npm install -g latex.js

You can extend <latex/>.js by defining a custom class containing your macros and passing it to the HtmlGenerator constructor via the CustomMacros property in the options object.

If you define macros in an external file for use with the CLI, the file must either be named exactly like the class or use a default export.

var generator = new latexjs.HtmlGenerator({
  CustomMacros: (function() {
    var args      = CustomMacros.args = {},
        prototype = CustomMacros.prototype;

    function CustomMacros(generator) {
      this.g = generator;
    }

    // Define the 'bf' macro
    args['bf'] = ['HV']
    prototype['bf'] = function() {
      this.g.setFontWeight('bf')
    };

    return CustomMacros;
  })()
});

For maximum control over the translation process, use latex.js as a library in your project. The architecture is divided into a parser and a generator. Currently, only an HtmlGenerator is available.

Installation

npm install --save-prod latex.js

Basic Usage Pattern

1. Import the parser and the HtmlGenerator.
2. Parse the LaTeX source.
3. Use the generator to translate the parsed content into HTML.

Note: The HtmlGenerator accepts an options object for configuration.

Because latex.js uses a PEG parser that treats LaTeX as a context-free language, it cannot support TeX's Turing-complete macro system (including \def or dynamic scoping).

If you need a macro that is not provided by the library or is part of a specific LaTeX package, you must reimplement the macro directly in JavaScript to circumvent the parsing limitations.

You can install latex.js either as a global command-line tool or as a dependency in your JavaScript project.

Global CLI Installation

To use latex.js directly from your terminal, install it globally using npm:

npm install -g latex.js

Library Installation

To use latex.js as a module within your own application, add it to your project's production dependencies:

npm install --save-prod latex.js