Awesome Asciidoc: Explain Code with Callouts

Writing documentation with Asciidoc is such a treat. We can add markers to our code where we want to explain something in our code. The markers have numbers and are enclosed in < and > brackets. The explanation for the markers follows a code listing in a callout list. Here we use the same marker and add extra text to explain the code. We can put the markers in comments in our code so we can use the markers in existing code.

Continue reading

Awesome Asciidoc: Include Partial Parts from Code Samples

Writing technical documentation with Asciidoc and Asciidoctor is so much fun. Especially the include macro makes inserting changing content, like source files, a breeze. We only need to maintain the original source file and changes will automatically appear in the generated documentation. We can include only a part of source file using tags. In the source file we add a comment with the following format tag::tagName[] to start the section. We end the section with end::tagName[]. Now in our Asciidoc document we can indicatie the tags we want to include with include::sourceFile[tags=tagName].

Continue reading