Perseus is Khan Academy's new exercise question editor and renderer.
Clone or download
alopatin Merge pull request #109 from Khan/link-to-perseus-configured
README: Add a link to perseus-configured
Latest commit 0e82a08 Jan 20, 2018
Permalink
Failed to load latest commit information.
.arcanist_extension/FlowTestEngine Experimental flow support in perseus Nov 30, 2016
build Build perseus Nov 3, 2017
flow-typed [highlighting] i18n for tooltip text Apr 26, 2017
fonts Update proxima nova font symlinks May 17, 2017
hubble @ e485987 [multirenderer] multi-editor UI: add, remove, and move array elements Dec 13, 2016
images Update spinner.gif and rebuild perseus Apr 14, 2017
jest Fix validation for answers that include percent signs Mar 2, 2017
kmath @ 92454b1 substate kmath Feb 19, 2015
lib Update to React 15 in Perseus Mar 27, 2017
math-input @ 102c0d3 Substate `math-input` Jul 17, 2017
node Implement ArticleDiff, improve ItemDiff Apr 4, 2017
node_modules Add fake react-addons-test-utils file Mar 29, 2017
react-components @ fee9ceb [cp article-align] Fix some small annoyances with the local article e… Oct 11, 2017
simple-markdown @ 27d1bc0 Substate react-components and simple-markdown. Sep 30, 2015
src Explicitly set correctness in radio transform. Nov 3, 2017
stylesheets Enable MC rationales in the editor Oct 18, 2017
.arcconfig Experimental flow support in perseus Nov 30, 2016
.arclint Fix lint config in Perseus Jun 1, 2016
.babelrc Fix perseus babel packaging Aug 17, 2017
.flowconfig Ignore commoner when running Flow Dec 5, 2016
.gitattributes Update to React 15 in Perseus Mar 27, 2017
.gitignore Gorgon linter engine for Perseustree-transformer.js class for travers… Jun 20, 2017
.gitmodules Fix the path to math-input in .gitmodules May 13, 2016
.travis.yml Fix travis build by changing node version Aug 22, 2017
CONTRIBUTING.md Update CONTRIBUTING.md Jan 19, 2018
LICENSE.txt Add MIT License Feb 6, 2014
Makefile Fix demo perseus bundle Aug 24, 2017
README.md Merge pull request #109 from Khan/link-to-perseus-configured Jan 20, 2018
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 Fix perseus babel packaging Aug 17, 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 Modify ./watch.sh so it also rebuilds frame-perseus.js May 4, 2017
webpack.config.demo-perseus.js Fix perseus demo loading of extra widgets Aug 24, 2017
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

As of January 2018 this repo is no longer under active development. It will, however, remain open source.

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. (If any of them change in a backwards-incompatible way, you'll likely need to bump the Perseus major version -- see the "Versioning" section below.)

  • 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)
  • KaTeX

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

For an example of supplying these dependencies, or to get an npm package of perseus with these dependencies built-in, see perseus-configured

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.

Mobile versioning

The KA mobile apps are also clients of Perseus, and the way that Perseus is integrated into the apps requires that we enforce some additional versioning constraints. For specifics, check out the Forge page.

Contributing

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

License

MIT License