A backend for AsciidoctorJ to generate Leanpub-flavoured Markdown
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
converters
gradle/wrapper
leanpub-book
.gitignore
.travis.yml
CHANGELOG.adoc
LICENSE.txt
README.adoc
appveyor.yml
build.gradle
gradlew
gradlew.bat
settings.gradle

README.adoc

Asciidoctor Markdown & Leanpub Converters

The very early stages of demonstrating how to create a converter written in Groovy using the experimental asciidoctorj-1.6.0 branch.

Bootstrap

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" } (1)
    }

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

plugins {
    id 'org.asciidoctor.convert' version '1.5.3'
}

apply plugin : 'org.asciidoctor.convert'

repositories {
    jcenter()
    mavenLocal()
}

asciidoctorj {
   version = '1.6.0-alpha.4' (2)
}

asciidoctor {
  backends 'leanpub'
}
  1. Temporary measure until releases synchronize to JCenter.

  2. You need to use one of the 1.6.0 Alpha versions.

Note
Ignore the warning Passing through unknown backend: leanpub.

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.

buildscript {
    repositories {
        jcenter()
        maven { url "http://dl.bintray.com/asciidoctor/maven" }
        maven {
            name 'Asciidoctor Snapshots'
            url 'https://oss.jfrog.org/artifactory/oss-snapshot-local'
        }
    }

    dependencies {
        classpath '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, are annotated wth ' [chapter], otherwise they will disappear from the Leanpub output.

[chapter]
== 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

[chapter,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: NameOfImage 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.