-
Notifications
You must be signed in to change notification settings - Fork 0
Does Asciidoctor support AsciiDoc .conf files?
No, Asciidoctor does not honor AsciiDoc configuration files (e.g., asciidoc.conf). Even though the mechanism for configuring AsciiDoc is powerful, it’s not even slightly approachable (as the endless stream of questions on the mailinglist proves) and we don’t want to carry over the legacy (or stigma) of those yak clippers into Asciidoctor. In short, we’re fortunate AsciiDoc lets us configure the daylights out of it, but we can do better.
Asciidoctor is going to offer a cleaner and more powerful way to extend and configure AsciiDoc processing. And porting the logic from your AsciiDoc configuration files should be straightforward since you get to use a real programming language!
I’ll go over the extension points and where we are with them atm.
Custom output (or backends) are written in Asciidoctor using Tilt-supported templates. Options include ERB, Haml and Slim. You can find implementations of the docbook45 and html5 backends in ERB, Haml and Slim in the asciidoctor-backends repository, as well as backends for several HTML 5-based presentation engines.
This is where most of the former AsciiDoc configuration will go, if not all of it.
Most of the configuration in AsciiDoc happens through attributes. Instead of using a configuration file, you can simply pass these configuration settings as attributes to the Asciidoctor API or asciidoctor command (e.g., figure-caption, listing-caption, etc).
In the future, I plan to support a yaml (and/or toml and/or json) configuration file for passing configuration and attribute overrides to the processor. That may happen in the next version or the one after.
Certain macros in AsciiDoc lend themselves to custom behavior. One example is the include::[] macro. Being able to customize how this macro is handled could offer a nice time saver for writers. They would be able to use it to state the intent of including the file, but the actual resolution of the file or what is included could be decorated in document production. Asciidoctor 0.1.4 will offer a way to plug one or more custom Ruby classes to handle the include::[] macro.
The holy grail of AsciiDoc (and lightweight markup) is the ability to introduce custom syntax. Similar to the include::[] macro handler, Asciidoctor 0.1.4 (or the version after) will offer a way to plug in one or more custom Ruby classes to handle custom syntax. The custom syntax can be a block macro, a delimited block or an inline macro.
We’re definitely looking for feedback and/or input on these features in Asciidoctor, so I encourage you to post anything that comes to mind to the Asciidoctor list at http://discuss.asciidoctor.org or the issue tracker at https://github.com/asciidoctor/asciidoctor/issues. Nothing is set in stone :)