LeanPub Extensions

Overview

LeanPub[1] is a publishing platform for books, especially for technical books.

The input format for LeanPub is markdown. Now markdown does not have the features that are needed to publish books, therefore they came up with some extensions:

  1. You can highlight lines in code blocks so that they stand out.
  2. You can insert an aside or text box, often used to discuss issues that are slightly off topic, or to add more complex information for advanced readers etc.
  3. Several flavours of a message combined with an icon and separated from the main text by some white space. We refer to this as “specialties”.

Since version 3.6 MarkAPL understands the LeanPub extensions and marks the markdown up accordingly. Both style sheets coming with MarkAPL have proper mark-up added.

We are going to discuss all extensions in detail.

1. Highlighting Code

Code can be highlighted by injecting leanpub-start-insert and leanpub-end-insert as shown here:

life←{↑1 ⍵∨.∧3 4=+/,¯1 0 1∘.⊖¯1 0 1∘.⌽⊂⍵)
leanpub-start-insert
primeNumbers←{{⍵/⍨2=+⌿0=⍵∘.|⍵}⍳⍵}100
leanpub-end-insert
dropLeadingBlanks←{(∨\' '≠⍵)/⍵}

Note that in the code block above the leanpub-*-insert strings show, meaning that they have not been processed. This is because there is an escape character (\) in front of them in the document itself.

This shows as:

life←{↑1 ⍵∨.∧3 4=+/,¯1 0 1∘.⊖¯1 0 1∘.⌽⊂⍵)
primeNumbers←{{⍵/⍨2=+⌿0=⍵∘.|⍵}⍳⍵}100
dropLeadingBlanks←{(∨\' '≠⍵)/⍵}

2. Asides or Text Boxes

Note that in the markdown asides need to be surrounded by empty lines, otherwise they won't be recognized.

This is a very simple example for an aside or text box:

A> Asides offer additional information.

This shows as:

Asides offer additional information.

However, inside an aside you can have everything Markdown offers: headers, code block, lists, whatever.

A> ### This offers information about asides
A>
A> Asides can hold everything that's available in Markdown.
A>
A> #### Examples:
A>
A> ~~~
A> {(+⌿⍵}÷≢⍵}
A> ~~~
A>
A> * List item 1
A> * List item 2
A>
A> > Asides are great.
A>
A> In-line mark-up is available, too: **bold**, _italic_, `code`, whatever.

This shows as:

This offers information about asides

Asides can hold everything that's available in Markdown.

Examples:

{(+⌿⍵}÷≢⍵}

Asides are great.

In-line mark-up is available, too: bold, italic, code, whatever.

Notes:

3. Specialties

Note that in the markdown all specialties need to be embraced by empty lines, otherwise they won't be recognized.

LeanPub offers special mark-up for several purposes:

We will discuss them in this order.

A word of warning: making use of the specialties prevents any HTML document created by MarkAPL from being stand-alone; the icons have to come from somewhere. However, by default they are referred to as a URL pointing to a web address (see MarkAPL's leanpubIconsUrl parameter), so when you have an Internet connection it will work fine.

If you like the general idea but not the icons used you can specify a different location and put your favourite icons there. Note that you can not change the names of the LeanPub extension icons.

Note that in case you specify a level-1 (<h1>) or a level-2 (<h2>) header in a specialty it will be converted to a level-3 header (<h3>) anyway. The reason is that many screenreaders read out all <h1> and all <h2> tags. Therefore the W3C recommends to not use headers of the levels 1 and 2 except they really are such headers.

Information

This:

~~~
I> A piece of information.
~~~

leads to this:

Information

A piece of information.

Here is a more complex example:

~~~
I> # About Specialties
I> All specialties share a number of properties:
I>
I> * They all have an icon to make it easier to identify them.
I> * They all have plenty of white space around them in order to tell them apart from ordinary text.
I>
I> They can have headers and multiple paragraphs, but they can also have all the other stuff Markdown is offering, although it is not recommended to use them.
~~~

This is the result:

Information

About Specialties

All specialties share a number of properties:

They can have headers and multiple paragraphs, but they can also have all the other stuff Markdown is offering, although you should use them with care.

Discussions

Simple example:

Discussion

Reserve time for discussions

More complex:

Discussion

Regarding Discussions

Exercise

Simple Example:

Exercise

Today's exercise

More complex:

Exercise

Exercises

First

Do this!

Second

Do that! Random text with a couple of words. Random text with a couple of words. Random text with a couple of words. Random text with a couple of words. Random text with a couple of words.

{(+⌿⍵}÷≢⍵}

Errors

Simple example:

Error

Errors exists only to be made. Off we go!

Error

About Errors

There is so much more to say regarding errors…

Warning

Simple example:

Warning

Warnings: don't use the LeanPub extension too often.

More complex:

Warning

A word of warning

Using the LeanPub extensions heavily it unlikely to be a good idea.

Questions

Simple example:

Question

Any questions?!

More complex:

Question

Question can be asked.

However, time is a scarce resource, so don't waste it on asking questions that will advertise you as a moron!

Behind the scenes

All Leanpub extensions are converted into HTML independently from processing the main document. The resulting HTML then replaces the markdown defining them as a one-line HTML block. If necessary additional empty lines are inserted in order to keep the rows in line with the original one.

As a side effect of this techniqe multi-line code blocks loose their newline characters because the HTML is converted into a single line. For that reason <br> tags are inserted to preserve those newlines.

This document refers to version 5.5.0 of MarkAPL.
Kai Jaeger ⋄ APL Team Ltd ⋄ 2018-10-14


Footnotes

  1. http://LeanPub.com