unified-latex

Monorepo for @unified-latex packages. See the auto-generated Documentation for usage details.

These packages provide a JS/TypeScript interface for creating, manipulating, and printing LaTeX Abstract Syntax Trees (ASTs).

Most of the action lies in the

• packages/ directory, where you'll find plugins for Unifiedjs and standalone tools for parsing LaTeX to an Abstract Syntax Tree (AST). Though parsing LaTeX isn't possible since it effectively has no grammar, unified-latex makes some practical assumptions. It should work on your code, unless you do complicated things like redefine control sequences or embed complicated TeX-style macros.

How it works

unified-latex uses PEG.js to define a PEG grammar for LaTeX. LaTeX source is first parsed with this grammar. Then it is post-processed based on knowledge of special macros. (e.g., some macros are known to take an argument, like \mathbb. Such arguments are not detected in the PEG processing stage).

See the examples/ folder for usage samples.

Development

You should develop in each project's subfolder in the packages/ directory. These packages are set up as npm workspaces.

If you have node.js and npm installed, run

npm install

in this (the root) directory. Then — after doing a full build as explained below first! — you may build any particular package (for example)

cd packages/unified-latex
npm install
npm run build

Building

vite is used to create bundled packages in the esm and commonjs formats. Builds are managed by wireit which can intelligently rebuild dependencies when they change. All compiled files are stored in the dist/ directory of a workspace.

To build code for all workspaces, run

npm run build -ws

from the root directory.

If typescript complains about imports not existing in rootDir, it probably means that there is not a TypeScript reference to that particular workspace. (References are how typescript divides projects into different pieces so that it doesn't need to recompile every project). Add the imported project to the "references" field of the tsconfig.json.

Note that all tsconfig.json files extend tsconfig.build.json, which has some special configuration options to forward imports of @unified-latex/... directly to the correct folder during development.

Testing

Tests in a specific workspace can be run via npx vitest in that workspace. These for the whole project can be run via npm run test in the root directory.

Since built packages are expected to support both esm and commonjs, testing of the built packages occurs in test/esm and test/cjs. To run these tests, make sure you have built all packages first. Run the following:

npm run build
npm run test:packages-install
npm run test:packages-esm
npm run test:packages-cjs

The test:packages-install runs npm pack on each dist/ directory and then copies the packaged files into the test/dist directory. Both test/esm and test/cjs install from these files (not the files hosted by npm).

Readme Generation and Consistency

README.md files for all workspaces are generated automatically by running

npx esr scripts/build-docs.ts

package.json files can be checked for naming consistency by running

npx esr scripts/package-consistency.ts

Publishing

Version management is done with lerna. Run

npx lerna version

to update the version of all packages. Run

npm run package
npm run publish

to publish all workspaces.

Playground

You use the Playground to view how latex is parsed/pretty-printed. To run your own version, visit the playground repository, and make a local clone. After running npm install, run npm link in your local latex-parser repository. Then, run npm link latex-ast-parser in the local playground repository. This will mirror your development version of latex-parser in the playground.

Related Projects

• Some code was borrowed from Michael Brade's LaTeX.js project
• Prettier is a code-formatting library
• tree-sitter-latex a tree-sitter grammar for incremental parsing of LaTeX
• Texlab a Rust implementation of the Language Server Protocol for LaTeX