LeanPub Extensions

Overview

LeanPub[1] serves as a publishing platform primarily designed for technical books.

The input format for LeanPub is Markdown. However, Markdown lacks certain features necessary for book publishing. As a solution, LeanPub introduced extensions to Markdown:

Code Highlighting

You can emphasize lines within code blocks.

Asides or Text Boxes

Used to discuss tangential topics or provide advanced information.

Specialties

Distinct message types combined with icons for various purposes.

Starting from version 3.6, MarkAPL has incorporated support for LeanPub extensions, enhancing Markdown with proper markup in both MarkAPL style sheets.

Let's explore these extensions in detail.

1. Highlighting Code

Code highlighting involves using leanpub-start-insert and leanpub-end-insert tags as illustrated here:

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

Note that the leanpub-*-insert strings in the code block above are visible but have no effect due to an escape character (\) before them in the document itself.

Without the escape character, the result would be:

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

2. Asides or Text Boxes

Asides require empty lines around them in Markdown to be recognized. A simple example:


A> Asides offer additional information.

This appears as:

Asides offer additional information.

Inside an aside, Markdown features like headers, code blocks, and lists are available:

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

Specialties are embraced by empty lines in Markdown. LeanPub offers special markup for various purposes:

Detailed examples of each specialty are provided in the text.

A word of warning: making use of the specialties prevents any HTML document created by MarkAPL from being truly 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 actual icons you can specify a different location and put your favourite icons there. However, you can not change the names of the LeanPub extension icons.

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

This:

D> Reserve time for discussions

results in:

Discussion

Reserve time for discussions

More complex:

Discussion

Regarding Discussions

Exercise

This:

X> Today's exercise

results in:

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

This:

E> Errors exists only to be made. Off we go!

results in:

Error

Errors exists only to be made. Off we go!

More complex:

Error

About Errors

There is so much more to say regarding errors…

Warning

This:

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

results in:

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

This:

Q> Any questions?!

results in:

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 HTML then replaces the Markdown as a one-line HTML block. If necessary additional empty lines are inserted in order to keep the rows in line with the original ones.

Because HTML blocks are left alone when the actual Markdown is processed that works pretty well. There is one downside however: since empty lines define the end of an HTML block, any empty lines within a LeanPub extension are converted into   which in HTML speak is a non-breakable space.

As a side effect, 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 11.1 of MarkAPL.

Kai Jaeger ⋄ 2020-10-31

Last Update: 2023-08-13


Footnotes

  1. http://LeanPub.com