LeanPub Extensions

LeanPub[¹] 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.

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←{(∨\' '≠⍵)/⍵}

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

A> Asides offer additional information.

This appears as:

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:

{(+⌿⍵}÷≢⍵}

Notes:

• In case you specify a level-1 (<h1>) or a level-2 (<h2>) header in an Aside 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.
• Headers defined in an Aside do not make it into the table-of-contents, and therefore they don't show in Meddy's tree view — representing the TOC — either.

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

• Information
• Discussions
• Exercises
• Errors
• Warnings
• Questions

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.

This:

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

leads to this:

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:

About Specialties

All specialties share a number of properties:

• They all have an icon to make it easier to identify them.
• They all have plenty of white space in order to tell them apart from ordinary text.

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.

This:

D> Reserve time for discussions

results in:

Reserve time for discussions

More complex:

Regarding Discussions

• Reserve time for discussions
• Start early

This:

X> Today's exercise

results in:

Today's exercise

More complex:

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.

{(+⌿⍵}÷≢⍵}

This:

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

results in:

Errors exists only to be made. Off we go!

More complex:

About Errors

There is so much more to say regarding errors…

This:

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

results in:

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

More complex:

A word of warning

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

This:

Q> Any questions?!

results in:

Any questions?!

More complex:

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!

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