Asciidoctor::Jenkins::Extensions

This gem is a collection of Asciidoctor extensions which enable more advanced formatting in Jenkins-related content.

Installation

Add this line to your application’s Gemfile:

gem 'asciidoctor-jenkins-extensions'

And then execute:

$ bundle

Or install it yourself as:

$ gem install asciidoctor-jenkins-extensions

Usage

Using this gem inside of an existing Asciidoctor-based project is as straight-forward as requiring asciidoctor/jenkins/extensions, for example:

require 'asciidoctor/jenkins/extensions'

In Awestruct-based projects, this require statement should go in _ext/pipeline.rb.

[pipeline] block

An extension to Asciidoctor syntax adds the [pipeline] block for including Pipeline code. This block supports both Declarative Pipeline and Pipeline Script syntax. For example:

[pipeline]
----
// Script //
node {
    stage('Build') {
      checkout scm
      // Install dependencies
      sh 'npm install'
    }
}

// Declarative //
pipeline {
    agent docker: 'node:6.3'
    stages {
        stage('Build') {
            sh 'npm install'
        }
    }
}
----

This pipeline block will prefer the Declarative Pipeline syntax when rendering, and provide a link for toggling the Scripted Pipeline.

The // Declarative // or // Script // delimiters are MANDATORY, even when defining a [pipeline] block with only one syntax supported. These delimiters instruct the extension on how to render the given code.

the plugin macro

The plugin inline macro can be used to link to plugins on the plugins index at https://plugins.jenkins.io/.

Example:

plugin:git[The Git Plugin]

jenkinsdoc/staplerdoc/javadoc macros

The jenkinsdoc inline macro can be used to link to the Jenkins Javadoc at https://javadoc.jenkins.io/.

It supports a variety of different syntaxes. For classes in Jenkins core:

jenkinsdoc:hudson.scm.SCM[] links to the full URL for the class in Jenkins core.
jenkinsdoc:hudson.scm.SCM#all()[] links to the full URL for the class in Jenkins core, and includes a fragment.
jenkinsdoc:SCM[] links to the /byShortName URL for the class in Jenkins core. Due to the redirect, fragments won’t work here.

By default, all of these use the class name as label, but that can be customized if necessary by providing an alternative label between the square brackets.

jenkinsdoc:hudson.scm.SCM#all()[a list of all known SCM implementations]

For classes in plugins, the plugin’s name (artifactId) is put before the class name and separated by colon:

jenkinsdoc:git:hudson.plugins.git.GitSCM[] links to the full URL for the class in the git plugin.
jenkinsdoc:git:hudson.plugins.git.GitSCM#getRepositories--[] links to the full URL for the class in the git plugin, and includes a fragment.

These use a similar default label if none is set, but it also specified which plugin the class is in. For the previous example, that label would be hudson.plugins.git.GitSCM in git.

Two other inline macros, staplerdoc and javadoc exist and link to the Stapler API documentation and Java API documentation, respectively. These do not support the form of jenkinsci that only requires the short name, but otherwise work the same way. Examples:

javadoc:java.io.File#pathSeparator[the path separator]
staplerdoc:org.kohsuke.stapler.AncestorInPath[]

Other macros (jep/jira/security)

See [examples](./examples).

Development

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Acceptance Tests

In order to make testing of extensions easier, there is a bit of support for live-page Asciidoc rendering with extensions live-reloaded on each page load.

In the examples/ directory you will find sample .adoc files which serve as test files for rendering with Asciidoctor and these extensions. To run the test server, assuming you have already executed bundle install, run:

shotgun

And then navigate to localhost:9393