Asciidoctor Extension Templates for Ruby

Asciidoctor Extension Templates is a gem providing basic extension templates for Ruby. Templates are directly runnable, and create some dummy content. It can be your starting point to develop your own Asciidoctor extension.

• just clone the project

• extract the template you need to a gem. See Ready to Rumble

• start coding functionality to your extension gem

Its aim is to take the pain out starting a new Asciidoctor extension in Ruby.

• Overview
• Highlights
• Development
• Ready to Rumble
• Coding the Extension
• Author
• Copyright

Overview

Asciidoctor Extension Templates is a Set of Asciidoctor Extension Templates which run OOTB. These can be the base for your own Asciidoctor extension development project.

The style and layout of the project is based on the one from Asciidoctor PDF. A lot of code is a 100% copy of the code there or at least heavily inspired. Logically all that stuff is (c) by OpenDevise Inc. and the Asciidoctor Project.

Highlights

• Templates are Runnable

• ready to run tasks for

  • Testruns (rspec)

  • Linting (rubocop)

  • Coverage (simplecov,deep-cover)

• easy extracting an extension to a new gem project

Development

NOTE:

I use RVM to manage Ruby installation.

so to follow the next steps as is you will need a working rvm flavoured Ruby installation:

• installed rvm

• installed Ruby

• installed bundler

This is neither a library nor an application. So you might want to separate it from your global ruby.

Retrieve the Source Code

To start with the template just clone the project. Simply copy the GitHub repository URL and pass it to the git clone command:

$ git clone https://github.com/irkode/irkode.playground

Next, change to the project directory:

$ cd asciidoctor-extension_templates

Install Dependencies

Now activate the ruby version:

$ rvm use 2.7.2
# ruby-2.7.2

The dependencies needed to use Asciidoctor Extension Templates are defined in the Gemfile at the root of the project. Use Bundler to install the dependencies for you.

Then use the bundle command to install the project dependencies into the project

$ bundle config set --local path '.bundle/gems' #(1)
$ bundle

1. bundle --path=.bundle/gems is deprecated

📎	You must call bundle from the project directory so that it can find the Gemfile.

Run a template

Each template provides a running script to demonstrate usage. Like with Bundler, you have to run the application from the project directory. Assuming all the required gems install properly, verify you can run the asciidoctor-extension_templates scripts using Ruby:

$ bundle exec bin/asciidoctor-extension_templates -v
# Asciidoctor Extension Templates 0.0.1.dev using Asciidoctor 2.0.12 [https://asciidoctor.org]
# Runtime Environment (ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [armv7l-linux-eabihf]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8) (1)
$ bundle exec bin/asciidoctor-extension_templates -b backend_tpl -o - README.adoc
# Well done : You plugged in a converter backend names 'backend_tpl'

1. yes - all done on a Raspberry PI 4

Ready to Rumble

Now you can start to generate a new Asciidoctor extension gem of your choice. Use the provided Rake task to create a new folder holding all the files you need to start with your choosen extension.

The list of available template tasks can be retrieved using bundle exec rake tpl:.

🔥	No error checking on the arguments, so double check your input

The tasks use the standard Rake argument notation with the following arguments.

target

destination root where the new gem folder will be created

short

extension short name used to build up the extension folder name and files.

class

extension class name to use in the coding part

Example: Backend

$ bundle exec rake tpl:
# USAGE: tpl:<command>[<args>]
#  tpl:backend[target,backend,class] - create a new backend from template
$ bundle exec rake tpl:backend['/home/my/coding','my_backend','MyBackend']

Which will create the folder /home/my/coding/asciidoctor-my_backend and install needed files there

you now can chdir to /home/my/coding/asciidoctor-my_backend and

• adjust template files (especially the gemspec and README)

• add your extension code

📎	License is set to MIT - You are highly encouraged to use this for your extension.

Coding the Extension

I guess if you follow the CONTRIBUTING-CODE.adoc from Asciidoctor PDF you might be on the right track.

There’s a section about Test and Linting and Asciidoctor Extension Templates follows this and provides the basics for both incl. coverage.

These tasks work also properly in the Extension Templates itself. Use them to check if the template library works on your machine.

Run tests

$ bundle exec rake spec
$ bundle exec rspec -fd

Run Linter

$ bundle exec rake lint

more details on that can be found in their guide.

Author

Asciidoctor Extension Templates was assembled and tweaked by @irkode based on the project layout of Asciidoctor PDF written by Dan Allen and Sarah White of OpenDevise Inc. on behalf of the Asciidoctor Project.

Copyright

Copyright © 2021-present @irkode

Lot of the code, project layout, …​ taken more or less from the Asciidoctor PDF project. In fact this is the goal of Asciidoctor Extension Templates: As close to a real extension as possible All that is: Copyright (c) 2014-present OpenDevise Inc. and the Asciidoctor Project.

Free use of this software is granted under the terms of the MIT License.

For the full text of the license, see the LICENSE file. Refer to the NOTICE file for information about third-party Open Source software in use.