Pete,
I head from Jason that you're experimenting with using
Asciidoctor to generate the HTML for some of the guides. I'm
thrilled to here that. It also prompted me to review how
Asciidoctor handles these documents. I processed the following
guide:
I've come up with some observations and recommendations. But
first, some general advice for using Asciidoctor.
If you are using Asciidoctor view the API, you'll want to
disable SafeMode (since that's not relevant for builds) and
enable full document output:
Asciidoctor.render_file('guide.asciidoc', :safe =>
Asciidoctor::SafeMode::UNSAFE, :header_footer => true,
:in_place => true)
The :in_place option mimics the behavior of AsciiDoc of
rendering to file w/ the same basename as the source file.
Coming in 0.1.0 is a cli, named asciidoctor. You'll be able
to use that as a drop-in replacement for the asciidoc command.
Moving on to the feedback.
* AsciiDoc clips the label of the following xref (because
of the comma in the label), whereas Asciidoctor gets it right:
<<GettingStarted-on_linux, Installing and starting the
JBoss server on Linux, Unix or Mac OS X>>
* Asciidoctor does not process the anchor:name[] macro, use
[[name]] instead (best is to put it above a section title)
* Asciidoctor does not render callout numbers as icons (I
recommend we use FontAwesome or CSS to accomplish this markup)
* Use a conditional block to setup the source-highlighter
when using Asciidoctor:
ifdef::asciidoctor[]
:source-highlighter: highlightjs
:highlightjs-theme: github
endif::asciidoctor[]
Another option for source highlighting is CodeRay, which is
more or less like Pygments in that it formats the code directly.
You'll need to gem install coderay, then:
ifdef::asciidoctor[]
:source-highlighter: coderay
endif::asciidoctor[]
I noticed a couple of places where Asciidoctor was
incorrectly parsing the text. I fixed them and pushed the
changes. They will likely make it into 0.1.0.
If you have any questions, or have any features you'd like to
see, let me know or just post the feedback in the Asciidoctor
issue tracker [1].
Cheers!
_______________________________________________
jdf-dev mailing list
jdf-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/jdf-dev