patrick/KaTeX
1
0
Fork 0
mirror of https://github.com/Smaug123/KaTeX synced 2025-10-08 12:38:39 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
c71ee4bdd5439c39e78ef2e91c9a2ddb8053844f
KaTeX/CONTRIBUTING.md
ylemkimon 5f32b71c85 Use webpack to build files and webpack-dev-server for testing (#1068) 
* Create a separate entry point for webpack

Created a webpack entry point for KaTeX, which imports katex.less. As
flow[1] and jest[2] doesn't support CSS modules natively, a separate
entry point is used and it is not flowtyped.

[1] https://gist.github.com/lambdahands/d19e0da96285b749f0ef
[2] https://facebook.github.io/jest/docs/en/webpack.html

* Use webpack to build files

* Made webpack.config.js export valid webpack configuration
* Use:
browserify -> webpack
babelify -> babel-loader
UglifyJS CLI -> UglifyJsPlugin
Less CLI -> less-loader
cleancss -> cssnano in css-loader
build/fonts -> file-loader
* Inline CSS(Less) using style-loader and export them using
ExtractTextPlugin
* Add `watch` npm script calling `webpack --watch`

* Improve local testing(webpack-dev-server)

* Made webpackDevServer export a valid webpack configuration
* Compile Less and inline CSS using less-loader and style-loader
* Instead of copying files serve files from /static and use file-loader
* Remove old server.js and its dependencies

* Use webpack-dev-server in Screenshotter

* Include contrib in webpack-dev-server

+ Moved common configurations to webpack.common.js

* Rename webpackDevServer.js to webpack.dev...

to be consistent, avoid confusion with webpack-dev-server and follow
webpack configuration naming convention.

* Remove unnecessary conditional output.path

* Use map instead of reduce

+ Add comments regarding function arguments

* Remove unnecessary mkdir and clean build/* before build

* Use katex as external dependency instead of global variable in contrib

Fixes #692.

* Unblock codes as they are built as a module

* Update package-lock.json

* Add comments regarding devServer option

* Lint renamed webpack.dev.js

a0d8b33

* Export ES6 module and expose its default export

* Revert "Browserify hotfix (#1057)"

This reverts commit f6b509123b.

* Enables colors on the console when running the dev server in Screenshotter

* Add context to webpack configuration

Allows webpack to be run from other directories

* Move `rm -rf build/*` to npm scripts

* Check dependencies before build

* Move UglifyJsPlugin into config creation

* Let webpack handle ES6 modules

Do not transform modules to commonjs in Babel. However Jest doesn't not
support ES6 modules, so transfrom modules to commonjs when NODE_ENV is
`test`.

* Add documentation on testing in IE 9 and 10 using webpack-dev-server

Changed version range to include IE-compatible version
2018-01-21 19:48:25 -05:00

170 lines
7.8 KiB
Markdown
Raw Blame History

# 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 our [gitter channel](https://gitter.im/Khan/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) as
well as a page that describes how to [examine TeX commands and where to find
rules](https://github.com/Khan/KaTeX/wiki/Examining-TeX) which can be quite
useful when adding new commands. There's also a user-contributed
[preview page](http://utensil-site.github.io/available-in-katex/)
showing how KaTeX would render a series of symbols/functions (including the ones
MathJax listed in their documentation and the extra ones supported by KaTeX). 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://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](src/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
New functions should be added in [src/functions](src/functions) using
`defineFunction` from [defineFunction.js](src/defineFunction.js). Read the
comments in this file to get started. Look at
[phantom.js](src/functions/phantom.js) and
[delimsizing.js](src/functions/delimsizing.js) as examples of how to use
`defineFunction`. Notice how delimsizing.js groups several related functions
together in a single call to `defineFunction`.
The new method of defining functions combines methods that were previously
spread out over three different files [functions.js](src/functions.js),
[buildHTML.js](src/buildHTML.js), [buildMathML.js](src/buildMathML.js) into a
single file. The goal is to have all functions use this new system.
## Testing
Local testing can be done by running the webpack-dev-server using configuration
`webpack.dev.js`. Run `npm install` to install dependencies, and then `npm start`
to start the server.
This will host an interactive editor at
[http://localhost:7936/](http://localhost:7936/) to play around with and test
changes.
webpack-dev-server 2.8.0 introduced a change which included ES6 keywords `const`
and `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
by running `npm install webpack-dev-server@2.7.1`.
#### Jest tests
The JavaScript parser and some of the HTML and MathML tree
builders are tested with Jest. These tests can be run using node with
`npm run jest`. If you need to debug the tests see
[https://facebook.github.io/jest/docs/troubleshooting.html](https://facebook.github.io/jest/docs/troubleshooting.html)
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, [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 Jest tests to ensure they work.
#### Screenshot tests
To ensure the final output looks good, we screenshot different expressions.
These tests can be run by using the
[Screenshotter docker](https://github.com/Khan/KaTeX/tree/master/dockers/Screenshotter).
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](test/screenshotter/ss_data.yaml).
You can use our
[texcmp](https://github.com/Khan/KaTeX/tree/master/dockers/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.
#### Testing in other browsers
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](http://modern.ie) VMs.
## Style guide
Code
- 4 spaces for indentation
- 80 character line length
- commas last
- declare variables in the outermost scope that they are used
- camelCase for variables in JavaScript
- snake_case for variables in Python
In general, try to make your code blend in with the surrounding code.
## Pull Requests
- link back to the original issue(s) whenever possible
- new commands should be added to the [wiki](https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX)
- commits should be squashed before merging
- large pull requests should be broken into separate pull requests (or multiple logically cohesive commits), if possible
## Working with submodules
The fonts for KaTeX live in a submodule which appears in submodules/katex-fonts.
Most of the time you won't have to worry about this unless you're making
changes to fonts or switching between branches where submodules/katex0fonts
point to different commits.
If you're not familiar with submodule, it's probably easiest to get started by
adding the following aliases to your .gitconfig:
```
[alias]
# Versions of commands that handle submodules properly.
co = "!f() { git checkout \"$@\" && git submodule update --init --recursive; }; f"
p = "!f() { git pull \"$@\" && git submodule update --init --recursive; }; f"
m = "!f() { git merge \"$@\" && git submodule update --init --recursive; }; f"
gsu = "!f() { git submodule sync --recursive && git submodule update --init --recursive; }; f"
```
`git co`, `git p`, and `git m` work just like `git checkout`, `git pull`, and
`git merge` respectively but automatically update submodules. For more info
about how to use git submodules see https://chrisjean.com/git-submodules-adding-using-removing-and-updating/.
When submitting pull requests, that update katex-fonts, you'll need to submit
two pull requests: one for [KaTeX/katex-fonts](https:/github.com/KaTeX/katex-fonts) and one for [Khan/KaTeX](https://github.com/Khan/KaTeX).
## CLA
In order to contribute to KaTeX, you must first sign the CLA, found at www.khanacademy.org/r/cla
## License
KaTeX is licenced under the [MIT License](http://opensource.org/licenses/MIT).
Reference in New Issue View Git Blame Copy Permalink