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. |
If the filter command does not specify a directory path then
asciidoc(1)
recursively searches for the executable filter command:
$HOME/.asciidoc/filters
directory.
/etc/asciidoc/filters
or /usr/local/etc/asciidoc
) directory is searched.
asciidoc(1)
./filters
directory.
$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.
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.
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. |
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 |
source | A source code highlight filter
is included in the distribution |
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. |
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.
$HOME/.asciidoc/filters/<filter>
where <filter>
is the filter
name.