Block Elements

Broadly speaking, Markua documents consist of three things: block elements, span elements and metadata. Paragraphs, headings, figures and lists, all discussed earlier, are examples of block elements. Block elements are separated from each other by at least one blank line.

These are the remaining block elements defined by Markua.

Scene Breaks (* * *)

In fiction, scene breaks are sometimes added between paragraphs in a chapter to denote a break in context. To add a scene break, add three or more asterisks on a line by themselves, with or without spaces between them. For example, ***, * * * and ********** on a line by themselves all produce a scene break.

Example:

This is before the scene break.

* * *

This is after the scene break.

Blockquotes (>)

Blockquotes in Markdown are created by prefacing lines with > , i.e. a greater than character followed by a space:

This is the first paragraph.

> This is a blockquote.
>
> It is outside the paragraphs.

This is the second paragraph.

Blockquotes in Markua are created in one of two ways:

1. By prefacing lines with > , i.e. a greater than character followed by a space.
2. By wrapping the blockquote in {blockquote} … {/blockquote}

Option #1 is preferable for short quotes; option #2 is easier on authors for really long quotes.

Like figures and tables, blockquotes can be inserted in the middle of a paragraph or as a sibling of it.

These Markua blockquotes are siblings of the paragraphs:

This is the first paragraph.

> This is a blockquote.
>
> It is outside the paragraphs.

This is the second paragraph.

{blockquote}
This is a blockquote.

It is outside the paragraphs.
{/blockquote}

This is the third paragraph.

These Markua blockquotes are nested in the paragraph:

This is the first paragraph.

This is the second paragraph.
> This is a blockquote
>
> It is inside the second paragraph.
This is part of the second paragraph.
{blockquote}
This is a blockquote.

It is inside the second paragraph.
{/blockquote}
This is part of the second paragraph.

This is the third paragraph.

A blockquote can contain other block-level elements, most commonly paragraphs.

If you are using the {blockquote} … {/blockquote} approach, this is trivial: just pretend you’re in a normal paragraph, and the syntax is the same.

If you are using the Markdown approach of >, then to start a new block level element within a blockquote, just put a line starting with a > followed by a space, followed by the block level element. It is equivalent to placing a > and a space in front of every line of the paragraphs.

In Markdown, a single newline inside a blockquote (where both lines are preceded by a > and a space) adds a single space. In Markua, however, a single newline inside a blockquote adds a forced line break. This is identical to how single newlines inside a normal Markua paragraph function. This is discussed at length in the Single Newlines section earlier. Note that it means you cannot manually wrap blockquotes to make them look nicer. Manually wrapping blockquotes is tedious and discourages editing of your own work. If you have really long blockquotes which span multiple paragraphs, the {blockquote} syntax is more pleasant to write in.

Blockquotes can be multi-paragraph. To create a multi-paragraph blockquote, you need to separate each paragraph with a line containing a > and (optionally) whitespace.

If a blockquote contains headings, these headings may be formatted by Leanpub differently than normal headings. Finally, if Leanpub is automatically generating a Table of Contents from chapter and section headings, any headings inside blockquotes should be ignored.

Asides (A> or {aside})

Since Markua is for writing books, including technical books, it needs not just a syntax for blockquotes–it also needs a syntax for asides and for blurbs. These syntaxes are very similar to the Markua syntax for blockquotes. Like blockquotes, any headings inside asides or blurbs do not show up in a Table of Contents (if one is present).

We will consider asides first.

Asides are typically short or long notes in books which are tangential to the main idea–sort of like footnotes, but in the body text itself. In technical books, quite often they are formatted in a box. Asides can span multiple pages.

The syntaxes for asides are very similar to blockquotes:

1. By prefacing lines with A> , i.e. an A, then a greater than character (>), then a space.
2. By wrapping the aside in {aside} … {/aside}

Option #1 is preferable for short asides; option #2 is easier on authors for really long asides.

For consistency with blockquotes, asides can be siblings of paragraphs or nested in them.

Here’s a short aside:

A> This is a short aside.

Here’s a longer aside, which also contains a heading:

A> # A Longer Aside
A>
A> This is a longer aside.
A>
A> It can have multiple paragraphs.
A>
A> The `A> ` stuff can get tedious after a while.
A>
A> This is why the `{aside}` syntax exists.

Here’s a longer aside using the {aside} syntax, which also contains a heading:

{aside}
# A Note About Asides

This is a longer aside.

It can have multiple paragraphs.

Asides can also have headings, like this one does.

Multi-paragraph asides are more pleasant using this syntax.
{/aside}

Blurbs (B> or {blurb})

Blurbs are like asides, but shorter. A blurb is not intended to span multiple pages of output.

The syntaxes for blurbs are very similar to asides:

1. By prefacing lines with B> , i.e. a B, then a greater than character (>), then a space.
2. By wrapping the blurb in {blurb} … {/blurb}

Examples:

B> This is a short blurb.

B> # A Longer Blurb
B>
B> This is a longer blurb.
B>
B> It can have multiple paragraphs.

{blurb}
#A Longer Blurb

This is a longer blurb.

It can have multiple paragraphs.
{/blurb}

Supported Attributes for Blurbs

Blurbs also have support for an attribute list, which can contain a class attribute as well as other implementation-specific “extension attributes”.

Blurb class Types

Markua has its origin in authoring computer programming books. In computer programming books, there are a number of blurb types which are a de facto standard:

• center
• discussion
• error
• information
• tip
• warning

These blurb types can be set on a blurb as its class attribute. Leanpub can optionally style these blurbs appropriately based on the class, for example by adding custom icons for each class of blurb.

Here’s how this looks with the B> syntax:

{class: warning}
B> This is a warning!

Here’s how this looks with the {blurb} syntax:

{blurb, class: warning}
This is a warning!
{/blurb}

Syntactic Sugar for Specific Blurb Classes: D>, E>, I>, Q, T, W>, X>

Having to constantly type {class: warning} in a computer programming book with a number of warnings would get tedious, as would any of the other blurb classes listed above.

So, Markua defines a standard shorthand syntax for these classes of blurbs. With this syntax, you use a different letter than B in the B>, to create a blurb with the appropriate class.

These are the syntactic sugar values you can use which have a heritage in computer programming books:

Examples:

D> This is a discussion blurb.

E> This is an error blurb.

I> This is an information blurb.

Q> This is a question blurb.

T> This is a tip blurb.

W> This is a warning blurb.

X> This is an exercise blurb.

These are equivalent to:

{class: discussion}
B> This is a discussion blurb.

{class: error}
B> This is an error blurb.

{class: information}
B> This is an information blurb.

{class: question}
B> This is a question blurb.

{class: tip}
B> This is a tip blurb.

{class: warning}
B> This is a warning blurb.

{class: exercise}
B> This is an exercise blurb.

These are also equivalent to:

{blurb, class: discussion}
This is a discussion blurb.
{/blurb}

{blurb, class: error}
This is an error blurb.
{/blurb}

{blurb, class: information}
This is an information blurb.
{/blurb}

{blurb, class: question}
This is a question blurb.
{/blurb}

{blurb, class: tip}
This is a tip blurb.
{/blurb}

{blurb, class: warning}
This is a warning blurb.
{/blurb}

{blurb, class: exercise}
This is an exercise blurb.
{/blurb}

Note that Q> and X> are a bit controversial:

• Q> defines a blurb which is formatted like a question, but {quiz} (discussed later) defines a quiz, and quizzes have actual numbered questions in them. It is unfortunate that the words quiz and question both start with the letter Q, and that the question blurb is not the same thing as a question in a quiz.
• X> defines a blurb which is formatted like an exercise, but {exercise} (discussed later) defines a structured exercise similar to a quiz. It is unfortunate that the term “exercise” is used for both.

There are issues, in both cases. However, the alternative is worse: removing the Q> or X> syntax would cause issues for every author who is familiar with, or has a manuscript formatted in, Leanpub Flavoured Markdown. This is not worth the reduced functionality, just to avoid one possible bit of confusion and one naming collision. So, the Q> and X> blurb syntactic sugar do exist, as do the {class: question} and {class: exercise} full blurb syntaxes.

Also note that nothing in this section defines what Leanpub must do with the given class of blurb. Leanpub, for example, uses it to add an appropriate icon from Font Awesome at the left of the blurb.

Finally, note that specifying a class in metadata overrides what the syntactic sugar does:

{class: tip}
W> This is a tip blurb, not a warning blurb.

Leanpub is free to either override this silently, or to raise an error if this happens.

Using Blurbs to Center Text with C>

You can also use a blurb to center text.

The following two ways to do this are equivalent:

C> This is a centered blurb.

{class: center}
B> This is a centered blurb.

This is the only way to center text in Markua.

Unlike other blurb types which have their origin in technical books, centering text has a wide range of uses. So, it could have been thought of as something different than a blurb. However, in terms of its behaviour and the way it’s inserted, centered text is a blurb–whether it’s inserted via syntactic sugar or via a class attribute on a normal blurb element. So, it’s discussed here.

Using Extension Attributes on Blurbs to add icon Support

Leanpub adds an icon attribute to blurbs. Markua does not specify that a blurb must support an icon attribute, or what it would mean if it did. However, Leanpub understands an icon attribute to reference an icon from Font Awesome. The value of this attribute is assumed to be the name of an icon in Font Awesome, without the fa- prefix. So, in Leanpub, you can do this:

{icon: car}
B> You can't spell carbon without it!

{icon: leanpub}
B> Yes, we're in Font Awesome!

{icon: github}
B> So is GitHub, of course. Unicorns.

In Leanpub, this will produce a nice icon of a car, using the Font Awesome icon.