CustomExtensions

Extensions

The toolchain uses a plugin system to extend the functionality. Such test plugins are called extensions.

How to

First, some boilerplate code:

# frozen_string_literal: true

require 'extension_manager'
require 'base_extension'

module Custom
  class HelloWorld < ::Toolchain::BaseExtension
    def run(adoc)
      original = adoc.original
      parsed = adoc.parsed
      attributes = adoc.attributes
      
      # run your code
      puts "Hello #{adoc.original.attr('docfile')}"
    end
  end
end

::Toolchain::ExtensionManager.instance.register(
  Custom::HelloWorld.new
)

First, create a class (CustomExtension here) which inherits from BaseExtension. This class overwrites the run method and has a single argument, the Asciidoctor document. The argument consists of three parts:

1. original: the original Asciidoctor document
2. parsed: the parsed Asciidoctor document
3. attributes: the attributes which were defined in the Asciidoctor document

Lastly, the extension needs to be registered with Toolchain::ExtensionManager.

Once this is done and the extension has been placed in the extensions.d folder, the toolchain will use this extension during the Test stage.

NOTE: The extension must be included in config.yaml in order to be loaded (see Config).

Errors

If your extensions checks for errors or warnings, use create_error to create an error and return all errors as list:

def run(adoc)
  original = adoc.original
  parsed = adoc.parsed
  attributes = adoc.attributes
  errors = []

  # run your code
  # ...
  errors << create_error(
    msg: msg,
    location: Location.new(adoc.original.attr('docfile'), nil)
  )
  # ...
  return errors
end