language-contribution.rst 2.4 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677
  1. Language contributor checklist
  2. ==============================
  3. 1. Put language definition into a .js file
  4. ------------------------------------------
  5. The file defines a function accepting a reference to the library and returning a language object.
  6. The library parameter is useful to access common modes and regexps. You should not immediately call this function,
  7. this is done during the build process and details differ for different build targets.
  8. ::
  9. function(hljs) {
  10. return {
  11. keywords: 'foo bar',
  12. contains: [ ..., hljs.NUMBER_MODE, ... ]
  13. }
  14. }
  15. The name of the file is used as a short language identifier and should be usable as a class name in HTML and CSS.
  16. 2. Provide meta data
  17. --------------------
  18. At the top of the file there is a specially formatted comment with meta data processed by a build system.
  19. Meta data format is simply key-value pairs each occupying its own line:
  20. ::
  21. /*
  22. Language: Superlanguage
  23. Requires: java.js, sql.js
  24. Author: John Smith <email@domain.com>
  25. Contributors: Mike Johnson <...@...>, Matt Wilson <...@...>
  26. Description: Some cool language definition
  27. */
  28. ``Language`` — the only required header giving a human-readable language name.
  29. ``Requires`` — a list of other language files required for this language to work.
  30. This make it possible to describe languages that extend definitions of other ones.
  31. Required files aren't processed in any special way.
  32. The build system just makes sure that they will be in the final package in
  33. ``LANGUAGES`` object.
  34. The meaning of the other headers is pretty obvious.
  35. 3. Create a code example
  36. ------------------------
  37. The code example is used both to test language detection and for the demo page
  38. on https://highlightjs.org/. Put it in ``test/detect/<language>/default.txt``.
  39. Take inspiration from other languages in ``test/detect/`` and read
  40. :ref:`testing instructions <basic-testing>` for more details.
  41. 4. Write class reference
  42. ------------------------
  43. Class reference lives in the :doc:`CSS classes reference </css-classes-reference>`..
  44. Describe shortly names of all meaningful modes used in your language definition.
  45. 5. Add yourself to AUTHORS.*.txt and CHANGES.md
  46. -----------------------------------------------
  47. If you're a new contributor add yourself to the authors list.
  48. Also it will be good to update CHANGES.md.
  49. 6. Create a pull request
  50. ------------------------
  51. Send your contribution as a pull request on GitHub.