Pete,<div><br></div><div>I head from Jason that you&#39;re experimenting with using Asciidoctor to generate the HTML for some of the guides. I&#39;m thrilled to here that. It also prompted me to review how Asciidoctor handles these documents. I processed the following guide:</div>

<div><br></div><div><a href="https://github.com/jboss-jdf/jboss-as-quickstart/tree/master/guide">https://github.com/jboss-jdf/jboss-as-quickstart/tree/master/guide</a></div><div><br></div><div>I&#39;ve come up with some observations and recommendations. But first, some general advice for using Asciidoctor.</div>

<div><br></div><div>If you are using Asciidoctor view the API, you&#39;ll want to disable SafeMode (since that&#39;s not relevant for builds) and enable full document output:</div><div><br></div><div>Asciidoctor.render_file(&#39;guide.asciidoc&#39;, :safe =&gt; Asciidoctor::SafeMode::UNSAFE, :header_footer =&gt; true, :in_place =&gt; true)</div>

<div><br></div><div>The :in_place option mimics the behavior of AsciiDoc of rendering to file w/ the same basename as the source file.</div><div><br></div><div>Coming in 0.1.0 is a cli, named asciidoctor. You&#39;ll be able to use that as a drop-in replacement for the asciidoc command.</div>

<div><br></div><div>Moving on to the feedback.</div><div><br></div><div><div>* AsciiDoc clips the label of the following xref (because of the comma in the label), whereas Asciidoctor gets it right:</div><div><br></div><div>

  &lt;&lt;GettingStarted-on_linux, Installing and starting the JBoss server on Linux, Unix or Mac OS X&gt;&gt;</div><div><br></div><div>* Asciidoctor does not process the anchor:name[] macro, use [[name]] instead (best is to put it above a section title)</div>

<div>* Asciidoctor does not render callout numbers as icons (I recommend we use FontAwesome or CSS to accomplish this markup)</div><div>* Use a conditional block to setup the source-highlighter when using Asciidoctor:</div>

<div><br></div><div>ifdef::asciidoctor[]</div><div>:source-highlighter: highlightjs</div><div>:highlightjs-theme: github</div><div>endif::asciidoctor[]</div></div><div><br></div><div>Another option for source highlighting is CodeRay, which is more or less like Pygments in that it formats the code directly. You&#39;ll need to gem install coderay, then:</div>

<div><br></div><div><div>ifdef::asciidoctor[]</div><div>:source-highlighter: coderay</div><div>endif::asciidoctor[]</div></div><div><br></div><div>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.</div>

<div><br></div><div>If you have any questions, or have any features you&#39;d like to see, let me know or just post the feedback in the Asciidoctor issue tracker [1].</div><div><br></div><div>Cheers!</div><div><div><br></div>

<div>-Dan</div><div><br></div><div>[1] <a href="https://github.com/erebor/asciidoctor/issues?state=open">https://github.com/erebor/asciidoctor/issues?state=open</a><br clear="all"><div><br></div>-- <br><div>Dan Allen</div>

Principal Software Engineer, Red Hat | Author of Seam in Action<br>Registered Linux User #231597<br><br><div><a href="http://google.com/profiles/dan.j.allen" target="_blank">http://google.com/profiles/dan.j.allen</a><br>
<a href="http://mojavelinux.com" target="_blank">http://mojavelinux.com</a><br>
<a href="http://mojavelinux.com/seaminaction" target="_blank">http://mojavelinux.com/seaminaction</a><br></div>
</div></div>