It's recommended to clone this repo with ka-clone, which installs Khan Academy's standard git hooks. if you used plain git clone instead, don't worry. You can run ka-clone --repair at any time to install the hooks.

You will need node and pnpm for development. If you're a KA engineer, you probably installed these when setting up your computer, but if you don't have them, see this guide.

Versions used for initial development of this repo:

Later versions will probably work fine—but if you run into issues, just know that a version mismatch here might be the cause.

Install dependencies and additional git hooks by running:

pnpm repo-setup

In the preprocessing folder, create a file (ex. to fix a bug) titled something like fix-bug.ts and a second file titled fix-bug.test.ts

Create a function to replace specific TeX (found using regex) with a specific expression (ex below)

export function fixBug(tex: string): string {
    return tex.replace(/<regex>/g, "<new-tex>");

Create unit tests in the test file to confirm the processing step is working. Consider any potential edge cases that your fix might be tested against

import {describe, it, expect} from "@jest/globals";
import {fixBug} from "./fix-bug";

describe("fixBug", () => {
    it("fixes the bug", () => {
        const input = "<old-tex>";
        const fixed = "<new-tex>";
        expect(fixBug(input)).toBe(fixed);
    });
});

Go to the index.ts file and add the fix to the pipeline. It should not be necessary to add to fixNonstandardSyntax as all new math should be MathJax-compatible. As a result, future changes here should be added to workAroundMathjaxDeficiences. (Don’t forget to import the function at the top!)

You should almost always add a regression test (there is a how-to guide for this below too). The only time not to do a regression test is if the feature/fix cannot be covered by these kinds of regression tests (ex. purely visual changes via CSS). To add a regression test, go to the regression-tests folder and create a file titled something like bug-fix.test.ts

Here you will add some standardized code that is used for all the regression tests, but with a couple parts changed (indicated with angle brackets)

import {describe} from "@jest/globals";
import {testEachTexExpressionInFileIsRenderable} from "./test-generator";

describe("the <tex> command in MathJax", () => {
    testEachTexExpressionInFileIsRenderable({
        filename: "<bug-fix>_data.txt",
        separator: "\n\n\n",
    });
});

As you can see, data is needed. Create a file in that same folder titled bug-fix_data.txt. Conduct a regex search of all the content for the specific phrase in question. Add some of that to the file, depending on how many examples there are. The README has more info on this.

Once you add a new regression test, you will want to run all the tests and see if any of the other tests notice a regression. Check to make sure the errors are expected, then update the snapshots by passing -u to the pnpm test command. You may be able to update the tests in the IDE interface too.

Summary:

• Create fix file and unit test file in preprocessing
• Add fix to the pipeline in the index file
• Move over to regression-tests and add a test file and data text file to watch for regressions
• Run regression tests and update snapshots (pnpm test -u <test-filename>) Here is an example PR for adding a new preprocessing step

Head over to the tex-input-config.ts file in src/ts

Follow the format of the other macros there. <Macro-name>: "<new-macro>",

Head over to renderer.test.ts and add in the new macro for testing, following the syntax there

[`\\<Macro-name>`, "<description of how it looks>"]

Run the tests, check for anything unexpected in the results, and then update the snapshots

Here is an example PR for adding a new TeX macro.

It's useful to be able to test MathJax on actual math from our content.

Download a snapshot of English and Hindi content by running:

pnpm download-content-snapshot

The download will take about 15 minutes. Once it's done, run

pnpm extract-tex

This will scan the downloaded content for TeX expressions and write each expression to a file in data/tex. It takes about 30 minutes.

The download and extract steps are split up because sometimes, the download hangs at 99% (bug in gsutil, maybe?) and has to be manually killed. If you encounter this bug, it's fine to kill the download, then go ahead and run pnpm extract-tex without re-running the download.

If you add features or fix bugs in the renderer, you'll probably want to add regression tests for them. See regression-tests/README.md for details about what the regression tests cover and how they work.

Getting Data For Regression Tests

Assuming you have done all the "Downloading Test Data" steps above, you can search for TeX expressions matching a regex by running:

# NOTE: use single quotes for the regex! Double-quotes in bash use different escaping rules.
pnpm search-tex '\\begin\{align(ed)?\}' | pbcopy

The pbcopy command (on macOS only) puts the search results on your clipboard.

Each TeX expression in the results is annotated with the path of the Perseus JSON file it originally came from.

You can then paste the search results into a regression test data file. See the regression-tests folder for examples.

The release process uses @changesets/cli.

The workflow is:

• Each feature PR must include a changeset file, generated by running pnpm changeset, describing what is in that change and whether a major, minor, or patch version bump is required.
• A GitHub workflow watches the main branch and updates a "Version Packages" PR whenever a feature PR is landed.
• When the "Version Packages" PR is landed, a GitHub workflow updates the package version and changelog based on outstanding changesets, builds a new version of the package, and publishes it to NPM.

Landing the "Version Packages" PR is a manual action (you can use git land for this) but everything else should be automatic.

After releasing, please consider updating the known usages of this repo to the new release.

Webapp

Once a new version is released, the version in webapp will need to be updated. This involves manually updating the version number of MathJax in Webapp's package.json file (services/static/package.json) and then running pnpm install in the services/static directory to update the pnpm-lock.yaml file.

Here is an example PR of bumping the version of MathJax in Webapp: Update mathjax to newest version in webapp (Does not have to be done as an audit as it is here)

It is possible there will be merge conflicts with the package.json. Make sure to confirm the version update is still present after resolving all conflicts!

Graphie Editor

The graphie editor consumes MathJax as a Git submodule. It is connected to a specific commit and does not update automatically, though updating it is similar to updating a regular git repo. Here is an approximate example of how to update it:

cd ~/Khan/graphie-to-png

# go into the submodule directory
cd mathjax-renderer

# download the latest commits from the mathjax-renderer repo
git fetch origin

# update to the desired version
git co vX.Y.Z

# re-pin the submodule to the new version
cd ..
git add mathjax-renderer
git commit

Example PR - Switch the math renderer from KaTeX to MathJax

PR from creating a bundle for the editor. This is regularly done as part of the regular release, so nothing needs to be done regarding the bundle when bumping MathJax in the graphie repo - Build to a single-file bundle, for graphie-to-png

Mobile

This must be done as part of the mobile release cycle. The version is specified in webview/javascript/package.json. Update the version number there, install dependencies, and commit the changes.

Example PR - Bumping the version of MathJax-Render in mobile