git.iko.soy/bat
on 3d07dec help sign in
bat/doc/assets.md
61 lines 3.6 kB history raw
1## Adding new builtin languages for syntax highlighting
3Should you find that a particular syntax is not available within `bat` and think it should be included in `bat` by default, you can follow the instructions outlined below.
5`bat` uses the excellent [syntect](https://github.com/trishume/syntect) library to highlight source
6code. As a basis, syntect uses [Sublime Text](https://www.sublimetext.com/) syntax definitions
7in the `.sublime-syntax` format.
9**Important:** Before proceeding, verify that the syntax you wish to add meets the [criteria for inclusion](#Criteria-for-inclusion-of-new-syntaxes).
111. Find a Sublime Text syntax for the given language, preferably in a separate Git repository
12 which can be included as a submodule (under `assets/syntaxes`).
142. If the Sublime Text syntax is only available as a `.tmLanguage` file, open the file in
15 Sublime Text and convert it to a `.sublime-syntax` file via *Tools* -> *Developer* ->
16 *New Syntax from XXX.tmLanguage...*. Save the new file in the `assets/syntaxes` folder.
183. Run the `assets/create.sh` script. It calls `bat cache --build` to parse all available
19 `.sublime-syntax` files and serialize them to a `syntaxes.bin` file (in this folder).
214. Re-compile `bat`. At compilation time, the `syntaxes.bin` file will be stored inside the
22 `bat` binary.
245. Use `bat --list-languages` to check if the new languages are available.
266. If you send a pull request with your changes, please do *not* include the changed `syntaxes.bin`
27 file. A new binary cache file will be created once before every new release of `bat`.
29### Troubleshooting
31Make sure that the local cache does not interfere with the internally stored syntaxes and
32themes (`bat cache --clear`).
34## Criteria for inclusion of new syntaxes
36* More than 10,000 downloads on packagecontrol.io/
38### Manual modifications
40The following files have been manually modified after converting from a `.tmLanguage` file:
42* `Apache.sublime_syntax`=> removed `.conf` and `.CONF` file types.
43* `Dart.sublime-syntax` => removed `#regex.dart` include.
44* `INI.sublime-syntax` => added `.hgrc`, `hgrc`, and `desktop` file types and support for comments after section headers
45* `Org mode.sublime-syntax` => removed `task` file type.
46* `SML.sublime_syntax` => removed `ml` file type.
47* `Robot.sublime_syntax` => changed name to "Robot Framework"
49### Non-submodule additions
51* `Assembly (x86_64)` has been manually added from https://github.com/13xforever/x86-assembly-textmate-bundle due to `git clone` recursion problems
52* `Nim.sublime-syntax` has been added manually from https://github.com/getzola/zola/blob/master/sublime_syntaxes/Nim.sublime-syntax as there was no suitable Git repository for it. The original syntax seems to originate from https://github.com/Varriount/NimLime
53* `Rego.sublime-syntax` has been added manually from https://github.com/open-policy-agent/opa/blob/master/misc/syntax/sublime/rego.sublime-syntax
54 as it is not kept in a standalone repository. The file is generated from
55 https://github.com/open-policy-agent/opa/blob/master/misc/syntax/textmate/Rego.tmLanguage
56* `SML.sublime_syntax` has been added manually from
57 https://github.com/seanjames777/SML-Language-Definitiona as it is not
58 kept in a standalone repository. The file generated is from
59 https://github.com/seanjames777/SML-Language-Definition/blob/master/sml.tmLanguage
60* `Cabal.sublime_syntax` has been added manually from
61 https://github.com/SublimeHaskell/SublimeHaskell/ - we don't want to include the whole submodule because it includes other syntaxes ("Haskell improved") as well.