Chapter 33. Filters

AsciiDoc filters allow external commands to process AsciiDoc Paragraphs, DelimitedBlocks and Table content. Filters are primarily an extension mechanism for generating specialized outputs. Filters are implemented using external commands which are specified in configuration file definitions.

There’s nothing special about the filters, they’re just standard UNIX filters: they read text from the standard input, process it, and write to the standard output.

The asciidoc(1) command --filter option can be used to install and remove filters. The same option is used to unconditionally load a filter.

Attribute substitution is performed on the filter command prior to execution — attributes can be used to pass parameters from the AsciiDoc source document to the filter.


	Filters sometimes included executable code. Before installing a filter you should verify that it is from a trusted source.

33.1. Filter Search Paths

If the filter command does not specify a directory path then asciidoc(1) recursively searches for the executable filter command:

First it looks in the user’s $HOME/.asciidoc/filters directory.
Next the global filters directory (usually /etc/asciidoc/filters or /usr/local/etc/asciidoc) directory is searched.
Then it looks in the asciidoc(1) ./filters directory.
Finally it relies on the executing shell to search the environment search path ($PATH).

Standard practice is to install each filter in it’s own sub-directory with the same name as the filter’s style definition. For example the music filter’s style name is music so it’s configuration and filter files are stored in the filters/music directory.

33.2. Filter Configuration Files

Filters are normally accompanied by a configuration file containing a Paragraph or DelimitedBlock definition along with corresponding markup templates.

While it is possible to create new Paragraph or DelimitedBlock definitions the preferred way to implement a filter is to add a style to the existing Paragraph and ListingBlock definitions (all filters shipped with AsciiDoc use this technique). The filter is applied to the paragraph or delimited block by preceding it with an attribute list: the first positional attribute is the style name, remaining attributes are normally filter specific parameters.

asciidoc(1) auto-loads all .conf files found in the filter search paths unless the container directory also contains a file named __noautoload__ (see previous section). The __noautoload__ feature is used for filters that will be loaded manually using the --filter option.

33.3. Example Filter

AsciiDoc comes with a toy filter for highlighting source code keywords and comments. See also the ./filters/code/code-filter-readme.txt file.


	The purpose of this toy filter is to demonstrate how to write a filter — it’s much to simplistic to be passed off as a code syntax highlighter. If you want a full featured multi-language highlighter use the source code highlighter filter.

33.4. Built-in filters

The AsciiDoc distribution includes source, music, latex and graphviz filters, details are on the AsciiDoc website.

Table 33.1. Built-in filters list

Filter name	Description
music	A music filter is included in the distribution `./filters/` directory. It translates music in LilyPond or ABC notation to standard classical notation.
source	A source code highlight filter is included in the distribution `./filters/` directory.
latex	The AsciiDoc LaTeX filter translates LaTeX source to an image that is automatically inserted into the AsciiDoc output documents.
graphviz	Gouichi Iisaka has written a Graphviz filter for AsciiDoc. Graphviz generates diagrams from a textual specification. Gouichi Iisaka’s Graphviz filter is included in the AsciiDoc distribution. Here are some AsciiDoc Graphviz examples.

33.5. Filter plugins

Filter plugins are a mechanism for distributing AsciiDoc filters. A filter plugin is a Zip file containing the files that constitute a filter. The asciidoc(1) --filter option is used to load and manage filer plugins.

Filter plugins take precedence over built-in filters with the same name.
By default filter plugins are installed in $HOME/.asciidoc/filters/<filter> where <filter> is the filter name.