Asciidoctor External Callout

An Asciidoctor extension which adds support for callout tags added outside the listing block.

Aside from getting little practice around Ruby and JavaScript, I decided to have a crack at this to help with a problem that comes up at work every so often.

The callout mechanism for Asciidoc works extremely well in 99% of the cases I run into:

[source,ruby]
----
require 'sinatra' #<1>

get '/hi' do #<2> #<3>
"Hello World!"
end
----
<1> Library import
<2> URL mapping
<3> Response block

Great, but it does mean you have to add commented to the tags to the source code to register the callout in the following block. As I've said, this is fine, 99% of the time, but I've run across a few occasions when adding tags to the source code (either in-line or an included file) can be a little problematic:

1. Restricted access to the source code: as a humble tech-writer, you might not have access to the included source code to add your own tags.
2. The source code has to remain runnable, but doesn't have a commenting mechanism that works well with Asciidoc (shell scripts amd json files spring to mind.)

And that's where this extension comes in: it adds support adding tags outside the source listing block, like this:

[source,ruby]
----
require 'sinatra'

get '/hi' do
  "Hello World!"
end
----
. Library import @3
. URL mapping @5
. Response block @5

Rather than tagging the code, you add a location token at the end of a list item, which will then add the tag at the specified line number. Run the source text through Asciidoctor+extension, and it'll split the same source block complete with callouts.

Two types of location token are supported:

@number : This format takes a numeric value indicating the line in the source block where the callout should appear. The callouts will appear at the end of the line. Multiple callouts on the same line will have a single space between them.

@/text/ : The text between the two slashes will be used in a regex search. A callout will be placed at the end of the first matching line. If you have a large listing, then it may be preferable to use the text search rather than counting all the lines. It may also be preferable to use a smaller listing, as a long listing might mean that your description is a bit too general. + Using the text search method means that the location of the callout will move with the line; handy if you're referencing a source file that might get the occasional tweak outside your control.

@/text/g : Works the same as the standard text search; the g flag means that callouts will be added to all the lines that match the search string, instead of just the first one.

@/text/i : This is a case-insensitive search.

@/text/gi : And of course, you can combine the two, though I'm not sure why you'd want to.

You can create a standalone callout list by adding the calloutlist role to an ordered list. This simply styles the list to make it look like a list of callouts, so you can use it as a reference to annoted images etc.

[calloutlist]
. This list can be used to add references to annotated images
. The list will look like a standard callout list.

Add this line to your application's Gemfile:

gem 'asciidoctor-external-callout'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install asciidoctor-external-callout

To use the extension, you need to register it before calling one of the Asciidoc convert functions to render the output.

require 'asciidoctor-external-callout'
require 'asciidoctor'

Asciidoctor.convert_file File.join(File.dirname(__FILE__), 'sample.adoc'), safe: :unsafe, backend: :html5

If you're not using the excellent Asciidoc plugin, then you're really missing out. One of its lesser known features is that it supports Asciidoc extensions written in Ruby:

1. Create a new folder structure in the root of your IntelliJ project called .asciidoctor/lib.
2. Copy the file asciidoctor-external-calllout.rb from this distribution to .asciidoctor/lib.

Now, when you preview an Asciidoc file with the plugin enabled, external callouts will now show up in the preview.

By default, the callout extension will put a single space between callouts that occur on the same line. If you want to adjust this, then you need to create a style that puts a horizontal margin between the callouts:

div.external-callout-block i.conum {
    margin-left: 10px;
    margin-right: 10px;
}

The callout attaches a class called external-callout-block to each source listing it processes. You can use this to differentiate between standard callouts, and callouts written by the extension.

The extension also adds a class called external-callout-list to the list of definitions at the bottom of the source block. (There's probably no need to adjust the styling for this.)

To convert a document with a stylesheet, use something like this:

Asciidoctor.convert_file File.join(File.dirname(__FILE__), 'sample.adoc'), 
                         safe: :unsafe, backend: :html5,
                         attributes: {'stylesheet' => './callout.css'}

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

The gem is open source under the terms of the MIT License.

Everyone interacting in the Asciidoctor::External::Callout project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.