Building from Source¶
Install Node if needed. Then run
make. This installs all of the needed dependencies and creates the full build folder.
For developing on MathQuill, run
make dev. This will skip minifying MathQuill, which can be annoyingly slow.
Building a Smaller MathQuill¶
make basic builds a stripped-down version of MathQuill for basic mathematics, without advanced LaTeX commands. This version doesn't allow typed LaTeX backslash commands with
\ or text blocks with
$, and also won't render any LaTeX commands that can't by typed without
\. This version of MathQuill's JS is only somewhat smaller, but the font is like 100x smaller.
To run this smaller version, serve and load
make test, which builds
test/unit.html in your browser to see the result of the unit tests. Open
test/visual.html to see how a variety of expressions are rendering on your branch.
Understanding The Source Code¶
build/ is created by
make to contain the same JS concatenated and minified.
There's 2 thin layers sandwiching 2 broad, modularized layers. At the highest level, the public API is a thin wrapper around calls to services on the controller. These set event listeners that call methods on commands in the edit tree. Those commands call tree and cursor manipulation methods to do actions like move the cursor or edit the tree.
At the lowest level, the edit tree of JS objects represents math and text analogously to how the HTML DOM represents a web page.
tree.js defines base classes of objects relating to the tree.
cursor.js defines objects representing the cursor and a selection of math or text, with associated HTML elements.
Old docs called this the "math tree", the "fake DOM", or some combination thereof, like the "math DOM".
A command is a thing a user can type and edit like a fraction, square root, or "for all" symbol, ∀. They are implemented as a class of node objects in the edit tree, like
Each command has an associated control sequence (commonly called a "macro" or "command"). This is a token in TeX and LaTeX syntax consisting of a backslash then any single character or string of letters, like
\ . Unlike loose usage in the LaTeX community, where
\neq might or might not be considered the same command, in the context of MathQuill they are considered different "control sequences" for the same "command".
A service is a feature that applies to all or many actions, such as typing, moving the cursor around, LaTeX exporting, or LaTeX parsing. Each of these actions vary by command. For example, the cursor goes in a different place when moving into a fraction vs into a square root and they each export different LaTeX.
Services define methods on the controller that call methods on nodes in the edit tree with certain contracts, such as a controller method called on initialization to set listeners for keyboard events, that when the Left key is pressed, calls
.moveTowards on the node just left of the cursor, dispatching on what kind of command the node is (
SquareRoot::moveTowards can insert the cursor in different places).
controller.js defines the base class for the controller, which each math field or static math instance has one of, and to which each service adds methods.
publicapi.js defines the global
MathQuill.getInterface() function, the mathField constructors, and the API objects returned by them. The constructors, and the API methods on the objects they return, call appropriate controller methods to initialize and manipulate math field and static math instances.
services/*.util.js files are unimportant to the overall architecture. You can largely ignore them until you have to deal with code that is using them.
intro.js defines some simple sugar for the idiomatic JS classes used throughout MathQuill, plus some globals and opening boilerplate.
Classes are defined using Pjs, and the variable
_ is used by convention as the prototype.
In comments and internal documentation,