10 Useful Asciidoctor Tips
-
Upload
andres-almiray -
Category
Documents
-
view
2.365 -
download
1
description
Transcript of 10 Useful Asciidoctor Tips
@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