D 2019-02-11T07:43:14.255
L Filters
N text/x-markdown
P d2e1b98b5043ba7ec8e41182b4eca87f17445248
U tinus
W 2670
# 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][1] 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. From version 1.3 of the plugin, there's a menu option to open the filter configuration file.

Each filter is defined in its own section, so by using a section header between square brackets, followed by the language 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 filter encountered is run, any other matching filters are
ignored.

* The `Extension` field should contain one or more comma-separated file extension(s).
* The `Language` field should match one of Notepad++'s syntax highlighting language names.

Note that at least one of these two 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 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. If the file hasn't been saved yet (e.g. `New 1`), or if the editor contains changes that haven't been saved, it will write the contents to a temporary file, and run the command with that temporary file.

The output of the command will then be used to display the preview. So the output has to be a format that can be displayed by the Shell Document engine, or, basically, by Internet Explorer.


## Example

Check out the [sample filter definition](artifact?ci=publish&filename=Config/PreviewHTML/filters.sample.ini) in the plugin's `Config` directory:

<iframe src="raw?ci=publish&filename=Config/PreviewHTML/filters.sample.ini&m=text/plain" style="width:98%;bottom:0px" onload="this.style.height=this.contentDocument.body.scrollHeight +'px';"></iframe>



[1]: https://en.wikipedia.org/wiki/Processing_Instruction#Examples
Z eecf68a3fa579f7e2e044c9debf6ac95