Shell Scripting

Asciidoctor: Creating a macro

I’ve been writing the TWIN4j blog for almost a year now and during that time I’ve written a few different asciidoc macros to avoid repetition.

The most recent one I wrote does the formatting around the Featured Community Member of the Week. I call it like this from the asciidoc, passing in the name of the person and a link to an image:

featured::[name="Suellen Stringer-Hye"]

The code for the macro has two parts. The first is some wiring code that registers the macro with Asciidoctor:


RUBY_ENGINE == 'opal' ? (require 'featured-macro/extension') : (require_relative 'featured-macro/extension')
Asciidoctor::Extensions.register do
  if (@document.basebackend? 'html') && ( < SafeMode::SECURE)
    block_macro FeaturedBlockMacro

And this is the code for the macro itself:


require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
include ::Asciidoctor
class FeaturedBlockMacro < Extensions::BlockMacroProcessor
  named :featured
  def process parent, target, attrs
    name = attrs["name"]
    html = %(<div class="imageblock image-heading">
                <div class="content">
                    <img src="#{target}" alt="#{name} - This Week’s Featured Community Member" width="800" height="400">
            <p style="font-size: .8em; line-height: 1.5em;" align="center">
              <strong>#{name} - This Week's Featured Community Member</strong>
    create_pass_block parent, html, attrs, subs: nil

When we convert the asciidoc into HTML we need to tell asciidoctor about the macro, which we can do like this:

asciidoctor template.adoc \
  -r ./lib/featured-macro.rb \
  -o -

And that’s it!

Published on System Code Geeks with permission by Mark Needham, partner at our SCG program. See the original article here: Asciidoctor: Creating a macro

Opinions expressed by System Code Geeks contributors are their own.

Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments
Back to top button