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.
24 lines
1.8 KiB
24 lines
1.8 KiB
4 years ago
|
////
|
||
|
|
Included in:
|
||
|
|
|
||
|
|
- user-manual: Extensions
|
||
|
|
////
|
||
|
|
|
||
|
|
Extensions have proven to be central to the success of AsciiDoc because they open up the language to new use cases.
|
||
|
|
However, the way extensions are implemented in AsciiDoc Python presents a number of problems:
|
||
|
|
|
||
|
|
* They are challenging to write because they work at such a low-level (read as: nasty regular expressions).
|
||
|
|
* They are fragile since they often rely on system commands to do anything significant.
|
||
|
|
* They are hard to distribute due to the lack of integration with a formal distribution system.
|
||
|
|
|
||
|
|
Asciidoctor addresses these issues by introducing a proper extension API that offers a superset of the extension points that AsciiDoc Python provides.
|
||
|
|
As a result, extensions in Asciidoctor are easier to write, more powerful, and simpler to distribute.
|
||
|
|
|
||
|
|
The goal for Asciidoctor has always been to allow extensions to be written using the full power of a programming language (whether it be Ruby, Java, Groovy or JavaScript), similar to what we've done with the backend (conversion) mechanism.
|
||
|
|
That way, you don't have to shave yaks to get the functionality you want, and you can distribute the extension using defacto-standard packaging mechanisms like RubyGems or JARs.
|
||
|
|
|
||
|
|
WARNING: The extension API in Asciidoctor is stable with the exception of inline macros.
|
||
|
|
Since inline content is not parsed until the convert phase, the inline macro processor must return converted text (e.g., HTML) rather than an AST node.
|
||
|
|
Once Asciidoctor is changed to https://github.com/asciidoctor/asciidoctor/issues/61[process inline content during the parse phase], the inline macro processor will need to return an inline node.
|
||
|
|
When that switch occurs, there will either be some sort of adapter or required migration for inline macro processors, but that has yet to be determined.
|