Creating an Asciidoc Block Type

To create the Asciidoc "EXTRA" formatting block for the Spanish section, I created a Asciidoctor plugin. Two simple Ruby classes are needed: an implementation and a registrar.

I slightly modified the example block provided by Asciidoctor. Their DSL (domain specific language) makes it easy to set up. The comments illustrate how the block is used in documents.

require 'asciidoctor/extensions'

include Asciidoctor

# An extension that introduces a custom admonition type, complete
# with a custom icon.
#
# Usage
#
#   [ADVANCED]
#   ====
#   What's the main tool for selecting colors?
#   ====
#
# or
#
#   [ADVANCED]
#   What's the main tool for selecting colors?
#
class ExtraAdmonitionBlock < Extensions::BlockProcessor
  use_dsl
  named :EXTRA
  on_contexts :example, :paragraph

  def process parent, reader, attrs
    attrs.update 'name' ⇒ 'extra', 'textlabel' ⇒ 'Extra'
    node = create_block parent, :admonition, reader.lines, attrs, content_model: :compound
    node.caption = attrs['textlabel'] unless node.caption
    node
  end
end

class ExtraAdmonitionBlockDocinfo < Extensions::DocinfoProcessor
  use_dsl

  def process doc
    if (doc.basebackend? 'html') && doc.backend != 'pdf'
      '<style>
.admonitionblock td.icon .icon-extra:before {content:"\f135";color:#871452;}
</style>'
    end
    # NOTE: f135 is the Unicode for the rocket Font Awesome icon
  end
end

This file handles the registration of the custom block with Asciidoctor using its plugin structure.

RUBY_ENGINE == 'opal' ? 
  (require 'extra-admonition-block/extension') : 
  (require_relative 'extra-admonition-block/extension')

Extensions.register do
  block ExtraAdmonitionBlock
  docinfo_processor ExtraAdmonitionBlockDocinfo
end