@unified-latex/unified-latex-to-hast

unified-latex-to-hast

What is this?

Functions to convert unified-latex Abstract Syntax Tree (AST) to a HAST (html-like) tree.

When should I use this?

If you want to convert LaTeX to HTML.

Controlling the HTML output

This plugin comes with presets for several common LaTeX macros/environments, but you probably want to control how various macros evaluate yourself. For example, you may have used \includegraphics with pdfs in your LaTeX source by want to output HTML that manipulates the path and includes pngs instead. You can accomplish this by passing macroReplacements (for environments, there is the similarly-named environmentReplacements) to the plugin.

For example,

import { unified } from "unified";
import rehypeStringify from "rehype-stringify";
import { htmlLike } from "@unified-latex/unified-latex-util-html-like";
import { printRaw } from "@unified-latex/unified-latex-util-print-raw";
import { unifiedLatexToHast } from "@unified-latex/unified-latex-to-hast";
import { unifiedLatexFromString } from "@unified-latex/unified-latex-util-parse";
import { getArgsContent } from "@unified-latex/unified-latex-util-arguments";

const convert = (value) =>
    unified()
        .use(unifiedLatexFromString)
        .use(unifiedLatexToHast, {
            macroReplacements: {
                includegraphics: (node) => {
                    const args = getArgsContent(node);
                    const path = printRaw(
                        args[args.length - 1] || []
                    ).replace(/\.pdf$/, ".png");
                    return htmlLike({
                        tag: "img",
                        attributes: { src: path },
                    });
                },
            },
        })
        .use(rehypeStringify)
        .processSync(value).value;

console.log(convert(`\\includegraphics{foo.pdf}`));

macroReplacements and environmentReplacements functions can return any unified-latex Node, but using the htmlLike utility function will return nodes that get converted to specific HTML. See htmlLike's documentation for more details.

Install

npm install @unified-latex/unified-latex-to-hast

This package contains both esm and commonjs exports. To explicitly access the esm export, import the .js file. To explicitly access the commonjs export, import the .cjs file.

Plugins

unifiedLatexToHast

Unified plugin to convert a unified-latex AST into a hast AST.

Usage

unified().use(unifiedLatexToHast[, options])

options

PluginOptions

Type

Plugin<PluginOptions[], Ast.Root, Hast.Root>

function unifiedLatexToHast(
  options: PluginOptions
): (tree: Ast.Root, file: VFile) => Hast.Root;

unifiedLatexWrapPars

Unified plugin to wrap paragraphs in \html-tag:p{...} macros. Because - and : cannot occur in regular macros, there is no risk of a conflict.

Usage

unified().use(unifiedLatexWrapPars[, options])

options

PluginOptions

Type

Plugin<PluginOptions[], Ast.Root, Ast.Root>

function unifiedLatexWrapPars(options: PluginOptions): (tree: Ast.Root) => void;

Functions

attachNeededRenderInfo(ast)

Attach renderInfo needed for converting some macros into their katex equivalents.

function attachNeededRenderInfo(ast: Ast.Ast): void;

Parameters

Param	Type
ast	Ast.Ast

convertToHtml(tree, options)

Convert the unified-latex AST tree into an HTML string. If you need more precise control or further processing, consider using unified directly with the unifiedLatexToHast plugin.

For example,

unified()
     .use(unifiedLatexFromString)
     .use(unifiedLatexToHast)
     .use(rehypeStringify)
     .processSync("\\LaTeX to convert")

function convertToHtml(
  tree: Ast.Node | Ast.Node[],
  options: PluginOptions
): string;

Parameters

Param	Type
tree	Ast.Node | Ast.Node[]
options	PluginOptions

wrapPars(nodes, options)

Wrap paragraphs in <p>...</p> tags.

Paragraphs are inserted at

• parbreak tokens
• macros listed in macrosThatBreakPars
• environments not listed in environmentsThatDontBreakPars

function wrapPars(
  nodes: Ast.Node[],
  options: {
    macrosThatBreakPars?: string[];
    environmentsThatDontBreakPars?: string[];
  }
): Ast.Node[];

Parameters

Param	Type
nodes	Ast.Node[]
options	Omitted

Constants

Name	Type
KATEX_SUPPORT	{ macros: any; environments: any; }
katexSpecificEnvironmentReplacements	Record<string, (node: Ast.Environment) => Ast.Node | Ast.Node[]>
katexSpecificMacroReplacements	Record<string, (node: Ast.Macro) => Ast.Node | Ast.Node[]>

Types

PluginOptions

export type PluginOptions = HtmlLikePluginOptions & {
    /**
     * By default, `unifiedLatexToHast` will force the output to be valid HTML.
     * This is accomplished by running `rehypeRaw` on the output which will ensure
     * there are no nested `<p>` tags, and that block elements don't end up as children of `<span>`s,
     * etc. Set to `true` to skip this check.
     */
    skipHtmlValidation?: boolean;
};

Changelog

v1.8.3

• Support \ref in PreTeXt conversion
• Better use of UnifiedJS to parse but not print LaTeX
• Support for \verb, \textsuperscript, \textsubscript, \sout, and \" i in HTML conversion