diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..55e3bc9e2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,107 @@ +# Contributing to KaTeX + +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 the [#katex room on +freenode](http://webchat.freenode.net/?channels=katex). + +## Helpful contributions + +If you'd like to contribute, try contributing new symbols or functions that +KaTeX doesn't currently support. The wiki has a page which lists [all of the +supported +functions](https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX). You +can check there to see if we don't support a function you like, or try your +function in the interactive demo at +[http://khan.github.io/KaTeX/](http://khan.github.io/KaTeX/). + +#### Single symbols + +There are many individual symbols that KaTeX doesn't yet support. Read through +the [symbols.js](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](http://fiddle.jshell.net/YpqVp/41/show/). + +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 `\neq`, look +for `=`). 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. + +Once your symbol works, check the JavaScript console to make sure you don't get +a message like "Can't find character metrics for _" when you render your symbol. +If you do, check out [extract_ttfs.py](metrics/extract_ttfs.py). + +#### Adding new functions + +Most functions are handled in the [functions.js](functions.js) file. Read the +comments in there to get started. If the function you want to add has similar +output to an existing function, see if you can add a new line to that file to +get it to work. + +If your function isn't similar to an existing function, you'll need to add a +line to `functions.js` as well as adding an output function in +[buildTree.js](buildTree.js). + +## Testing + +Local testing can be done by running the node server in `server.js`. Run `make +setup` to insteall dependencies, and then `make serve` to start the server. + +This will host an interactive editor at +[http://localhost:7936/](http://localhost:7936/) to play around with and test +changes. + +#### Jasmine tests + +The JavaScript parser and some of the tree +builder is tested with Jasmine. These tests can be run either using node with +`make test`, or in the browser by visiting +[http://localhost:7936/test/test.html](http://localhost:7936/test/test.html). + +The Jasmine tests should be run after every change, even the addition of small +symbols. However, [Travis](https://travis-ci.org/Khan/KaTeX/) will run these +tests when you submit a pull request, in case you forget. + +If you make any changes to Parser.js, add jasmine tests to ensure they work. + +#### Huxley tests + +To ensure the final output looks good, we use +[Huxley](https://github.com/chenglou/node-huxley) tests, which screenshot +different expressions. These tests can be run by using the [Huxley +docker](https://github.com/Khan/KaTeX/tree/master/dockers/HuxleyTests). + +The Huxley 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 huxley test. See +[Huxleyfile.json](test/huxley/Huxleyfile.json). + +#### Testing in other browsers + +KaTeX supports all major browsers, including IE 8 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 8, using [modern.ie](http://modern.ie) VMs. + +## Style guide + +Code + + - 4 spaces for indentation + - 80 character line length + - commas last + +In general, try to make your code blend in with the surrounding code. + +## License + +KaTeX is licenced under the [MIT License](http://opensource.org/licenses/MIT). \ No newline at end of file diff --git a/README.md b/README.md index 49ffcd2ed..c2277c0ab 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,42 @@ -# KaTeX [![Build Status](https://travis-ci.org/Khan/KaTeX.svg?branch=master)](https://travis-ci.org/Khan/KaTeX) +# [KaTeX](http://khan.github.io/KaTeX/) [![Build Status](https://travis-ci.org/Khan/KaTeX.svg?branch=master)](https://travis-ci.org/Khan/KaTeX) -Fast math! +KaTeX is a fast, easy-to-use JavaScript library for TeX math rendering on the web. -To run locally --------------- - make setup - make serve + * **Fast:** KaTeX renders its math synchronously and doesn't need to reflow the page. See how it compares to a competitor in [this speed test](http://jsperf.com/katex-vs-mathjax/). + * **Print quality:** KaTeX’s layout is based on Donald Knuth’s TeX, the gold standard for math typesetting. + * **Self contained:** KaTeX has no dependencies and can easily be bundled with your website resources. + * **Server side rendering:** KaTeX produces the same output regardless of browser or environment, so you can pre-render expressions using Node.js and send them as plain HTML. -* [Test page](http://localhost:7936/) -* [Unit tests](http://localhost:7936/test/test.html) +KaTeX supports all major browsers, including Chrome, Safari, Firefox, Opera, and IE 8 - IE 11. -License -------- -[MIT License](http://opensource.org/licenses/MIT) +## Usage + +Download the built files from [the releases page](https://github.com/khan/katex/releases). Include the `katex.min.js` and `katex.min.css` files on your page: + +```html + + +``` + +Call `katex.render` with a TeX expression and a DOM element to render into: + +```js +katex.render("c = \\pm\\sqrt{a^2 + b^2}", element); +``` + +To generate HTML on the server, you can use `katex.renderToString`: + +```js +var html = katex.renderToString("c = \\pm\\sqrt{a^2 + b^2}"); +// '...' +``` + +Make sure to include the CSS and font files, but there is no need to include the JavaScript. + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) + +## License + +KaTeX is licenced under the [MIT License](http://opensource.org/licenses/MIT).