10 Useful Asciidoctor Tips

download 10 Useful Asciidoctor Tips

of 13

  • date post

    28-Jun-2015
  • Category

    Documents

  • view

    2.339
  • download

    1

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.

Transcript of 10 Useful Asciidoctor Tips

  • 1. 10 Useful Asciidoctor TipsAndres AlmirayCanoo Engineering AG#devoxx #asciidoctor_tips @aalmiray

2. #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.adocinclude::_links.adoc[]!Asciidoctorhasgreatintegrationwith{link_gradle}and{link_maven}.#devoxx #asciidoctor_tips @aalmiray 6. #4 Blank lines at top and bottom Simplifies including files into others//withoutblanklines//withblanklines//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 ;-)=ChapterTitleThefollowingchapterdiscussesloremipsumdolorsitametconsecuturadnauseam.//IDEA:insertaloremipsumgeneratorhere?!Loremipsumdolorsitametconsecutur.Loremipsumdolorsitametconsecutur.Loremipsumdolorsitametconsecutur.Loremipsumdolorsitametconsecutur.!////Whybuildacustomlorem-ipsumextensionwhencopy&pasteissocheap?Noneedtotirethosecellbrains.Ohlook,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 onbuild 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 from2#devoxx #asciidoctor_tips @aalmiray 10. #8 Include Raw Content Either use the pass:[] macro or the ++++ blockpass:[]!++++varpageTracker=_gat._getTracker("XX-123456-1");pageTracker._initData();pageTracker._trackPageview();++++#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]----DefinetheclassPropertiesBusinessmethods#devoxx #asciidoctor_tips @aalmiray 12. #10 Follow Mr. HAKIs blog @mrhaki blogs periodically athttp://mrhaki.blogspot.ch/search/label/Asciidoc! Lots of useful tricks and exercises on brand new features#devoxx #asciidoctor_tips @aalmiray 13. 10 Useful Asciidoctor TipsAndres AlmirayCanoo Engineering AG#devoxx #asciidoctor_tips @aalmiray