Asciidoctor Markdown & Leanpub Converters

The very early stages of demonstrating how to create a converter written in Groovy using asciidoctorj-2.2.0.

Bootstrap

Gradle

If you are using Asciidoctor plugin for Gradle then you should be able to do

buildscript {
    repositories {
        jcenter()
        maven { url "http://dl.bintray.com/asciidoctor/maven" }
    }

}

plugins {
    id 'org.asciidoctor.jvm.convert' version '2.0-alpha.5'
}

repositories {
    jcenter()
    mavenLocal()
}

configurations {
    leanpub
}

dependencies {
    leanpub 'org.asciidoctor:asciidoctor-leanpub-markdown:2.0-alpha.2'
}

asciidoctor {
  backends 'leanpub'

  configurations 'leanpub'
}

Maven

If you want to integrate the converter in a maven project, just add

<build>
    <plugins>
        <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>2.0.0-RC.1</version>
            <dependencies>
                <dependency> <!-- 1 -->
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-leanpub-markdown</artifactId>
                    <version>2.0-alpha.2</version>
                </dependency>
            </dependencies>
            <configuration>
                <backend>leanpub</backend> <!-- 2 -->
            </configuration>
        </plugin>
    </plugins>
</build>

<pluginRepositories> <!-- 3 -->
    <pluginRepository>
        <id>jcenter</id>
        <name>bintray-plugins</name>
        <url>http://dl.bintray.com/asciidoctor/maven</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </pluginRepository>
</pluginRepositories>

The converter as a plugin dependency
Set backend to leanpub or markdown
Add jcenter as plugin repository

Command line

If you want to try the command-line version of asciidoctorj, then you are in luck. You can run it from asciidoctorj/asciidoctorj-distribution/build/install/asciidoctorj-distribution/bin/asciidoctorj.

All you have to do is pass the --cp command-line parameter and tell it where the leanpub-converter-core.jar is.

Using SNAPSHOT versions

Since this backend is very much in active development, you might want to try latest features as they are committed. If you are using the Gradle plugins you need to add an additional repository and use the SNAPSHOT instead.

repositories {
    jcenter()
    maven {
        name 'Asciidoctor Snapshots'
        url 'https://oss.jfrog.org/artifactory/oss-snapshot-local'
    }
}

dependencies {
    leanpub 'org.asciidoctor:asciidoctor-leanpub-markdown:1.6.0-alpha.1-SNAPSHOT'
}

Note	You should obviously not use this for production works as SNAPSHOT-based dependencies lead to non-repeatable builds.

Parts & Chapters

Level 0 heading becomes a Leanpub part and creates a new part file

= This becomes a part

Level 1 heading becomes a Leanpub chapter. In addition if it is annotated with [chapter] it creates a new chapter file. At least one level 1 heading should be annotated with [chapter]. When writing a multi-part book, ensure that level 1 headings that follow a level 0, and which are not marked special sections wil be treated as Leanpub chapters/

== This becomes a chapter

Level 1 heading annotated with [preface] becomes a Leanpub preface

[preface]
== This is a preface

Leanpub allows chapters to be added to a sample book. If you want chapters or a preface to be added to your sample book, add leanpub='sample' metadata to the chapter or preface block

[preface,leanpub='sample']
== Preface

[leanpub='sample']
== Chapter

Blocks

Poetry blocks are supported by adding a poem role to a verse block

[verse.poem]
....
Poem goes here
....

Source code blocks with callouts

Leanpub does not support callouts in the way Asciidoctor does. Our solution, for when callouts are detected, is to generate a source code listing with line numbers. The associated colist block is then generated with corresponding line numbers instead of the original callout numbers. The callouts are also removed from the source listing.

Currently it is possible to generate the colist block in one of three styles, which in themselves correspond to Leanpub blocks. They are:

paragraph (default)
aside
discussion

The specific style is set via the leanpub-colist-style attribute. Each colist item is preceded by a prefix of Line. This can be changed by setting the leanpub-colist-prefix attribute.

Images

No size checks are done on images, they are just copied to the manuscript/images folder. Remember that Leanpub prefers 300dpi images. See (Leanpub docs. Also take note that floating lists around images do not work in Leanpub. This converter will not prevent this from happening. It is up to the author to take care of that.

The :figure-caption!: attribute is ignored - images are not numbered.

Most Asciidoctor image metadata is ignored in image::sunset.jpg[Sunset,300,200,link="http://to/some.jpg"], none of the size or link be be converted, but alternative text will be converted for both inline and block images. The float metadata will be converted for bloc images.

Tables

See the examples project for what is supported and what is not supported.

Cover page

Use :front-cover-page: to add a Leanpub cover. Currently no size checking is done, but a PNG extension is required. See https://leanpub.com/help/manual#leanpub-auto-how-to-insert-cover-images—cover-pages(Leanpub docs) for more detail on size requirements.

See Asciidoctor in action

Have a look on Leanpub at this free sample book which is the generated version of the example project.

asciidoctor / asciidoctor-leanpub-converter