nanoc/nanoc — pull request #394 by ddfreyne (2014-02-17 22:46:36+00:00)
Title: Add Asciidoctor filter

This adds a filter for [Asciidoctor](http://asciidoctor.org/), which is a nice and flexible Ruby implementation of [AsciiDoc](http://www.methods.co.nz/asciidoc/).

### Neat stuff you can do with it

You can extract AsciiDoc metadata into items during preprocessing:

```ruby
preprocess do
@items.each do |item|
case item[:extension]
when 'adoc', 'asciidoc'
Asciidoctor::Document.new(item.raw_content).attributes.each_pair do |k,v|
item[k.to_sym] = v
end
end
end
end
```

### Why no `nanoc-asciidoctor` gem?

nanoc 4.0 will have a much more modular architecture where each filter and helper lives in its own repository and gem. Unfortunately, nanoc 4.0 is a long way off, and I believe it is better to continue with the current approach and add new features directly into the nanoc repository/gem itself.

This right here unfortunately contradicts what I’ve been saying in #385, #386 and #388. (Sorry.) I feel this needs more discussion. We have two choices:

* Include this change, as well as the other three ones mentioned above, in nanoc 3.7. The advantage of this is that we don’t change our policy.

* Create separate repositories and gems for each filter/helper/etc. The disadvantage is that some things are very hard to extract (e.g. commands). Extracting them without letting `nanoc` depend on them will break backwards compatibility, but letting `nanoc` depend on 30 other gems is also ridiculous.