Perseus is Khan Academy's new exercise question editor and renderer.
JavaScript CSS
Latest commit 954d328 Feb 24, 2017 @crm416 crm416 Update built files
Summary:
To include:

```
b2c4059  Charles Marsh 2017-02-23 Use MathInput input boxes for <Table> widget
```

Test Plan: Run through the plan from that commit.

Auditors: kevinb
Permalink
Failed to load latest commit information.
.arcanist_extension/FlowTestEngine Experimental flow support in perseus Nov 30, 2016
build Update built files Feb 25, 2017
fonts Add symlinks to proxima fonts :) Aug 19, 2016
hubble @ e485987 [multirenderer] multi-editor UI: add, remove, and move array elements Dec 13, 2016
images Inline dropdown icon Aug 19, 2016
jest Actually remove khan-exercises from Perseus May 10, 2016
kmath @ 92454b1 substate kmath Feb 19, 2015
lib Update MathJax substate Jan 4, 2017
math-input @ 93a4a5d Update math-input substate Dec 20, 2016
node Experimental flow support in perseus Nov 30, 2016
node_modules Fix nits from previous code review and make it work with fresh install May 13, 2016
react-components @ 539b056 Revert "react-components: add onResourceLoaded prop to TeX" Feb 1, 2017
simple-markdown @ 27d1bc0 Substate react-components and simple-markdown. Sep 30, 2015
src Use MathInput input boxes for <Table> widget Feb 25, 2017
stylesheets Use MathInput input boxes for <Table> widget Feb 25, 2017
.arcconfig Experimental flow support in perseus Nov 30, 2016
.arclint Fix lint config in Perseus Jun 1, 2016
.babelrc Experimental flow support in perseus Nov 30, 2016
.flowconfig Ignore commoner when running Flow Dec 5, 2016
.gitattributes Enable lazy-loading for most of the widgets Jul 19, 2016
.gitignore Refactor Makefile, make `minify` target Jul 6, 2016
.gitmodules Fix the path to math-input in .gitmodules May 13, 2016
.travis.yml Enabled auto-updating of gh-pages when merging to master May 12, 2016
CONTRIBUTING.md Update CONTRIBUTING.md to say perseus is already checked out for empl… Oct 24, 2016
LICENSE.txt Add MIT License Feb 6, 2014
Makefile Experimental flow support in perseus Nov 30, 2016
README.md Update MathJax substate Jan 4, 2017
difftest.html Update references to MathJax config Jan 4, 2017
index.html Update references to MathJax config Jan 4, 2017
inputting-math.md Update inputting-math.md Jun 13, 2014
lint_blacklist.txt Display/hide keypad on input focus/blur May 13, 2016
mobile-api.md mobile-api: Fix apiOptions section Aug 11, 2015
package.json Update webpack to work with Node 7 Feb 14, 2017
perseus.sublime-project Adds perseus.sublime-project to the project. Aug 20, 2015
travis_deploy_rsa.enc Enabled auto-updating of gh-pages when merging to master May 12, 2016
watch.sh Add a `make watch` command for more quickly building files Jun 16, 2016
webpack.config.demo-perseus.js Revert "Revert "Implement content preview inside iframes with touch e… Jun 30, 2016
webpack.config.js Make make watch work Aug 18, 2016
webpack.config.node-perseus.js Define Node environment for modules required by webpack May 16, 2016

README.md

Perseus

Build Status Join the chat at https://gitter.im/Khan/perseus

Perseus is Khan Academy's new exercise question editor and renderer. It allows you to create and display interactive questions.

screenshot of Perseus

Live demo

Our test page isn't much yet, but you can check out a live demo of it here!

Getting Started

To get the dev server running locally, try make server PORT=9000 which will run the local perseus server on localhost:9000. Then visit http://localhost:9000/.

To package perseus for distribution, run make build and to package a debug-friendly build, run make debug.

Both the build and the server make targets will run npm install but you can also run it yourself to install all node dependencies.

External dependencies

Perseus makes a couple of assumptions about the environment that it's loaded into. Specifically, it expects the following libraries to be available on the global window object.

  • React
  • _ (underscore)
  • jquery
  • aphrodite
  • classnames

(See externalVals in webpack.config.js)

Also, the following global variables are used, if present:

  • Khan (warnMathJaxError & warnFont)
  • icu (a subset of the localeplanet api is depended on, as covered by icu-slim.js from our fork of localeplanet)
  • MathQuill
  • Exercises
  • KhanUtil (localeToFixed & debugLog)

(See src/perseus-env.js and src/demo-perseus.js)

Versioning

Perseus uses two types of version numbers: the version of the itemData/content that can be sent to ItemRenderer/Renderer, and the version of the api exposed through the ItemRenderer/Renderer apiOptions prop. These are set in src/version.json.

itemData versioning

Item data versioning has two subtypes of versions: a global itemDataVersion for the itemData/content format sent to ItemRenderer/Renderer, and per-widget version numbers for the options sent to each widget. All of these version numbers exist both in perseus.js and in the itemData saved to the datastore by the Perseus editor.

Each of these versions consists of a major and minor version number. A perseus version can render an itemData version iff its global itemDataVersion and each of its widget versions are greater than or equal to those sent to perseus as itemData. A major version increase will happen when the saving format of this itemData has changed. Perseus clients should not need to care about this distinction, but it is important to Perseus' implementation of backwards-compatibility.

apiOptions versioning

The version of the apiOptions prop sent to ItemRenderer or Renderer is stored on Perseus.apiVersion. A minor version increase indicates an optional additional parameter to this interface. A major version increase indicates a not-backwards-compatible change to this API. A perseus client should rely on a specific major version of perseus, and should be able to use any future minor version increase without changes, but not necessarily previous minor versions. For example, if a client begins using version 1.2, Perseus api versions 1.3 or 1.4 will work transparently, but Perseus api versions 1.0, 1.1, 2.0, or 2.2 will not work.

Contributing

See CONTRIBUTING.md for a walkthrough of how some of the Perseus code works and how to extend it.

License

MIT License