We welcome pull requests to KaTeX. If you'd like to add a new symbol, or try to tackle adding a larger feature, keep reading. If you have any questions, or want help solving a problem, feel free to stop by our gitter channel.
If you'd like to contribute, try contributing new symbols or functions that KaTeX doesn't currently support. The documentation has pages listing supported functions and functions that KaTeX supports and some that it doesn't support. You can check them to see if we don't support a function you like, or try your function in the interactive demo at http://katex.org/. The wiki has a page that describes how to examine TeX commands and where to find rules which can be quite useful when adding new commands.
There are many individual symbols that KaTeX doesn't yet support. Read through the symbols.js file for more information on how to add a symbol.
To figure out the unicode symbol for the symbol you are trying to add, try using the symbol in MathJax to see what unicode symbol it outputs. An interactive MathJax shell can be found here.
To figure out what group your symbol falls into, look through the symbols list
to find other symbols of a similar kind. (e.g. if you were adding
=). If you cannot find anything similar, or are unsure, you can try using
your symbol in TeX surrounded by other different kinds of symbols, and seeing
whether your spacing matches the spacing that TeX produces.
New functions should be added in src/functions using
defineFunction from defineFunction.js. Read the
comments in this file to get started. Look at
delimsizing.js as examples of how to use
defineFunction. Notice how delimsizing.js groups several related functions
together in a single call to
The new method of defining functions combines methods that were previously spread out over three different files functions.js, buildHTML.js, buildMathML.js into a single file. The goal is to have all functions use this new system.
Local testing can be done by running the webpack-dev-server using configuration
yarn to install dependencies, and then
to start the server.
This will host an interactive editor at http://localhost:7936/ to play around with and test changes.
webpack-dev-server 2.8.0 introduced a change which included ES6 keywords
let within the scripts being served to the browser, and therefore doesn't
support IE 9 and 10. If you want to test in IE 9 and 10, install version 2.7.1
yarn add firstname.lastname@example.org.
builders are tested with Jest. These tests can be run using node with
yarn test:jest. If you need to debug the tests see
The interactive editor can also be used for debugging tests in the browser by copy/pasting the test case to be debugged into the editor. The permalink option can come in really useful when doing repeated runs of the same test case.
The Jest tests should be run after every change, even the addition of small symbols. However, CircleCI will run these tests when you submit a pull request, in case you forget.
If you make any changes to Parser.js, add Jest tests to ensure they work.
Some tests verify the structure of the output tree using snapshot testing.
Those snapshots can be updated by running
Also, test code coverage can be collected by
You can view the report in
To ensure the final output looks good, we screenshot different expressions. These tests can be run by using the screenshotter docker.
The screenshot tests should be run if you add anything more significant than individual symbols. These tests are not automatically run, so please remember! If the new images are different (meaning they are not byte-by-byte the same as the old ones), inspect them visually. If there are no visible changes, that is okay. If things change in a way consistent with your additions, explain what changed and why. Otherwise, figure out what is causing the changes and fix it!
If you add a feature that is dependent on the final output looking the way you created it, add a screenshot test. See ss_data.yaml.
You can use our texcmp tool to compare the outputs of a screenshot test as generated by KaTeX and LaTeX. It's often useful to attach the resulting "visual diff" to your pull request with a new feature.
KaTeX supports all major browsers, including IE 9 and newer. Unfortunately, it is hard to test new changes in many browsers. If you can, please test your changes in as many browsers as possible. In particular, if you make CSS changes, try to test in IE 9, using modern.ie VMs.
KaTeX is built using webpack with configuration
yarn build to build the project.
In general, try to make your code blend in with the surrounding code.
The code can be linted by running
files using ESLint and stylesheets using stylelint. They must pass to commit
Some files have flowtype annotations and can be checked for type errors using
Flow by running
yarn test:flow. See Flow for more details.
The fonts for KaTeX live in a submodule stored in
When you first clone the KaTeX repository, use
git submodule update --init --recursive to download the corresponding
fonts repository. After running
yarn, you should have Git hooks that
will automatically run this command after switching to branches
submodules/katex-fonts point to different commits.
For more info about how to use git submodules, see https://chrisjean.com/git-submodules-adding-using-removing-and-updating/.
In order to contribute to KaTeX, you must first sign the CLA, found at www.khanacademy.org/r/cla
KaTeX is licenced under the MIT License.