DOCSEARCHbyAlgolia
Submit Docs

MathLive Documentation

repository·master·Indexed 24 days ago

https://github.com/arnog/mathlive

A web component library for high-fidelity, accessible math input and display. It provides the <math-field> interactive editor with virtual keyboard support, as well as <math-span> and <math-div> for static TeX-quality rendering. Includes a Vue wrapper and supports LaTeX, MathML, and math-json formats.

Tokens
37.4K
Snippets
84
Records
237
Agent score
84%

What's inside MathLive

  1. Understand the MathLive source architecture

    master

    MathLive is organized into several specialized modules that handle different stages of the math rendering and editing lifecycle:

    • src/public: Contains the TypeScript declaration files defining the public API.
    • src/core: The rendering engine responsible for parsing LaTeX and converting it into HTML markup.
    • src/core-atoms: Low-level code used to render and generate LaTeX for specific mathematical layout objects (e.g., fractions, delimiters, arrays).
    • src/core-definitions: Maps supported LaTeX commands to their arguments and corresponding atoms.
    • src/editor: Utilities for editor-specific features like the virtual keyboard, localization, and keybindings.
    • src/editor-mathfield: The interactive UI component that manages keyboard/pointer input and the visual interface for editing formulas.
    • src/editor-model: Manages the state of the math expression, including the tree of atoms representing the content and the current selection, along with methods to modify that state.
    • src/addons: Miscellaneous additional features.

  2. Use the MathLive Vue wrapper

    master
    The MathLive Vue wrapper provides a <mathlive-mathfield> component that allows you to embed a rich, accessible math editor into your Vue applications. This component enables users to edit mathematical formulas using the MathLive library, supporting virtual keyboards for mobile devices and providing output in formats such as LaTeX, MathML, or spoken text.

  3. Mathfield API Reference Overview

    master
    The Mathfield API provides the interface for interacting with MathLive's mathematical input components. The documentation covers the core Mathfield class and the MathfieldElement web component, which are the primary entry points for integrating mathematical editing capabilities into web applications.

  4. Overview of MathLive components

    master

    MathLive provides three main web components for different math rendering needs:

    1. <math-field>: The flagship interactive editor. Best for user input, featuring a virtual keyboard, command execution, and event handling.
    2. <math-span>: A lightweight, inline renderer for static math. Ideal for embedding math within text paragraphs.
    3. <math-div>: A block-level renderer for static math. Best for display equations and articles.

  6. Configure LaTeX export format and clipboard behavior

    master

    In version 0.34.0, the latex-expanded format was updated to ensure better compatibility with other TeX-compatible renderers:

    • The latex-expanded format no longer returns \mleft and \mright commands.
    • Content exported to the clipboard is now automatically surrounded by $$ to indicate TeX format.
    • When pasting content that begins or ends with $ or $$, MathLive will assume the content is in LaTeX format.

  7. Understand the core parsing and rendering pipeline

    master

    The src/core/ module is responsible for the parsing and rendering of LaTeX. It does not handle LaTeX editing. The pipeline works as follows:

    1. Parsing: It uses LaTeX command definitions located in core-definitions/ to interpret the input LaTeX string.
    2. Layout: It uses layout primitives from core-atoms/ to transform the parsed input into Box objects (which act as virtual DOM nodes).
    3. Rendering: These Box objects are then rendered into final HTML or SVG markup.

  8. Configure the shared Virtual Keyboard

    master

    Since version 0.90.0, the virtual keyboard is a single global instance shared by all mathfields. You should configure it via the mathVirtualKeyboard global object rather than on individual mathfield instances.

    Key Properties:

    • mathVirtualKeyboard.layouts: Defines the keyboard layouts (replaces customVirtualKeyboardLayers and customVirtualKeyboards).
    • mathVirtualKeyboard.alphabeticLayout: Sets the alphabetic layout (e.g., 'azerty').
    • mathVirtualKeyboard.actionToolbar: Configures the toolbar (replaces virtualKeyboardToolbar).
    • mathVirtualKeyboard.container: Sets the container for the keyboard (replaces virtualKeyboardContainer).
    • mathVirtualKeyboard.show() / mathVirtualKeyboard.hide(): Programmatic control of visibility.

    Keyboard Policy: Use MathfieldElement.mathVirtualKeyboardPolicy on a mathfield instance to control automatic behavior:

    • "auto": The keyboard displays automatically on touch devices when a mathfield is focused.
    • "manual": The keyboard does not display automatically; you must call mathVirtualKeyboard.show() (e.g., on a focusin event).

  9. Understand the Mathfield interaction layers

    master

    The mathfield interaction logic is split into two primary input handling modules:

    • Pointer Input: Handled by pointer-input.ts, managing mouse and touch interactions.
    • Keyboard Input: Handled by keyboard-input.ts, managing keyboard-based math entry.

    These modules work in conjunction with the MathfieldPrivate class, which acts as the bridge between the Model (the source of truth for the mathfield state) and the Core (the engine that renders the model's data into HTML/SVG markup).

  10. Understand the Atom layout primitives

    master

    In MathLive, layout primitives are defined as subclasses of the base Atom class. These atoms are the building blocks used to construct mathematical layouts. Each atom typically implements two key methods:

    1. render(): Returns an array of Box objects (virtual DOM nodes) that represent the visual instance of the atom.
    2. serialize(): (Optional) Returns a LaTeX string representing the atom instance. While the base Atom class provides a default implementation (command name + arguments in curly brackets), atoms can override this to provide custom LaTeX output.

  11. Understand the Render Tree

    master

    The render tree is a visual representation generated from the data model. It contains geometric information (position and size) and visual properties for each element.

    Key Characteristics

    • Inheritance: Nodes can inherit properties like color, font, and size from their parent nodes.
    • Output Formats: The render tree can be transformed into a DOM tree, a Canvas, an SVG, or a MathML tree.
    • Hitboxes: The output of the render tree must be passed to the hitbox handler to enable interaction.

    Common Render Nodes

    • vbox: Boxes stacked vertically.
    • hbox: Boxes stacked horizontally, aligned on the baseline.
    • glyph: A single character or symbol.

  12. Understand the Mathfield Data Model

    master

    The data model is a tree structure representing the content and state of the mathfield. It tracks content, selection, and styling.

    State Changes & Events When the data model is modified (content, selection, or style), an event is dispatched. To support cancellation of changes, state change events include two phases:

    • willChange: Fired before the change is applied.
    • didChange: Fired after the change is applied.

    Node Attributes Nodes in the tree can have various attributes, including:

    • hspace: Horizontal spacing (e.g., 'op', 'bin', 'rel', or 'default').
    • Styling: color, background color, weight (e.g., bold, normal), shape (e.g., italic, slanted), fontsize, and font-family (e.g., roman, sans-serif).
    • variant: Mathematical variants like double-struck or calligraphic.

    Node Types The model consists of several node types, such as text, mathlist, command, placeholder, error, space, line, box, rule, genfrac, surd, accent, overunder, delim, and table.