Building and Testing¶
To use Highlight.js it is first necessary to build it for the environment where you plan to execute it: the browser, the Node.js server, etc.
Often when contributing a pull-request it’s sufficient to build and test only the Node.js build. Our CI process will guarantee the browser build tests are all still green if you don’t run them during development.
npm run build
npm run test
The browser library must be built and tested separately:
npm run build-browser
npm run test-browser
script, make sure to have node installed and run
npm install to get the
The tool is located in
tools/build.js. A few useful examples:
Build for a browser using only common languages:
node tools/build.js :common
Build for node.js including all available languages:
node tools/build.js -t node
Build two specific languages for debugging, skipping compression in this case:
node tools/build.js -n python ruby
On some systems the node binary is named
nodejs; simply replace
nodejs in the examples above if that is the case.
The full option reference is available with the usual
The build result will be in the
The usual approach to debugging and testing a language is first doing it
visually. You need to build highlight.js with only the language you’re working
on (without compression, to have readable code in browser error messages) and
then use the Developer tool in
tools/developer.html to see how it highlights
a test snippet in that language.
A test snippet should be short and give the idea of the overall look of the language. It shouldn’t include every possible syntactic element and shouldn’t even make practical sense.
After you satisfied with the result you need to make sure that language detection still works with your language definition included in the whole suite.
Testing is done using Mocha and the
files are found in the
test/ directory. You can use the node build to
run the tests from the command line with
npm test after building. (Using
npm run build_and_test you can build and then test with one command.)
Note: for Debian-based machine, like Ubuntu, you might need to create an alias or symbolic link for nodejs to node. The reason for this is the dependencies that are requires to test highlight.js has a reference to “node”.
Place the snippet you used inside the browser in
test/detect/<language>/default.txt, build the package with all the languages
for node and run the test suite. If your language breaks auto-detection, it
should be fixed by improving relevance, which is a black art
in and of itself. When in doubt, please refer to the discussion group!
You can also provide additional markup tests for the language to test isolated
cases of various syntactic construct. If your language has 19 different string
literals or complicated heuristics for telling division (
/) apart from
/ .. /) – this is the place.
A test case consists of two files:
test/markup/<language>/<test_name>.txt: test code
test/markup/<language>/<test_name>.expect.txt: reference rendering
To generate reference rendering use the Developer tool located at
tools/developer.html. Make sure to explicitly select your language in the
drop-down menu, as automatic detection is unlikely to work in this case.
Building and Testing with Docker¶
If you don’t want to install dependencies on your system, you can use the included Dockerfile to build a container that will add the source code and then deploy a web server for you to preview it. Specifically, after you finish with your changes you can build the container from the root of the repository:
docker build -t highlight-js .
And then run the container. You will need to expose port 80 on the host for the web interface, and note that we are running it in detached (-d) mode.
docker run -d --name highlight-js --rm -p 80:80 highlight-js
If your preference is for another port, you can do that too:
docker run -d --name highlight-js --rm -p 80:8080 highlight-js
Or you can skip binding a port if your intention is to interactively shell into the container to use it as a development environment.
docker run -d --name highlight-js --rm highlight-js
Whatever you choose, you can use docker ps to ensure that it’s running.
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
0e15a7c99adf highlight-js "docker-entrypoint.s…" 8 seconds ago Up 7 seconds 0.0.0.0:80->80/tcp highlight-js
Then, open up to http://127.0.0.1/tools/developer.html to see the developer page for preview. When you are done, clean up your container.
docker stop highlight-js
If you want a more advanced testing setup, you can bind the source folder when you run the container.
docker run -d --name highlight-js --volume $PWD/src:/var/www/html/src --rm -p 80:80 highlight-js
Then if you want to make changes, you can do so locally (the folder is bound as a volume), and execute a command to the container to trigger a rebuild:
docker exec highlight-js node tools/build.js :common
And then reload the page to see changes. When you finish, don’t forget to remove the container.