@aalmiray#devoxx #asciidoctor_tips

10 Useful Asciidoctor TipsAndres Almiray

Canoo Engineering AG

@aalmiray#devoxx #asciidoctor_tips

@aalmiray#devoxx #asciidoctor_tips

#1 Live Reload + Browser Extension

• http://livereload.com/ !

• https://github.com/asciidoctor/asciidoctor-chrome-extension !

• https://github.com/asciidoctor/asciidoctor-firefox-addon

@aalmiray#devoxx #asciidoctor_tips

#2 Build Tool integration

• https://github.com/asciidoctor/asciidoctor-maven-plugin !

• https://github.com/asciidoctor/asciidoctor-gradle-plugin !

• https://github.com/aalmiray/livereload-gradle-plugin

@aalmiray#devoxx #asciidoctor_tips

#3 Provide a _links.adoc file

• Use an attribute per link

• Include the _links.adoc file at the beginning of your index file

//  _links.adoc  :link_gradle:  http://www.gradle.org/[Gradle,  window="_blank"]  :link_maven:  http://maven.apache.org/[Maven,  window="_blank"]

//  index.adoc  include::_links.adoc[]  !Asciidoctor  has  great  integration  with  {link_gradle}  and  {link_maven}.

@aalmiray#devoxx #asciidoctor_tips

#4 Blank lines at top and bottom

• Simplifies including files into others

//  without  blank  lines  //  index.adoc  !include::chapter1.adoc[]  !include::chapter2.adoc[]  !include::chapter3.adoc[]

//  with  blank  lines  //  index.adoc  !include::chapter1.adoc[]  include::chapter2.adoc[]  include::chapter3.adoc[]

@aalmiray#devoxx #asciidoctor_tips

#5 Comment your documentation!

• Yes, comments on documentation ;-)

=  Chapter  Title  The  following  chapter  discusses  lorem  ipsum  dolor  sit  amet  consecutur  ad  nauseam.  //  IDEA:  insert  a  lorem  ipsum  generator  here?  !Lorem  ipsum  dolor  sit  amet  consecutur.  Lorem  ipsum  dolor  sit  amet  consecutur.  Lorem  ipsum  dolor  sit  amet  consecutur.  Lorem  ipsum  dolor  sit  amet  consecutur.  !////  Why  build  a  custom  lorem-­‐ipsum  extension  when  copy&paste  is  so  cheap?  No  need  to  tire  those  cell  brains.  Oh  look,  beer!  ////

@aalmiray#devoxx #asciidoctor_tips

#6 Use conditional blocks

• ifdef::attribute_name[] checks if attribute has a value

• ifndef::attribute_name[] performs the opposite check

• ifeval::[{attribute_name} > 2] evaluates the attribute !

• You can surround blocks if ifdef/ifndef/ifeval & endif

• These are great for conditionally rendering content based on build variables (see tip #2).

@aalmiray#devoxx #asciidoctor_tips

#7 Callouts in paragraphs

• Apply the following inside any paragraph [conum,data-value=2]_2_where 2 can be any number !

• Reverse engineered from<em class="conum">2</em>

@aalmiray#devoxx #asciidoctor_tips

#8 Include Raw Content

• Either use the pass:[] macro or the ++++ block

pass:[<iframe  src=“http://secr.et/not/a/malicious/page/honest.html”></iframe>]  !++++  <script  type="text/javascript">  var  pageTracker  =  _gat._getTracker("XX-­‐123456-­‐1");  pageTracker._initData();  pageTracker._trackPageview();  </script>  ++++

@aalmiray#devoxx #asciidoctor_tips

#9 The Include Macro is Awesome

• Include any file.

• Apply call outs in source code. Use standard code comments

• Change indentation; include certain lines, tags.src/main/java/sample/Foo.java  [source,java,linenums,options="nowrap"]  -­‐-­‐-­‐-­‐  include::{rootdir}/src/main/java/sample/Foo.java[lines=16..-­‐1]  -­‐-­‐-­‐-­‐  <1>  Define  the  class  <2>  Properties  <3>  Business  methods

@aalmiray#devoxx #asciidoctor_tips

#10 Follow Mr. HAKI’s blog

• @mrhaki blogs periodically at http://mrhaki.blogspot.ch/search/label/Asciidoc !

• Lots of useful tricks and exercises on brand new features

@aalmiray#devoxx #asciidoctor_tips

10 Useful Asciidoctor TipsAndres Almiray

Canoo Engineering AG