Asciidoctor provides the following extension points:
Processes the raw source lines before they are passed to the parser. See Preprocessor Example.
- Tree processor
Processes the Asciidoctor::Document (AST) once parsing is complete. See Tree Processor Example.
Processes the output after the document has been converted, but before it’s written to disk. See Postprocessor Example.
- Docinfo Processor
Adds additional content to the header or footer regions of the generated document. See Docinfo Processor Example.
- Block processor
Processes a block of content marked with a custom block style (i.e.,
[custom]). (similar to an AsciiDoc filter) See Block Processor Example.
- Block macro processor
Registers a custom block macro and processes it (e.g.,
gist::12345). See Block Macro Processor Example.
- Inline macro processor
Registers a custom inline macro and processes it (e.g.,
Save). See Inline Macro Processor Example.
- Include processor
include::<filename>directive. See Include Processor Example.
There are additional extension examples in the Asciidoctor extensions lab.
These extensions are registered per document using a callback that feels like a DSL:
Asciidoctor::Extensions.register do |document| preprocessor FrontMatterPreprocessor tree_processor ShellSessionTreeProcessor postprocessor CopyrightFooterPostprocessor docinfo_processor TrackingCodeDocinfoProcessor if document.basebackend? 'html' block ShoutBlock block_macro GistBlockMacro if document.basebackend? 'html' inline_macro ManInlineMacro include_processor UriIncludeProcessor end
|Extension classes must be defined outside of the register block. Once an extension class is registered, it is frozen, preventing further modification. If you define an extension class inside the register block, it will result in an error on subsequent invocations.|
You can register more than one processor of each type, though you can only have one processor per custom block or macro. Each registered class is instantiated when the Asciidoctor::Document is created.
|There is currently no extension point for processing a built-in block, such as a normal paragraph. Look for that feature in a future Asciidoctor release.|