////
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.
