Experimental AsciiDoc support with external helpers

[anthonyfok]

Push Request: Experimental AsciiDoc support with external helpers
(Replaces my previously borked PR #823)

• Modeled after existing support for reStructuredText files

• Handles content files with extensions .asciidoc and .ad

• Pipes content through asciidoctor --safe -.
  If asciidoctor is not installed, then asciidoc --safe -.

• To make sure asciidoctor or asciidoc is found, after adding
  a piece of AsciiDoc content, run hugo with the -v flag
  and look for this message:

  INFO: 2015/01/23 Rendering with /usr/bin/asciidoctor ...
  

Caveats:

• The final "Last updated" timestamp is currently not stripped.

• When hugo is run with -v, you may see a lot of these messages

  INFO: 2015/01/23 Rendering with /usr/bin/asciidoctor ...
  

  if you have lots of *.ad or *.asciidoc files.

• Some versions of asciidoc may have trouble with its safe mode.
  To test if you are affected, try this:

  $ echo "Hello" | asciidoc --safe -
  asciidoc: ERROR: unsafe: ifeval invalid
  asciidoc: FAILED: ifeval invalid safe document
  

  If so, I recommend that you install asciidoctor instead.

Feedback and patches welcome!

Ideally, we should be using https://github.com/VonC/asciidocgo,
@VonC's wonderful Go implementation of Asciidoctor. However,
there is still a bit of work needed for asciidocgo to expose
its API so that Hugo can actually use it.

Until then, hope this "experimental AsciiDoc support through external
helpers" can serve as a stopgap solution for our community. :-)

More discussions at Issue #470 and at PR #823.

[bep]

Running with asciidoctor works fine, but there are room for fine-tuning:

1000 small pages, Blackfriday vs acsiidoctor:

0 of 1001 drafts rendered
0 future content 
1024 pages created 
4 categories created
4 series created
52 tags created
in 2499 ms

0 of 1001 drafts rendered
0 future content 
1024 pages created 
52 tags created
4 categories created
4 series created
in 77172 ms

[Fale]

The .adoc extension is very popular for asciidoc files. I would add it too :)

[anthonyfok]

Thank you for your suggestion, @Fale! The .adoc extension is now added. :-)

[Fale]

Thanks to you for the fast fix. I hope to see it in mainline soon :)

[spf13]

Merged as 358dcce

[bwklein]

@anthonyfok Is there a way to pass attributes to asciidoctor when Hugo calls for it to render content?

[anthonyfok]

Hi @bwklein,

No, not yet. There are some command-line options that are passed to asciidoctor when Hugo calls it, but it is not user-configurable, at least not yet.

If you would like this to be implemented, please open a new issue and perhaps give some example use cases, especially what command-line options you would like to be user-configurable.

Thanks!

Anthony

[bwklein]

@anthonyfok Thank you for the reply. This is a good example of how Middleman does it.
https://github.com/middleman/middleman-asciidoc

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.