Custom Data Folders

tajmone edited this page Oct 6, 2018 · 3 revisions
Highlight v3.40

Using Custom Data Folders and Files

Notes on how to make Highlight CLI use custom lang defs, themes and plug-ins.

Table of Contents


Sometime you might need Highlight to use language definitions and/or themes/plugins from some custom path, instead of Highlight’s default folder (ie: the langDefs, themes and plugins subfolders in the main installation folder) — or even a custom "filetypes.conf" file.

There are three different ways to achieve this:

  1. Set HIGHLIGHT_DATADIR environment variable.
  2. Use the --data-dir=<directory> option.
  3. Use the --config-file=<file> option.

Methods (1) and (2) leverage Highlight’s search-path list, and their effect is folder-wide; method (3) forces Highlight to disregard the search-path list and use a specific langdef or theme, and its effect is limited to a single target langdef and/or theme per invocation.

Highlight’s Configuration-Search Paths List

Here you’ll find the list of folder paths in which Highlight looks for configuration scripts for both Linux and Mac, on the one hand, and for Windows, on the other (Highlight behavior differs slightly on Windows).

These folders are expected to mirror the folders structure found in Highlight’s setup folder — ie: to contain subfolder with the corresponding scripts:

  • "/langDefs/": *.lang files (language definitions)
  • "/themes/": *.theme files (themes)
  • "/plugins/": *.lua files (plug-ins)

You can also place a custom "filetypes.conf" file in the root of these paths.

Whenever Highlight finds a configuration script matching the current requirements, it will load it from the currently searched path and stop looking. This means that you can override the required language definition but not the theme (or viceversa), as Highlight will search for each file separately (each time going again through all the folders in the search-path list).

Linux and Mac

Configuration scripts are searched in the following directories:

  1. ~/.highlight/
  2. path of HIGHLIGHT_DATADIR env var
  3. path of --data-dir option
  4. /usr/share/highlight/
  5. /etc/highlight/ (location of "filetypes.conf")
  6. current working directory (fallback)


On Windows OS, Highlight search for configuration scripts in these folders:

  1. path of --data-dir option (if present), otherwise Highlight’s path
  2. path of HIGHLIGHT_DATADIR env var
  3. Highlight’s path
  4. current folder/path of invocation script

So, the --data-dir option will always have a higher precedence, and any matching configuration scripts find therein will prevail over other paths.

On the other hand, the path of HIGHLIGHT_DATADIR env var will always come after Highlight’s path (if no --data-dir option is pecified), so it won’t override any configuration scripts present therein — effictely leaving --data-dir as the only viable option to override existing configuration scripts (unless also the --data-dir option is pecified, and the path it points to doesn’t override the configuration script of HIGHLIGHT_DATADIR’s folder).

As for new configuration scripts (ie: for which there are no same-named files present in Highlight’s subfolders), both the --data-dir option and HIGHLIGHT_DATADIR env var are viable ways to make visible to Highlight our custom scripts.

Debugging The Configuration Paths

When in doubt (or, indeed, in trouble), remember that the --print-config option is there to show you Highlight’s list of search directories:

--print-config             print path configuration

… so just append --print-config to the invocation options you’re using and you’ll be shown the exact locations Highlight is looking for configuration files, ordered by priority.

Reference Links

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.