10 Useful Asciidoctor Tips
16 likes8,352 views
The document outlines ten useful tips for using Asciidoctor, such as integrating live reload with browser extensions, building tool integration, and the importance of maintaining blank lines in documents. It emphasizes the use of conditional blocks, comment sections, and raw content inclusion, as well as the utility of the include macro for source code management. Additionally, it recommends following Mr. Haki's blog for more tips and exercises related to Asciidoctor.
![#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}.
#devoxx #asciidoctor_tips @aalmiray](https://image.slidesharecdn.com/devoxxasciidoctortips-141113092127-conversion-gate02/85/10-Useful-Asciidoctor-Tips-5-320.jpg)
![#4 Blank lines at top and bottom
• Simplifies including files into others
//
without
blank
lines
//
with
blank
lines
//
index.adoc
//
index.adoc
!
!
include::chapter1.adoc[]
include::chapter1.adoc[]
!
include::chapter2.adoc[]
include::chapter2.adoc[]
include::chapter3.adoc[]
!
include::chapter3.adoc[]
#devoxx #asciidoctor_tips @aalmiray](https://image.slidesharecdn.com/devoxxasciidoctortips-141113092127-conversion-gate02/85/10-Useful-Asciidoctor-Tips-6-320.jpg)
![#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).
#devoxx #asciidoctor_tips @aalmiray](https://image.slidesharecdn.com/devoxxasciidoctortips-141113092127-conversion-gate02/85/10-Useful-Asciidoctor-Tips-8-320.jpg)
![#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>
#devoxx #asciidoctor_tips @aalmiray](https://image.slidesharecdn.com/devoxxasciidoctortips-141113092127-conversion-gate02/85/10-Useful-Asciidoctor-Tips-9-320.jpg)
![#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>
++++
#devoxx #asciidoctor_tips @aalmiray](https://image.slidesharecdn.com/devoxxasciidoctortips-141113092127-conversion-gate02/85/10-Useful-Asciidoctor-Tips-10-320.jpg)
![#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
#devoxx #asciidoctor_tips @aalmiray](https://image.slidesharecdn.com/devoxxasciidoctortips-141113092127-conversion-gate02/85/10-Useful-Asciidoctor-Tips-11-320.jpg)
10 Useful Asciidoctor Tips
- 1. 10 Useful Asciidoctor Tips Andres Almiray Canoo Engineering AG #devoxx #asciidoctor_tips @aalmiray
- 3. #1 Live Reload + Browser Extension • http://livereload.com/ ! • https://github.com/asciidoctor/asciidoctor-chrome-extension ! • https://github.com/asciidoctor/asciidoctor-firefox-addon #devoxx #asciidoctor_tips @aalmiray
- 4. #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 #devoxx #asciidoctor_tips @aalmiray
- 5. #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}. #devoxx #asciidoctor_tips @aalmiray
- 6. #4 Blank lines at top and bottom • Simplifies including files into others // without blank lines // with blank lines // index.adoc // index.adoc ! ! include::chapter1.adoc[] include::chapter1.adoc[] ! include::chapter2.adoc[] include::chapter2.adoc[] include::chapter3.adoc[] ! include::chapter3.adoc[] #devoxx #asciidoctor_tips @aalmiray
- 7. #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! //// #devoxx #asciidoctor_tips @aalmiray
- 8. #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). #devoxx #asciidoctor_tips @aalmiray
- 9. #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> #devoxx #asciidoctor_tips @aalmiray
- 10. #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> ++++ #devoxx #asciidoctor_tips @aalmiray
- 11. #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 #devoxx #asciidoctor_tips @aalmiray
- 12. #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 #devoxx #asciidoctor_tips @aalmiray
- 13. 10 Useful Asciidoctor Tips Andres Almiray Canoo Engineering AG #devoxx #asciidoctor_tips @aalmiray