Using Custom Data Folders and Files
Notes on how to make Highlight CLI use custom lang defs, themes and plug-ins.
Table of Contents
- Highlight Configuration-Search Paths
- Debugging The Configuration Paths
- Linux and Mac References
- Windows Tutorial
- Reference Links
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
/plugins/ subfolders in the main installation folder) — or even a custom "
There are three different ways to achieve this:
- Use the
--data-dir=<directory>command line option.
- Use the
--config-file=<file>command line 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.
||overrides Highlight defaults.|
||new scripts only.|
||bypasses configurations altogether.|
Highlight Configuration-Search Paths
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).
||Highlight directory||path of Highlight executable|
||location of "
|current directory||current directory||(fallback)|
These folders are expected to mirror the folders structure found in Highlight’s setup folder — ie: to contain subfolder with the corresponding scripts:
*.langfiles (language definitions)
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).
Search Paths Priorities
--data-dir option will always have a higher precedence, and any matching configuration scripts find therein will prevail over other paths.
-D, --data-dir=<directory> set path to data directory
On the other hand, the path of
HIGHLIGHT_DATADIR env var will always come after Highlight’s path when no
--data-dir option is specified, so it won’t override any same-named scripts present therein, nor the
filetypes.conf file — effictely leaving
--data-dir as the only viable option to override existing configuration scripts (unless also the
--data-dir option is specified, and the path it points to doesn’t override the configuration script of
As for new language definitions, themes or plugins 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.
Linux and Mac References
Configuration scripts are searched in the following directories:
- path of
- path of
/etc/highlight/(location of "
- current working directory (fallback)
On Windows OS, Highlight searches for configuration scripts in these folders:
- path of
--data-diroption (if present), otherwise Highlight’s path
- path of
- Highlight’s path
- current folder/path of invocation script
We shall now provide some examples covering different working scenearios. Here I'm assuming you have installed Highlight on your Windows machine AND that you've added Highlight directory (
%ProgramFiles%\Highlight\) to the system PATH.
Viewing Your Current Configuration
You can always use the
--print-config option to check your current Highlight settings. E.g., on Windows:
D:\some\path>highlight --print-config Config file search directories: C:\Program Files\Highlight\ C:\Program Files\Highlight\ Filetype config file: C:\Program Files\Highlight\filetypes.conf
You might wonder why the path of Highlight installation directory is being shown twice. The first entry actually represents the
--data-dir option — if no
--data-dir option is specified, the Highlight directory will be used as a fallback default value:
Config file search directories: C:\Program Files\Highlight\ <-- path of `--data-dir` (fallback default) C:\Program Files\Highlight\ <-- Highlight directory
This will become clearer when we'll look the
--data-dir option, further on.
Custom Folders via
Let's say we're working on a project in
D:\myproject\ and want Highlight to use some customized scripts and settings from the
myDataDir subfolder via the
--data-dir command line option.
We'll first use
--print-config to verify how configurations will be read:
D:\myproject>highlight --print-config --data-dir=%CD%\myDataDir Config file search directories: D:\myproject\myDataDir\ C:\Program Files\Highlight\ Filetype config file: D:\myproject\myDataDir\filetypes.conf
We can see that
myDataDir is being given top priority for loading configuration scripts, and that
filetypes.conf configuration file inside it is being used as the reference configuration file, effectively overriding Highlight default configuration.
This means that any syntaxes inside
myDataDir\langDefs will override the syntaxes in Highlight installation folder, and the same goes for themes and plugins.
Custom Folders via
Let's now try to use the
HIGHLIGHT_DATADIR env var instead, pointing to the
HL_DATADIR subfolder. We first set the env var:
and check it's pointing to the expected path:
D:\myproject>echo %HIGHLIGHT_DATADIR% D:\myproject\HL_DATADIR\
OK. Let's now query Highlight configuration status:
D:\myproject>highlight --print-config Config file search directories: C:\Program Files\Highlight\ D:\myproject\HL_DATADIR\ C:\Program Files\Highlight\ Filetype config file: C:\Program Files\Highlight\filetypes.conf
As you can see, the
HIGHLIGHT_DATADIR folder is given lower priority than Highlight installation directory, and the
filetypes.conf therein is not overriding Highlight default config file. This means that any same-named language definitions, themes or plugins in the directory of
HIGHLIGHT_DATADIR will not override Highlight default scripts. But any new scripts therein will become available to Highlight.
The above should clarify why Highlight uses the Highlight directory as the fallback value for
--data-dir when none is specified by the user:
Config file search directories: C:\Program Files\Highlight\ <-- path of `--data-dir` (fallback default) D:\myproject\MY_DATADIR\ <-- path of HIGHLIGHT_DATADIR C:\Program Files\Highlight\ <-- Highlight directory
And now let's see what happens if we combine both
D:\myproject>highlight --print-config --data-dir=%CD%\myDataDir Config file search directories: D:\myproject\myDataDir\ D:\myproject\HL_DATADIR\ C:\Program Files\Highlight\ Filetype config file: D:\myproject\myDataDir\filetypes.conf
As expected, now the folder pointed by
--data-dir gets higher priority, and the
filetypes.conf inside it will be used by Highlight. But now the
HIGHLIGHT_DATADIR folder is given higher priority over Highlight installation directory, which means that langDefs, themes and plugins in the
HIGHLIGHT_DATADIR directory can now override same-named scripts in Highlight install directory (unless also present inside the
Ultimately, which configuration files will be used depends largely on the contents of the custom folders. In the above example, if the
myDataDir folder doesn't contain a
filetypes.conf file, then
HL_DATADIR\filetypes.conf will be used (if present), overriding Highlight installation defaults.