= Asciidoctor Markdown & Leanpub Converters
Schalk Cronjé
:version: 2.0-alpha.2
:asciidoctorj-version: 2.2.0
:asciidoctor-maven-plugin-version: 2.0.0-RC.1
The very early stages of demonstrating how to create a converter written in Groovy using asciidoctorj-{asciidoctorj-version}.
== Bootstrap
=== Gradle
If you are using Asciidoctor plugin for Gradle then you should be able to do
[source,groovy,subs=attributes+]
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:{version}'
}
asciidoctor {
backends 'leanpub'
configurations 'leanpub'
}
=== Maven
If you want to integrate the converter in a maven project, just add
[source,xml,subs=attributes+]
org.asciidoctor
asciidoctor-maven-plugin
{asciidoctor-maven-plugin-version}
org.asciidoctor
asciidoctor-leanpub-markdown
{version}
leanpub
jcenter
bintray-plugins
http://dl.bintray.com/asciidoctor/maven
false
<1> The converter as a plugin dependency
<2> Set backend to `leanpub` or `markdown`
<3> 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.
[source,groovy]
----
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 (https://leanpub.com/help/manual#leanpub-auto-images-and-cover-pages)[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: image:NameOfImage.png[]` 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 https://leanpub.com/asciidoctortoleanpubsample[free sample book] which is the generated version of the example project.