@unified-latex/unified-latex-to-pretext

unified-latex-to-pretext

What is this?

Functions to convert unified-latex Abstract Syntax Tree (AST) to a XAST (xml-like) tree in the PreTeXt format.

When should I use this?

If you want to convert LaTeX to PreTeXt for further processing with the PreTeXt compiler.

Controlling the PreTeXt 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 the output to reference different files. 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 { unifiedLatexToPretext } from "@unified-latex/unified-latex-to-pretext";
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(unifiedLatexToPretext, {
            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-pretext

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

unifiedLatexToPretext

Unified plugin to convert a unified-latex AST into a xast AST representation of PreTeXt source.

Usage

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

options

PluginOptions

Type

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

function unifiedLatexToPretext(
  options: PluginOptions
): (tree: Ast.Root, file: VFile) => Xast.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;

xmlCompilePlugin

Unified plugin to convert a XAST AST to a string.

Usage

unified().use(xmlCompilePlugin)

Type

Plugin<void[], Root, string>

function xmlCompilePlugin(): 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

convertToPretext(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 unifiedLatexToPretext plugin.

For example,

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

function convertToPretext(
  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 & {
    /**
     * A boolean where if it's true then the output won't be wrapped in the <pretext><article> ... etc. tags.
     * If it's false (default), a valid and complete PreTeXt document is returned.
     */
    producePretextFragment?: boolean;
};