You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
69 lines
2.8 KiB
69 lines
2.8 KiB
4 years ago
|
////
|
||
|
Included in:
|
||
|
|
||
|
- user-manual: Extensions: Extension Points
|
||
|
////
|
||
|
|
||
|
Here are the extension points that are available in Asciidoctor 0.1.4.
|
||
|
|
||
|
Preprocessor::
|
||
|
Processes the raw source lines before they are passed to the parser.
|
||
|
|
||
|
TreeProcessor::
|
||
|
Processes the [.class]#Asciidoctor::Document# (AST) once parsing is complete.
|
||
|
|
||
|
Postprocessor::
|
||
|
Processes the output after the document has been converted, but before it's written to disk.
|
||
|
|
||
|
DocinfoProcessor::
|
||
|
Adds additional content to the header or footer regions of the generated document.
|
||
|
|
||
|
Block processor::
|
||
|
Processes a block of content marked with a custom block style (i.e., `[custom]`). (similar to an AsciiDoc filter)
|
||
|
|
||
|
Block macro processor::
|
||
|
Registers a custom block macro and processes it (e.g., `gist::12345[]`).
|
||
|
|
||
|
Inline macro processor::
|
||
|
Registers a custom inline macro and processes it (e.g., `btn:[Save]`).
|
||
|
|
||
|
Include processor::
|
||
|
Processes the `include::<filename>[]` directive.
|
||
|
|
||
|
These extensions are registered per document using a callback that feels sort of like a DSL:
|
||
|
|
||
|
```ruby
|
||
|
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
|
||
|
```
|
||
|
|
||
|
CAUTION: 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 [.class]#Asciidoctor::Document# is created.
|
||
|
|
||
|
NOTE: 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.
|
||
|
|
||
|
////
|
||
|
For now, you need to use the Asciidoctor API (not the CLI) in order to register the extensions and invoke Asciidoctor.
|
||
|
Eventually, we'll be able to load extensions packaged in a RubyGem (Ruby) or JAR (Java) by scanning
|
||
|
the LOAD_PATH (Ruby) or classpath (Java), respectively.
|
||
|
We may also ship some built-in extensions that can be enabled using an attribute named `extensions`, similar to how Markdown processors work.
|
||
|
|
||
|
TIP: For those of you on the JVM, yes, you can write extensions in Java.
|
||
|
We've prototyped it and it works.
|
||
|
We're still sorting out a few technical challenges and documentation to make it completely smooth, but we'll get there.
|
||
|
For details, follow the discussion in issue {issue-ref}/79[#79].
|
||
|
////
|