Filters

By default, the preview plugin only displays a preview of HTML or XML files — and for XML files, only when they contain a processing-instruction for a stylesheet.

Filters are a way to pre-process other files than HTML or XML so they can be previewed.

Definition

Filters are defined in a special filters.ini file in the Config directory. The recommended way to open the filter configuration file is via the menu option.

Each filter is defined in its own section, so by using a section header between square brackets, followed by the language and/or file extension it should work for, and the command line to execute:

    [Filter name]
    Extension=<.ext>
    Language=<Notepad++ language name>
    Command=<command line, using %1 for the currently selected file>

To temporarily disable a filter without completely deleting is, you can start the filter name with a '-' hyphen (e.g. [-Filter name]); the plugin will then skip that filter.

Filter selection

The preview plugin decides whether or not to run each filter based on the file's extension OR the active highlighter language. The first matching filter is run, any other matching filters are ignored.

The Language field should match one of Notepad++'s syntax highlighting language names.
The Extension field may contain one or more comma-separated file extension(s).
The Filename field may contain a file mask (including wildcard characters such as * or ?; see description).

Note that at least one of these three fields must be provided, otherwise the filter will never be used.

Filter execution

When the plugin has determined that a filter should be used, it will try to run the given Command with the current file.

If there is no Command field, or it is empty, the editor's contents will be passed as-is to the preview engine. Note that this allows previewing any file format.
Otherwise, the Command will be run.

How the plugin communicates with the command depends on the presence of the %1 and %2 symbols, as follows:

If the Command field does not contain the symbol %1, then the plugin will pipe the editor's contents into the command's input stream.
Otherwise, if the editor has no changes, the filter will simply replace %1 in the Command by the full path and filename of the currently selected file name. But if the file contains changes that haven't been saved, it will write the contents to a temporary file, and replace %1 with that temporary file name.

As for the output:

If the Command field does not contain the symbol %2, then the plugin will use the command's output stream to display the preview.
If the Command field does contain the symbol %2, then the plugin will replace that by a temporary file name; and when the command finishes, it will use the contents of that file to display the preview.

Note that the output has to be a format that can be displayed by the Shell Document engine (basically, by Internet Explorer).

And last but not least, keep in mind that Notepad++ will not respond while a file command is run, so do try to keep it fast.

Example

Check out the sample filter definition in the plugin's Config directory: