Create an Extended Converter

Register an extended converter

Asciidoctor provides a mechanism for looking up a registered converter so it can be extended (i.e., used as a base class), then another mechanism for registering the extended converter in its place. Let’s see how that looks.

extended-pdf-converter.rb
class ExtendedPDFConverter < (Asciidoctor::Converter.for 'pdf')
  register_for 'pdf'

  # overrides go here
end

When this script is required by Asciidoctor, it will replace the primary converter with the extended one automatically. As it stands, this converter doesn’t do anything different than the primary converter because we haven’t yet overridden any of its methods.

Override a method

Let’s start by overriding the thematic break (i.e., horizontal rule) to make it render like a red ribbon.

  def convert_thematic_break node
    theme_margin :thematic_break, :top
    stroke_horizontal_rule 'FF0000', line_width: 0.5, line_style: :solid
    move_down 1
    stroke_horizontal_rule 'FF0000', line_width: 1, line_style: :solid
    move_down 1
    stroke_horizontal_rule 'FF0000', line_width: 0.5, line_style: :solid
    theme_margin :thematic_break, ((block_next = next_enclosed_block node) ? :bottom : :top), block_next || true
  end

The return value of a convert handler for a block node is ignored. The return value of a convert handler for an inline node must be a string, which may contain the HTML-like markup that this convert supports.

To find all the available methods to override, see the API docs.

Now that you’ve made a change to the converter, let’s learn how to activate it.