Upload
andres-almiray
View
2.363
Download
1
Tags:
Embed Size (px)
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.
Citation preview
@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