10 useful asciidoctor tips

13
@aalmiray #devoxx #asciidoctor_tips 10 Useful Asciidoctor Tips Andres Almiray Canoo Engineering AG

Upload: andres-almiray

Post on 28-Jun-2015

2.350 views

Category:

Documents


1 download

DESCRIPTION

You've seen the asciidoctor talks. You've written a few asciidoc documents. Now what? Allow me to share some tips and tricks learned after working with several projects that make us of Asciidoctor for writing their documentation and guides. Tips such as keeping production sources and documentation in sync; productivity tools; and other little nuggets of joy.

TRANSCRIPT

Page 1: 10 Useful Asciidoctor Tips

@aalmiray#devoxx #asciidoctor_tips

10 Useful Asciidoctor TipsAndres Almiray

Canoo Engineering AG

Page 2: 10 Useful Asciidoctor Tips

@aalmiray#devoxx #asciidoctor_tips

Page 3: 10 Useful 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

Page 4: 10 Useful Asciidoctor Tips

@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

Page 5: 10 Useful Asciidoctor Tips

@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}.

Page 6: 10 Useful Asciidoctor Tips

@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[]

Page 7: 10 Useful Asciidoctor Tips

@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!  ////

Page 8: 10 Useful Asciidoctor Tips

@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).

Page 9: 10 Useful Asciidoctor Tips

@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>

Page 10: 10 Useful Asciidoctor Tips

@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>  ++++

Page 11: 10 Useful Asciidoctor Tips

@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

Page 12: 10 Useful Asciidoctor Tips

@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

Page 13: 10 Useful Asciidoctor Tips

@aalmiray#devoxx #asciidoctor_tips

10 Useful Asciidoctor TipsAndres Almiray

Canoo Engineering AG