obilodeau/asciidoctor-templates-compiler

Compile templates-based Asciidoctor converter (backend) into a single Ruby file

Asciidoctor Templates Compiler

This tool allows to precompile Slim templates into Ruby code and assemble them into a single-file pure Ruby converter (backend).

TODO

Installation

Add this line to your application’s Gemfile:

group :development do
  gem 'asciidoctor-templates-compiler', '~> 0.4.1'
end

or to your gemspec:

s.add_development_dependency 'asciidoctor-templates-compiler', '~> 0.4.1'

and then execute:

$ bundle install

Usage

The main entry point is method Asciidoctor::TemplatesCompiler::Slim#compile_converter (for Slim) that accepts the following keyword arguments.

backend_info

A hash of keys for backend_info: basebackend, outfilesuffix, filetype, htmlsyntax, supports_templates (supported since Asciidoctor ≥ 1.5.7).

class_name

Full name of the converter class to generate (e.g. My::HTML::Converter). This argument is required.

delegate_backend

Name of the backend (converter) to use as a fallback for AST nodes not supported by your converter. If not specified (default), no fallback will be used and converter will raise NoMethodError when it try to convert an unsupported node.

engine_opts

A Hash of options to pass into the templating engine that compiles templates into Ruby code.

output

An output stream (IO object like opened file, $stdout, …) to write the generated converter into. Default is StringIO.new (it’s the return value of #compile_converter).

pretty

Enable pretty-formatting of the generated Ruby code (generated by Slim/Temple)? Default is false.

register_for

An array of backend names that the generated converter should be registered in Asciidoctor to handle. Default is empty.

templates_dir

Path of the directory where to look for templates (*.slim files not starting with _, in the case of Slim) and (optional) helpers.rb. This argument is required.

Examples

Minimal example

require 'asciidoctor-templates-compiler'

File.open('converter.rb', 'w') do |file|
  Asciidoctor::TemplatesCompiler::Slim.compile_converter(
      templates_dir: 'data/templates',
      class_name: 'ShinyHtml::Converter',
      delegate_backend: 'html5',
      register_for: ['shiny-html'],
      backend_info: {
        basebackend: 'html',
        outfilesuffix: '.html',
        filetype: 'html',
      },
      pretty: true,
      output: file)
end

Example of usage in Rakefile

#!/usr/bin/env rake

CONVERTER_FILE = 'lib/asciidoctor/shiny_html/converter.rb'
TEMPLATES_DIR = 'data/templates'

namespace :build do

  file CONVERTER_FILE, [:mode] => FileList["#{TEMPLATES_DIR}/*"] do |t, args|
    require 'asciidoctor-templates-compiler'

    File.open(CONVERTER_FILE, 'w') do |file|
      $stderr.puts "Generating #{file.path}."
      Asciidoctor::TemplatesCompiler::Slim.compile_converter(
          templates_dir: TEMPLATES_DIR,
          class_name: 'Asciidoctor::ShinyHtml::Converter',
          delegate_backend: 'html5',
          register_for: ['shiny-html'],
          backend_info: {
            basebackend: 'html',
            outfilesuffix: '.html',
            filetype: 'html',
          },
          pretty: (args[:mode] == :pretty),
          output: file)
    end
  end

  namespace :converter do
    desc 'Compile Slim templates and generate converter.rb (pretty mode)'
    task :pretty do
      Rake::Task[CONVERTER_FILE].invoke(:pretty)
    end

    desc 'Compile Slim templates and generate converter.rb (fast mode)'
    task :fast do
      Rake::Task[CONVERTER_FILE].invoke
    end
  end

  task :converter => 'converter:pretty'
end

task :build => 'build:converter:pretty'

task :clean do
  rm_rf CONVERTER_FILE
end

You can also look into asciidoctor-html5s for a real-world example including integration with Asciidoctor::DocTest.

License

This project is licensed under MIT License. For the full text of the license, see the LICENSE file.