Experimental AsciiDoc support with external helpers #823
Conversation
See #470 * Based on 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. :-)
|
Cool. But whats missing from asciidocgo that prevent us from using it? |
|
On an added note - I think we should wait and/or make it so we can use the Go implementation. One thing is to use a Python lib for code highlighting -- but dragging some slow Ruby into the mix for the vital rendering part ... |
|
Had a quick look at the go library -- and it looks very unfinished. |
Indeed. The fork https://github.com/ciarand/asciidocgo by @ciarand has gone a bit further, but still not in a readily usable state. When a first look at it a couple months ago, it appears that @VonC has completed all the internals, but the actual external API is... not written (!) at the moment? Looks very promising, but I don't think it would be ready for Hugo v0.13. Maybe v0.14. Yes, Asciidoctor will be quite a bit slower than the rest of Hugo, but I suppose it would satisfy the many AsciiDoc fans who want to start using Hugo with AsciiDoc today. ;-) We just need a BIG DISCLAIMER in the documentation that this AsciiDoc feature is experimental and s-l-o-w, and improvement in speed are expected in future versions once asciidocgo is ready, hopefully a few months later. :-) |
|
Yeah, unfortunately I haven't had (and probably won't have) time to fix it up |
|
Thank you for your input @ciarand, and for spearheading the effort to finish the last mile for asciidocgo. Perhaps fellow Gophers would be interested in rising to the challenge to make asciidocgo complete? :-) By the way, apologies to fellow Hugo developers: I have mistakenly pushed this topic branch to the main hugo git repository, whereas I was supposed to push it to my fork and then make the pull request there. (Oops!) Sorry for my oversight. |
|
Notes for possible solutions to the caveats:
|
|
As to the topic branch: Please delete it on spf13, and push it to your own repo. That would also mean creating a new PR, but that's OK. |
|
@bjornerik: Good idea, thanks! I'll do that right away. |
|
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. |
See #470
Based on existing support for reStructuredText files
Handles content files with extensions
.asciidocand.adPipes content through
asciidoctor --safe -.If
asciidoctoris not installed, thenasciidoc --safe -.To make sure
asciidoctororasciidocis found, after addinga piece of AsciiDoc content, run
hugowith the-vflagand look for this message:
Caveats:
The final "Last updated" timestamp is currently not stripped.
When
hugois run with-v, you may see a lot of these messagesif you have lots of
*.ador*.asciidocfiles.Some versions of
asciidocmay have trouble with its safe mode.To test if you are affected, try this:
If so, I recommend that you install
asciidoctorinstead.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. :-)