The Markua Specification

The Markua Specification
The Markua Specification
Buy on Leanpub

Table of Contents

The Magical Typewriter

Imagine you owned a magical typewriter.

When you used this magical typewriter, you wrote with fewer distractions. You didn’t just write faster, you wrote better.

With your magical typewriter, you never worried about layout. The book formatted itself.

You could hit a key on your magical typewriter to create an ebook from your manuscript with one click.

All ebook formats would be created, and they’d all look good. You’d have PDF for computers, MOBI for Kindle, and EPUB for everywhere else. The book would look great on phones.

With your magical typewriter, you could publish your book before it was even done, and get feedback from readers all over the world. You could automatically share book updates with them. You would press one key on your magical typewriter to publish a new version, and all your readers would have it instantly.

With your magical typewriter, you could easily compare your current manuscript to any other version of your manuscript that had ever existed.

When the book was done, if you decided to make a print book, you could press a key on your magical typewriter to generate InDesign with one click. Your designer or publisher could use this as a starting point for producing a great looking print book.

With your magical typewriter, you’d only have to do one thing: Write.

Wouldn’t it be great if such a magical typewriter existed?

It does. At Leanpub, we’re building it.

But there’s one requirement for this magical typewriter to exist: a simple, coherent, open source, free, plain text format for a book manuscript.

This simple format is what authors will write their books in, instead of Word. It will enable an ecosystem of tools to emerge around it.

This simple format will be the basis for the magical typewriter.

This simple format is called Markua.

This is its specification.

Overview

Note for Leanpub Authors

Leanpub authors please read this first to see an incomplete list of what we still need to build in Leanpub. Also, please note that statements about Leanpub for Courses are “forward-looking statements” – Leanpub for Courses is currently in private beta. To request access to the beta, email hello@leanpub.com.

What is Markua?

Markua, pronounced “mar-coo-ah”, is the best way in the world to write books.

Markua is extremely simple and powerful. If you want to write a novel in Markua, you can learn the Markua syntax that you need to know in 30 seconds (see below). If you want to write a computer programming book or doctoral thesis in Markua, order a pizza: you can learn the additional syntax you need in less than 30 minutes.

Markua is terse. When you are writing using Markua, you are writing, not programming. Once you understand Markua’s syntax, it fades into the background.

Markua is opinionated. There is only one way to do almost everything.

Markua is designed for the writing of books, but it can also be used for other purposes. You can write journal articles in Markua, and you can even create courses in Markua. For example, Leanpub authors can click a button to create a massive open online course (MOOC), complete with automated marking, entirely from a Markua source document.

In this specification, however, I will talk exclusively about books: saying “books, documents and courses” would be annoying to write–and even more annoying to read!

Markua is a plain text format. Markua manuscripts, called Markua documents, can be written however you want. On a computer, you can use any text editor you want. Beginning authors can use things like Notepad or TextEdit; programmers can use Emacs, vi, Sublime or Atom; writers who like minimalist programs can use “distraction-free” programs like iA Writer or even physical devices like the Freewrite. You can also write Markua in any online editor which supports plain text or Markdown editing: since Markua syntax is so similar to Markdown syntax, many programs will already format Markua documents nicely.

Markua documents can be automatically transformed into every currently-popular type of ebook format. The computer programs which do this transformation are called Markua Processors. These programs understand both Markua syntax and how to generate the various output formats. An example Markua Processor is Leanpub: Leanpub can output PDF, EPUB, MOBI, HTML and InDesign all from the same Markua source document.

How to Write a Novel in Markua

You only need to know seven things to write a novel in Markua:

  1. To make a new chapter you start a line with a pound sign (#), followed by a space, the name of the chapter and a blank line:
    # The Chapter Name
  2. To make a new paragraph, hit Enter twice to add a blank line.
  3. Chapter headings and paragraphs are separated by blank lines.
  4. Surround text with one asterisk (*) on each side to make it *italic*.
  5. Surround text with two asterisks (**) on each side to make it **bold**.
  6. To add a scene break, put three asterisks on a line by themselves, with blank lines above and below them:
    * * *
  7. All other text and punctuation is typed normally:
     He asked, "How do you type quotes?" "Like this," I replied.

That’s it!

Minimal Formatting

When you are writing, formatting is procrastination. Writing is hard enough without needing to worry about formatting. Markua is a format for use by writers, not book designers.

So, Markua provides fairly minimal formatting options. Almost all formatting provided in Markua is semantic formatting. This is formatting which has meaning in the text, and which could not be changed by a book designer without possibly changing the meaning of the text.

To emphasize how little formatting is in Markua: Markua doesn’t have any concept of font sizes or margins! Also, Markua really, really, really does not care about “widows and orphans”–unless they’re people!

Markua: Markdown for Books

Markua is based on Markdown. Markdown is a plain text format for writing text which can be transformed by Markdown processors into HTML. Markdown was created by John Gruber, with help from Aaron Swartz. Markdown was described by John Gruber as follows:

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

The primary reason that Markdown is a great way to write is that it was designed to be this way:

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.

Markua is heavily inspired by Markdown. What Markua does is to map most (not all!) Markdown syntax to book concepts, as well as adding new syntax and concepts of its own.

The most popular subset of Markdown exists virtually unchanged in Markua. For example, all the Markua syntax described earlier as necessary to write a novel is inherited verbatim from Markdown.

One of the design goals of Markua is for it to be the most straightforward way for a Markdown document to become a book. So, if you already write your blog posts or lecture notes in Markdown, they are probably already valid Markua. You can use any Markua Processor, such as Leanpub, to turn them into an ebook with one click. Then, as you go down the path of enhancing the manuscript and adding things which only make sense in books, this process will feel like adding, not converting. The process of going from a Markdown document into a Markua ebook is mostly a process of decorating–enhancing and reinterpreting the Markdown document appropriately. In fact, one of the goals is for writers who are familiar with Markdown to feel as though they are still writing in Markdown, but that Markdown somehow grew an understanding of book concepts. Markua is really “Markdown for books”.

Text Formatting

Markua’s goal is to provide all the semantic formatting required by authors. Formatting that could be done by a book designer without needing to discuss it with the author is considered orthogonal to Markua, and is largely omitted from Markua.

Markua is a plain text format designed for the writing of books. Books have various types of text formatting in them: bold, italic, underline, strikethrough, superscript and subscript.

Here’s how to do basic, semantic text formatting.

Italic
To produce italic text, surround it with either _one underscore_ or *one asterisk*.
Bold
To produce bold text, surround it with either __two underscores__ or **two asterisks**.
Bold + Italic
To produce bold + italic text, surround it with either ___three underscores___ or ***three asterisks***.
Underline
To produce underlined text, surround it with ____four underscores____. This is gross, but it’s a tradeoff for Markdown compatibility: the one, two and three underscore choices were taken. Thankfully, it’s usually preferable to use italic instead of underline. However, underline is not just a typewriter version of italics. In some languages, underlining serves a distinct, legitimate purpose.
Strikethrough
To produce strikethrough text, surround it with ~~two tildes~~. This is the same syntax as is used by both GitHub Flavored Markdown and by John Macfarlane’s excellent pandoc.
Superscript
To produce superscript like the 3 in 53 = 125, surround it with carets like 5^3^ = 125. (This is the same syntax as is used by pandoc.)
Subscript
To produce subscript like the 2 in H2O, surround it with single tildes like H~2~O.

Note that if the asterisks and underscores needed to produce bold and italic are not nested correctly, they will be output as asterisks and underscores instead of producing formatting. This includes combinations like **_this**_, *__this*__ or __*this__*.

Headings

Markua is a way of writing books. Books have things like chapters, sections and subsections. Sometimes books have parts, e.g. Part One and Part Two.

Here’s the way that headings are made in Markua:

# Part #

This is a paragraph.

# Chapter

This is a paragraph.

## Section

This is a paragraph.

### Sub-Section

This is a paragraph.

#### Sub-Sub-Section

This is a paragraph.

##### Sub-Sub-Sub-Section

This is a paragraph.

###### Sub-Sub-Sub-Sub-Section

This is a paragraph.

Specifically, to create a Markua heading, you put the following on a line by itself:

  • between one and six pound signs (#)
  • followed by exactly one space
  • followed by text
  • followed (only for parts) by exactly one space and exactly one pound sign

A Markua heading usually needs a blank line above and below it. There are two exceptions: if it’s at the beginning of a manuscript file, you can omit the blank line above it; if it’s at the end of a manuscript file, you can omit the blank line below it.

Making these headings divides your book or document into these divisions. If you add part headings, your book will have parts; if you don’t, it won’t. If you add chapter headings, your book will have chapters; if you don’t, it won’t.

Markua is very strict about its heading syntax:

  1. In Markua, to make a part heading you make a heading like # Title #–the heading starts with exactly one pound sign and exactly one space, and ends with exactly one space and exactly one pound sign. No other combination of pound signs and spaces makes a part heading.
  2. Part headings end with a space and a pound sign, but other than that, headings cannot have optional pound signs at the end of them. Any other pound signs are considered to be text in the heading.
  3. All headings must start with between 1 and 6 pound signs (#) and then have exactly one space, followed by text. If any other number of spaces is used or if tabs are used, the text must be interpreted as a paragraph by a Markua Processor, not as a heading. (This ensures that Markua manuscripts look consistent for authors, and can be parsed more easily by Markua Processors. Also, if we allowed spaces to be omitted, you couldn’t start paragraphs with a #hashtag–which has not been a problem traditionally, but which might be these days.)
  4. Headings must be separated from other block elements by blank lines (created by two newlines) both before and after them. Because of the way that Markua concatenates files, headings at the top of a Markua document automatically have a blank line above them, and headings at the bottom of a Markua document automatically have a blank line below them. So, headings at the top of a document only need a blank line below them, and headings at the bottom of a document only need a blank line above them.
  5. If there is only a single newline after the heading, a Markua Processor must consider the subsequent text to be part of the heading. If a Table of Contents is generated, the newline is converted into a space. This rule means that the entire contents of the next paragraph will be part of the heading, which will be caught, since it will look like an obvious error in the book.

To learn more about the design goals of Markua headings and the differences between Markua and Markdown headings, see the appendix.

Paragraphs and Blank Lines

The distinguishing thing about a paragraph is that there is nothing else distinguishing about it: unlike headings, lists and other Markua elements, a paragraph requires no special formatting. To create a new paragraph, you add two newlines to create a blank line.

Here’s an example of this in Markua syntax. These are three paragraphs in Markua, each separated by the canonical two newlines which produce one blank line:

I'm paragraph one. Yay!

This is paragraph two.

This is paragraph three.

There are other more technical rules about spaces, newlines and indentation, which are discussed later.

Resources

Markua documents are written in plain text, either in one text file or multiple text files. However, modern books sometimes contain more than text. Books may embed many types of resources. Each type of resource has a number of supported formats. Markua’s goal is to make inserting all types of resources simple and consistent, while staying as close to Markdown’s syntax as possible.

Resources vary in four different ways:

  1. Insertion Methods: Span and Figure
  2. Locations: Local, Web and Inline
  3. Types: audio, code, image, math, poetry, table and video
  4. Formats: png, m4a, mp3, ruby, latex, etc.

Before going into more detail, it’s helpful to consider a brief example of Markua text which shows a number of resources being inserted. These resources have different insertion methods (span and figure), different locations (local, web and inline), different types (image, code) and different formats (png, jpg, ruby)–yet the syntax to insert them is compact and consistent:

Inserting an image as a figure is...

![A Piece of Cake](http://markua.com/cake.jpg)

Inline code resources are added as spans like this `hello world` or as figures.

```ruby
puts "hello world"
```

{format: ruby}
![Hello, World](hello.rb)

The last figure in the example above showed an attribute list, which is a list of key-value pairs in curly braces. Any figure can have an attribute list, regardless of resource location, type or format. Attribute lists are explained in depth later.

If you’re familiar with Markdown syntax, you’ll note that the syntax for local and web resources is similar to Markdown’s inline image insertion syntax, and that the syntax for inline resources is similar to the fenced code blocks syntax from popular Markdown extensions including GitHub Flavoured Markdown.

Tables are also resources, and can also be local, web or inline. However, the table syntax is more elaborate than the syntax for the other resource types, so we discuss tables later.

Resource Insertion Methods

Resources can be inserted either as spans or as figures. All resources can be inserted as figures, but only inline code and math resources can be inserted as spans.

We will discuss figures first and then spans.

Figures

When a resource is properly inserted as a figure, the resource is inserted with at least one newline before and after it.

A figure can either be top-level (with a blank line before and after it), or it can be contained in a paragraph. The ways that figures and other block elements can be inserted in paragraphs as discussed in depth later.

The syntax for a local resource or a web resource inserted as a figure is as follows:

{key: value, comma: separated, optional: attribute_list}
![Optional Figure Caption](resource_path_or_url)

The syntax for an inline resource inserted as a figure is as follows:

{key: value, comma: separated, optional: attribute_list}
```optional_format
inline resource content (default format is `guess`)
```

Note that you can also insert an inline resource as a figure using tildes as the delimiter. If the only delimiter was backticks, it would be really difficult to write about Markua in Markua. This syntax is as follows:

{key: value, comma: separated, optional: attribute_list}
~~~optional_format
inline resource content (default format is `text`)
~~~

Note that exactly three backticks or three tildes must be used to insert an inline resource as a figure. If more backticks or tildes are used, these will be interpreted as normal text.

Figure Attributes

A figure can also have attributes. The supported attributes vary based on the type of resource, but all figures support the caption, class, format, title and type attributes. (As such, these five attributes are not shown on the specific resource types below.)

caption
This is text which is shown near the figure, typically above or below it. A Markua Processor can choose where to position captions based on any criteria it chooses. For example, a Markua Processor can position all captions above or below figures, or use a different behaviour based on the resource format. Note that the figure caption itself may contain the Markua text formatting specified earlier in the Text Formatting chapter.
class
Any attribute list supports a class attribute. When used in figures, this is the class of the figure. This can be used for styling, and it can also be used by Markua Processors which wish to group figures by classes (e.g. theorems, lemmas, etc).
format
This is the resource format. Different resource types have different legal values for format.
title
This is text which is displayed for the figure wherever the figure is listed (e.g. List of Illustrations, Table of Tables, etc.). If no title is provided, the caption should be used in those places.
type
This is the resource type. This is usually inferred from the format instead of being specified.

Figures can have alt text and a figure caption. The alt text and figure caption are distinct things. We will discuss the figure caption first and the alt text second.

Figure Captions

A resource which is inserted as a figure can have a figure caption.

This caption shows up in two places in the output:

  1. Near the resource, typically above or below it, per the preference of the Markua Processor.
  2. Based on the resource type, either in the List of Illustrations, List of Tables or Table of Figures, if they are generated for the book. This text should also be a crosslink to the caption inserted near the figure itself.

The caption for a figure can be provided either in the square brackets in front of a local or web resource or in the attribute list above the resource:

![My Amazing Algorithm](algorithm.rb)

{caption: "My Amazing Algorithm"}
![](algorithm.rb)

The first choice is clearly shorter, as well as more pleasant to write and to read.

Note that inline resources have no square brackets, so any captions must be added in the attribute list:

Here's a paragraph before the figure.

{caption: "My Amazing Algorithm"}
```ruby
puts "hello world"
```

Here's a paragraph after the figure.

Figure Alt Text

A figure can have alt text, as long as the type of resource being inserted supports alt text. The alt text is defined in an attribute list above the figure. Since the alt text is defined in the attribute list, the resource location does not matter: local, web and inline resources all support alt text.

The four types of resource which can have alt text when inserted as a figure are image, video, audio and math. Resources of type code and table do not support alt text, since they themselves are just text. If any alt text is provided for a code or table resource it is ignored.

Alt text is text which is intended to take the place of the resource if the resource itself cannot be seen. In the case of images, the obvious use case is for readers with visual disabilities who are using a screen reader, but it also includes audiobooks and ebook readers which often do not support embedded images, audio and video.

The alt text should not have the same content as the figure caption, if the figure caption is present. (Imagine the annoyance of having a visual disability and having your screen reader read identical alt text and figure captions to you throughout an entire book!) Instead, the alt text should be descriptive of the image content, while the figure caption can be more creative. For example, a figure caption may be “Washington Crossing the Delaware” and the alt text could be “Denzel Washington riding a jet ski in a river”. Having good alt text would enable readers who cannot see the image to still get the joke which the figure caption makes.

Figure Captions and Alt Text Together

These are some examples of figures with both alt text and a figure caption:

{alt: "Denzel Washington on a jet ski in a river"}
![Washington Crossing the Delaware](delaware.jpg)

{alt: "Denzel Washington on a jet ski in a river", caption: "Washington Crossing the Delaware"}
![](delaware.jpg)

{caption: "Earth From Space (Simplified)", alt: "a blue circle"}
```svg
<svg width="20" height="20">
  <circle cx="10" cy="10" r="9" fill="blue"/>
</svg>
```

The Figure Attribute List Takes Precedence

It is always an error to specify an attribute both in the attribute list for a figure and in the syntactic sugar locations, either after the backticks or in the square brackets.

However, if this is done, then the value in the attribute list takes precedence.

In the following figure, the format is text not ruby:

{format: text}
```ruby
puts "hello world"
```

In the following figure, the caption would be “Foo” not “bar”:

{caption: Foo}
![bar](foo.png)

Again, both of these are not good Markua: attribute values should be specified only once.

Spans

Two types of resources can be inserted as inline spans: code resources of format text, and math resources.

An inline code resource of text format can be inserted as a span using the following syntax:

It's a single backtick `followed by inline resource content` and then a single backtick.

An inline math resource of latex format can be inserted as a span using the following syntax:

It's a single backtick `followed by inline resource content`$ and then a single backtick and dollar sign.

The code and math resources are described more fully later. (You can actually insert a math resource of mathml format as a span, but that’s really verbose!)

When a resource is inserted as a span, the resource is inserted as part of the flow of text of a paragraph with no newlines before or after it. A span resource is intended to be extremely short and simple. However, to support rare use cases, any span can have an attribute list. The attribute list on a span is specified immediately after the closing backtick. Examples of this are shown in the code and math sections.

Finally, if you wish to insert an image in the middle of a sentence, chances are you are trying to insert an emoji. Emoji have special support in Markua, described here.

Figures That Look Like Spans

If a local or web resource is inserted with no newlines before or after it, the resource is NOT inserted as a span. Instead, it is treated as though there was one newline before and after the resource, and the resource is inserted as a figure with a single line break before and after it.

The following two paragraphs are equivalent:

Here's some text ![Foo](bar.png) and more text.

Here's some text
![Foo](bar.png)
and more text.

In both cases, the bar.png image is inserted as a figure, and the text in the square brackets is the figure caption, not the alt text. The text in square brackets before a local or web resource is always the figure caption. Also, in both cases, the text which follows the figure is part of the same paragraph as the text which precedes the figure, unless there are two newlines after it to start a new paragraph. This is discussed further here. Even though both images above are inserted as figures, in the first case there is no way to specify alt text. This is why the implicit newline approach is inferior to using explicit newlines, since with explicit newlines an attribute list can be defined on the figure like this:

Here's some text
{alt: "a shoal"}
![Foo](bar.png)
and more text.

Finally, note that this is all true for all local or web resources, regardless of resource type. The following two paragraphs which contain a web code resource are also equivalent:

Hello in Ruby is a simple ![Hello World in Ruby](http://markua.com/hello.rb) statement.

Hello in Ruby is a simple
![Hello World in Ruby](http://markua.com/hello.rb)
statement.

For the purpose of brevity, this point will not be explained in each section about different resource formats.

To be clear:

  • All local or web resources are inserted as figures. It is not possible to insert any type of local or web resource as a span.
  • All table, image, audio and video resources are inserted as figures. It is not possible to insert table, image, audio or video resources inline as a span.
  • It is only possible to insert code and math resources inline as spans. The code is formatted as text, and the math is formatted as latex. The specific syntax for these use cases is covered later.

Resource Locations

A resource is either considered a local, web or inline resource based on its location:

Local Resource
The resource is stored along with the manuscript–either in a resources directory on a local filesystem, or uploaded to the same web service where the Markua document is being written.
Web Resource
The resource is referred to via an http or https URL.
Inline Resource
The resource is defined right in the body of a Markua document.

Local Resources

If local resources are used, all local resources must be stored inside a resources directory, or one of its subdirectories. The resources directory is not part of the path to the resource. Implementors of Markua Processors must ensure they do not support navigating upward with ../ in paths.

A file called foo.jpg in the resources directory is referenced as ![](foo.jpg)–not as ![](/foo.jpg), ![](resources/foo.jpg) or ![](/resources/foo.jpg).

A file called bar.png in a subdirectory images of the resources directory is referenced as ![](images/bar.png)–not as ![](/images/bar.png), ![](resources/images/bar.png) or ![](/resources/images/bar.png).

Markua does not specify whether there are any subdirectories of the resources directory, or what their names are. Since any subdirectories have their names as part of the path to the resource, implementations can do whatever they want. For example, Leanpub will create subdirectories of the resources directory for every type of resource (images, audio, video, code, math and tables), but this is not a requirement. (To be clear, the names of these directories have no meaning; they could be anything.)

The local resources approach can also be used by hosted services. Internally, services can store resources wherever they want, but if they provide a download (say as a zip file) they should create the resources directory and provide the uploaded resources in that directory. If a nested structure is used, it should be exported that way–if a web service produces paths which reference images inside an images directory (e.g. as images/foo.png), then the zip file centaining an export should contain a resources directory which contains an images subdirectory with the images.

Web Resources

If web resources are supported, both http: and https: resources should be supported.

Web resources are identified by the absolute URL of the resource on the internet.

Inline Resources

Inline resources can be of type code, math (regardless of format), table, or an image resources of svg format. Since an SVG image is just XML text, it can be contained inline in the text of a Markua document. This is not something that is true for binary resources like PNG or JPEG images or any type of audio or video file–these can only be local or web resources.

Resource Types and Formats

There are seven types of resources: audio, code, image, math, poetry, table and video. Each type of resource has a number of supported formats. Any of the seven resource types can be inserted as a local resource or web resource, and many of the resource types can also be inserted as an inline resource.

Both the type and the format can be specified in an attribute list, by the respective type and format attributes.

The type and the format can also be inferred from the file extension and, in the case of web resources, the URL. The following table shows the mapping of file extensions to the default format and type inferred. Note that these are just defaults: a resource can be set to be any type and format using the attribute list, and this overrides what is inferred from the file extension.

Formats Mapped to Resource Types
Extension format type Description
.aac aac audio AAC audio
.m4a aac audio AAC audio
.mp3 mp3 audio MP3 audio
.oga ogg audio Ogg Vorbis
.ogg ogg audio Ogg Vorbis
.wav wav audio WAV audio
.wave wav audio WAV audio
.txt text code Unformatted code
(other) guess code Formatted code
.gif gif image GIF image
.jpeg jpeg image JPEG image
.jpg jpeg image JPEG image
.png png image PNG image
.svg svg image SVG image
.svgz svgz image Zipped SVG
.mathml mathml math MathML math
.tex latex math LaTeX math
.text poetry poetry Poetry
.tbl table table Markua table
.mp4 mp4 video MP4 video
.webm webm video WebM video

Note that these file extensions are case-insensitive. Also, note that .mp4 is used for MP4 video, not MP4 AAC audio.

Also, as discussed in the code section, Markua Processors must interpret all unspecified file extensions as specifying a resource of type code with a format of guess, unless the resource is a web resource. If the type and format are not specified and the resource is a web resource, the Markua Processor may use the domain to decide what type of resource to assume. For example, a domain of youtube.com may be assumed to be of type video, a domain of instagram.com may be assumed to be of type image, and a domain of github.com may be assumed to be of type code.

If the type is not specified in the attribute list, the format determines the type. The formats can either be specified by the format attribute or (in most cases) inferred from the file extension for local and web resources. (Inline resources obviously have no file extension, since they are contained in the body of a Markua manuscript file.)

As an author, all you typically do is provide the correct file extension or set the format in the attribute list. Markua recognizes the format, and uses it to determine the type. If the format is unrecognized, then the resource is treated as a resource of type code and with a format of guess.

It’s important to emphasize that the type and format of a resource can be overridden using an attribute list. In rare instances, it is useful to override the type and format which have been inferred by the Markua Processor based on the file extension of the resource. This is done by specifying a type and/or format in the attribute list of the resource.

Three examples of when this could be desired are:

  1. When writing about, say, the SVG file format, you may want to treat a .svg file as a resource of type code instead of type image. This way, the SVG image (which is just XML text) would be shown as code, instead of interpreted as an image. This would be accomplished by the attribute list {type: code, format: text}.
  2. When writing about a programming language which is not identified correctly by a Markua Processor, you may want to force the format of the language.
  3. When writing about LaTeX math, you may want to force the type to be code not math.

We will now consider each of the types of resources in more detail, as well as the various formats that they support. We will also discuss the supported attributes for each resource type. Resources have different default attributes based on their type, format and insertion method.

Images

The syntax to insert an image is the same compact and consistent syntax that is used for any resource. Local and web resource locations are supported for any type of image; inline resource locations are supported for SVG images only.

Per the table of resource types and formats, the following types of images are supported in Markua: GIF, PNG, JPEG, SVG and zipped SVG.

Images are always inserted as figures.

We will discuss the supported and the default attributes for images, and then show examples of images being inserted for local, web and inline images.

Note that regardless of the image location, a Markua Processor can embed the image in the output format. For example, a web image does not need to be loaded from the web every time; it can be inlined in the output by the Markua Processor. A Markua Processor can also process images such that all images are placed on the web with URLs, and the images are loaded by the reader from the web.

Images have some of the only non-semantic formatting in Markua. Images can have width, height and float attributes, or can be fullbleed. These settings, which also apply to the posters for videos, are so universal when applied to images that it would be too purist for Markua to insist that the only way to format images was to add a class element, and then style the class of the image elsewhere. Markua is semantic, but it’s also pragmatic: by providing a few basic ways to format images, it enables authors to make in-progress books look good enough to publish in-progress.

Supported Attributes for Images

The following are the supported attributes for image resources, in addition to the type, format, caption and class attributes which all resources support:

alt
The alt is the alt text, to be displayed when the image cannot be shown. This is provided in the figure attribute list.
float
The float can be left, right, middle, inside, outside. Combined with width and height, this provides basic image formatting.
fullbleed
true or false. The default is false. If true, the Markua Processor should ensure that the image is the full size of the page, with no margins on the page. If false, the width, height and float attributes are used instead and margins are respected.
height
The height of the image, in percentage of page content area height (respecting margins). This is specified as an integer between 1 and 100.
cite
An image can have a citation. A Markua Processor is free to combine this citation with the caption attribute or display it separately.
url
An image can have a URL, which is the URL of the cite attribute if present. A Markua Processor is free to combine this URL with the cite and caption attributes however it wishes, e.g. by linking the cite attribute text to the url or showing the url in parentheses or in a footnote.
width
The width of the image, in percentage of page content area width (respecting margins). This is specified as an integer between 1 and 100.

Note that if only one of width and height are specified, the Markua Processor should scale the image proportionally if possible (again, respecting margins). If both width and height are specified, the Markua Processor should scale the image accordingly, ignoring the aspect ratio. (So, it’s almost always a bad idea to specify both width and height.)

For an example of the cite and url attributes, consider the following hypothetical image:

{alt: "a slice of chocolate cake", cite: "Peter's Food Photography", url: "http://peterarmstrong.com/pictures/\
1.jpg"}
![A Piece of Cake](cake.jpg)

The caption is “A Piece of Cake”, and the question of what to do with the cite and url attributes is dependent on the implementation of the Markua Processor.

Local Images

The following are some examples of local images:

Here's a paragraph before the first figure.

![A Piece of Cake](cake.jpg)

Here's a paragraph between the first and second figures.

{alt: "a slice of chocolate cake", fullbleed: true}
![A Piece of Cake](images/cake.jpg)

Here's a paragraph between the second and third figures.

{alt: "a slice of apple pie with ice cream on top", class: "food-closeup"}
![A Piece of Pie](pie.jpg)

Here's a paragraph after the third figure.

In the above example, the first and third images were directly in the resources directory, whereas the second image was in an images subdirectory of the resources directory.

Web Images

The following are some examples of web images:

Here's a paragraph before the first figure.

![A Piece of Cake](http://markua.com/cake.jpg)

Here's a paragraph between the first and second figures.

{alt: "a slice of chocolate cake", fullbleed: true}
![A Piece of Cake](http://markua.com/cake.jpg)

Here's a paragraph between the second and third figures.

{alt: "a slice of apple pie with ice cream on top", class: "food-closeup"}
![A Piece of Pie](http://markua.com/pie.jpg)

Here's a paragraph after the third figure.

Inline Images (SVG only)

SVG images are just XML text, so they can be inserted inline in Markua:

Here's a paragraph before the figure.

{caption: "Earth From Space (Simplified)", alt: "a blue circle"}
```svg
<svg width="20" height="20">
  <circle cx="10" cy="10" r="9" fill="blue"/>
</svg>
```

Here's a paragraph after the figure.

Video

The syntax to insert a video is the same compact and consistent syntax that is used for any resource. Local and web resource locations are supported for both video formats; inline resource locations for video are obviously not supported.

A Markua Processor may choose to not support video at all, or to only support one of local or web video due to bandwidth or copyright concerns.

Unlike images, which are supported in most circumstances, with video files it’s currently a bit of a crapshoot. There’s currently a dominant proprietary format (H.264, or .mp4) and a new open source challenger (WebM). It’s entirely likely that many ebook readers won’t support either.

Also, unlike images where many images will accompany the manuscript itself, with video it’s expected that authors will be uploading their videos to sites such as YouTube first, and then reusing these videos in the contents of their Markua books. So, while video can be local or web video, web video will be much more prominent than web images in a Markua book.

Furthermore, unlike with web images where the format (and thus the type) are typically discoverable from the file extension in the URL, with web video it’s usually not. So, for web videos, there will typically be a {type: video} attribute list at a minimum. That said, if the type and format are not specified and the resource is a web resource, the Markua Processor may use the domain to decide what type of resource to assume. So YouTube videos may just work in some Markua Processors, like Leanpub, without specifying either the type or format.

Per the table of resource types and formats, the following types of videos are supported in Markua: MP4 and WebM.

We will discuss the supported and the default attributes for videos, and then show examples of videos being inserted for both local and web videos.

Supported Attributes for Video

The following are the supported attributes for video resources, in addition to the type, format, caption and class attributes which all resources support. Note that the caption, class, float, fullbleed, height and width attributes apply to the poster image for the video–not to the video itself during playback.

embed
true or false. If true, then you can actually embed the video file or reference it and play it. If false, then it’s from a site like youtube which disallows this. In this case, this should function like a link to external web page which (youtube app etc). A Markua Processor can be smart about defaults, and parse the URL to set the value of the embed attribute.
float
The float can be left, right, middle, inside, outside. Combined with width and height, this provides basic formatting.
fullbleed
true or false. The default is false. If true, the Markua Processor should ensure that the image is the full size of the page, with no margins on the page. If false, the width, height and float attributes are used instead and margins are respected.
height
The height of the image, in percentage of page content area height (respecting margins). This is specified as an integer between 1 and 100.
poster
The poster is the URL or path to an image which should be shown instead of the video before the video is played. If a Markua Processor is outputting some format where it is known that video resources are not supported, it must choose the poster to use as a replacement for the video. Books are not just ebooks–books can also be printed on the fibers of trees that have been chopped down (“paper”), producing something called a “book”. These “books”, whether they are bound in a sturdy fashion (“hardcover books”) or a flimsy fashion (“paperback books”), have one thing in common with respect to embedded video: they do not support it. Finally, if a Markua Processor is embedding a web video from a web video service (e.g. YouTube) which has a known algorithm for the location of the poster images for its videos, the Markua Processor may choose to use that poster image if a poster attribute is not explicitly specified. However, if a poster attribute is specified, then it must be used by the Markua Processor.
width
The width of the image, in percentage of page content area width (respecting margins). This is specified as an integer between 1 and 100.

Local Video

Here's a paragraph before the figure.

![A Piece of Cake](cake-eating-contest.webm)

Here's a paragraph after the figure.

Web Video

Here's a paragraph before the figure.

{type: video, poster: "http://img.youtube.com/vi/VOCYL-FNbr0/mqdefault.jpg"}
![Introducing Markua](https://www.youtube.com/watch?t=105&v=VOCYL-FNbr0)

Here's a paragraph after the figure.

Ironically, it took me about a year after that talk was recorded to finally figure out what Markua was.

Audio

Just as with video, the audio support in ebooks and on the web is more varied than for images. With audio, there are MP3, AAC, Ogg and WAV formats all in widespread use, and there are a number of other formats with supporters. It’s entirely likely that many ebook readers won’t support any of them.

A Markua Processor may choose to not support audio at all, or to only support one of local or web audio due to bandwidth or copyright concerns.

Per the table of resource types and formats, the following types of audio resources are supported in Markua: MP3, AAC, WAV and Ogg Vorbis.

The syntax to insert an audio file is the same compact and consistent syntax that is used for any resource. Local and web resource locations are supported for both audio formats; inline resource locations for audio are obviously not supported.

We will discuss the supported and the default attributes for audio files, and then show examples of audio being inserted for both local and web audio files.

Supported Attributes for Audio

There are no supported attributes for audio, other than the type, format, caption and class attributes which all resources support.

Local Audio

The full version of the talk is here:

![Full Talk](talk.m4a)

Web Audio

The full version of the talk is here:

![Full Talk](http://markua.com/talk.m4a)

Code

Code can be a local, web or inline resource, just like any other resource, and the same resource syntax applies to code as to all other resources.

As discussed, code cannot have alt text. It’s just text. If any alt text is provided for a code resource, it is ignored.

Markua specifies only one specific file extension to be associated with a type of code: the .txt extension, which is for the format of text. However, Markua Processors must interpret all unspecified file extensions as specifying a resource of type code with a format of guess.

Regardless of whether syntax highlighting is supported and the programming language is detected, all code must be formatted as monospaced text by Markua Processors.

The text format means to not do any syntax highlighting as well.

The guess format is a request for the Markua Processor to guess at the programming language based on the file extension and/or the syntax of the code itself. Then, if the detected language corresponds to a particular programming language which the Markua Processor recognizes, and if the Markua Processor supports syntax highlighting, then it can format the resource as nicely syntax-highlighted code. Syntax highlighting is entirely optional in Markua Processors. If a Markua Processor does not support syntax highlighting, and/or if it cannot detect a matching supported programming language, then it must format the code as though the format was text–i.e. to format it as unformatted monospaced text.

Besides the text and guess values of the format attribute, you can also specify the programming language by setting the format attribute to a specific programming language. This is more reliable than guess. Unlike other resource types, Markua does not specify the complete set of the values of the format attribute–there are so many programming languages in the world, and new ones are added so frequently, that doing so would be impractical.

The default value of the format attribute for code is complex:

  1. For code which is inserted as a span (which is only supported with inline resources), the default format is text.
  2. For code which is inserted as a figure which is inserted as an inline resource using three tildes, the default format is text.
  3. For all other code, the default format is guess. This includes local and web resources inserted as figures, and code inserted as an inline figure using three backticks.

Note that the default format can be overridden by specifying it via an attribute list, or after the three backticks in syntactic sugar.

Supported Attributes for Code

The following are the supported attributes for code resources, in addition to the type, format, caption and class attributes which all resources support.

line-numbers
This determines whether the code sample shows line numbers. Legal values are true or false. The default value is false. Any value other than true is interpreted as false.
number-from
If line numbers are shown, this lets you override the starting number of the line numbers. The default value is 1.
crop-start
Sometimes it’s desirable to only show part of a code resource defined in an external file as the code example. The crop-start and crop-end attributes let you accomplish this. The crop-start attribute defines the line which represents the first line included from the resource. For example, {crop-start: 10, crop-end: 15, line-numbers: true, number-from: 10} ensures that lines 10-15 are shown and are numbered as lines 10-15. The default value is 1, which is the first line of the file.
crop-end
This attribute ends the range started with crop-start. The default value of crop-end is to be omitted, which is equivalent to specifying the last line of the file.
Default Value of the format attribute in Inline Code Samples

The default value of the format attribute for a code resource inserted as a figure varies based on context.

If the code resource is a local or web resource, it defaults to guess.

If the code resource is an inline resource, the default varies based on the delimiter. With three backticks the default format is guess, and with three tildes, the default format is text. This way, you can vary the default without having to type an attribute list: if you want the code language guessed at, use backticks; if you don’t, use tildes. Of course, you can specify any attributes you wish with either delimiter, and specified attributes override default ones. The only reason there are different defaults are to make things easier to type. Programmers refer to such niceties as “syntactic sugar”.

Local Code Resources

Local code resources can be inserted as a figure. In all the following examples of figures, the text in the square brackets is the figure caption, like it is in all figures.

This first figure will be a type of code and a format of guess. A Markua Processor which associates .rb file extensions with Ruby code will treat this as Ruby code; a Markua Processor which has no association for .rb files will treat it as plain text:

Here's a paragraph before the figure.

![Hello World in Ruby](hello.rb)

Here's a paragraph after the figure.

That is equivalent to:

Here's a paragraph before the figure.

{format: guess}
![Hello World in Ruby](hello.rb)

Here's a paragraph after the figure.

If you don’t want to take chances you can do this:

Here's a paragraph before the figure.

{format: ruby}
![Hello World in Ruby](hello.rb)

Here's a paragraph after the figure.

Note that the caption is optional in all figures:

Here's a paragraph before the figure.

![](hello.rb)

Here's a paragraph after the figure.

Web Code Resources

Web code resources function identically to how local code resources work, including the significance of file extensions. The only differences is that the files are on the web.

This will be a type of code and a format of guess since the file extension is not specified:

![Hello World in Ruby](http://markua.com/hello.rb)

That is equivalent to:

{format: guess}
![Hello World in Ruby](http://markua.com/hello.rb)

If you don’t want to take chances you can do this:

{format: ruby}
![Hello World in Ruby](http://markua.com/hello.rb)

Note that in the above examples of figures, the text in the square brackets is the figure caption, like it is in all figures.

Inline Code Resources

Inline code resources are the most flexible way to insert code. They are the only way to insert code as a span resource, and the most straightforward way to add short code examples as figures.

Span

The format of an inline code resource inserted as a span is:

Yada yada `some code here` yada yada.

The format of code inserted as a span defaults to text. However, you can override this by attaching an attribute list to the end of a span.

In the following example, the first statement let the format of the code default to text, whereas the second statement specifies the format of the code as ruby:

Hello World in Ruby is a simple `puts "hello world"` statement.

Hello World in Ruby is a simple `puts "hello world"`{format: ruby} statement.

Note that there is no syntactic sugar for this, since I don’t like this, and I want it to be as distasteful as possible. So, this is a sort of “syntactic salt”. Syntax highlighting does not make much sense for code which is inserted in the middle of a sentence–there’s just not enough code there for it to be worthwhile. However, in Markua, any span can have an attribute list attached to it (in order to add index entries, for example), so there is no reason to explicitly forbid specifying a format in the attribute list.

Figure

Inline code resources work great as figures.

This will be a type of code and a format of guess since three backticks are used and since the format is not specified:

Some paragraph.

```
puts "hello"
```

Some paragraph.

That is equivalent to:

Some paragraph.

```guess
puts "hello"
```

Some paragraph.

If you don’t want to take chances you can do this to explicitly specify the format:

Some paragraph.

```ruby
puts "hello"
```

Some paragraph.

If you don’t like syntactic sugar you can do:

Some paragraph.

{format: ruby}
```
puts "hello"
```

Some paragraph.

If you want a figure caption, you can add it to the attribute list with any of the above. For example:

Some paragraph.

{caption: "Hello World in Ruby"}
```ruby
puts "hello"
```

Some paragraph.

Finally, if you want the code to definitely not get syntax highlighted, you can force format to be text in one of two ways.

First, you can set it explicitly:

Some paragraph.

```text
puts "hello"
```

Some paragraph.

Second, you can use three tildes instead of three backticks, since the default with tildes is text not guess:

Some paragraph.

~~~
puts "hello"
~~~

Some paragraph.

Marking Code as Added or Deleted

Markua supports marking code as added or deleted, which can be helpful if you are writing a computer programming book and want to indicate what code should be added or removed to a larger program.

The way to do this is to add special comment lines to your code.

The magic words are markua-start-insert, markua-end-insert, markua-start-delete and markua-end-delete. Any line containing one of those words will be removed completely by a Markua Processor before being inserted into the output.

The Markua Processor will then be able to determine which code is being deleted or inserted, and format it accordingly. The recommended way for a Markua Processor to do this is to make code which is being inserted get bolded, and to make code which is getting deleted to be put in strikethrough.

Finally, while syntax highlighting is optional in a Markua Processor, if a Markua Processor does support syntax highlighting it is allowed for the Markua Processor to not do any syntax highlighting when there is the presence of any of any special markua-* comments. Syntax highlighting may make it harder to notice the added and removed code, if they are formatted with bold and strikethrough respectively.

Line Wrapping in Code Resources

Code resources should have newlines added by the author to ensure that automatic line wrapping is not relied upon. Markua Processors may wrap lines to ensure that all code is visible on a page, and may add continuation characters (like the backslash \ character) in the output to indicate that a line has been automatically wrapped. However, adding a continuation character is not a requirement, nor is the choice of which continuation character is used.

Poetry

Poetry can be a local, web or inline resource, just like any other resource, and the same resource syntax applies to poetry as to all other resources.

Poetry can only be inserted as a figure. It cannot be inserted as a span resource, like code can.

Markua specifies only one specific file extension to be associated with a type of poetry: the .text extension, which is for the format of poetry.

Supported Attributes for Poetry

The following are the supported attributes for poetry resources, in addition to the type, format, caption and class attributes which all resources support.

monospaced
true or false. The default is false, except for a special case with inline poetry resources, discussed below. If true, the Markua Processor must use a monospaced font to output the poetry. If false, the Markua Processor may use whatever font (proportional or monospaced) it is configured to use to output poeetry.

Note that inside a poetry resource, Markua text formatting still applies. You can’t do arbitrary Markua stuff like headings, images and tables, but you can do the text formatting like bold, italic, strikethrough, etc. So, if you want to write poetry involving asterisks and underscores, use a code block.

Spacing, Poetry and Newlines

Regardless of the value of the monospaced attribute, all whitespace inside a poetry resource is respected. This includes all spaces and newlines, regardless of whether they are leading, internal or trailing spaces, and regardless of the number of consecutive newlines.

Poetry resources should have newlines added by the author to ensure that automatic line wrapping is not relied upon.

Markua Processors may wrap lines to ensure that all poetry is visible on a page, and may add continuation characters (like the backslash \ character) in the output to indicate that a line has been automatically wrapped by the Markua Processor.

Obviously, seeing a continuation character is in poetry is terrible, so the author should consider this a mistake that needs to be fixed by manually line wrapping.

Local Poetry Resources

Local poetry resources look like many other resources inserted as figures. The text in the square brackets is the figure caption, like it is in all figures.

Here's a Shakespearean sonnet:

![Sonnet 130](sonnet130.text)

Here's an E. E. Cummings poem:

{monospaced: true}
![I Will Be](iwillbe.text)

Web Poetry Resources

Web poetry resources function identically to how local poetry resources work, including the significance of file extensions. The only differences is that the files are on the web.

Here's a Shakespearean sonnet:

![Sonnet 130](http://markua.com/sonnet130.text)

Here's a paragraph after the figure.

Inline Poetry Resources

With an inline poetry resource, the default value of the monospaced attribute for a poetry resource varies based on the delimiter used.

There are two types of delimiters that can be used to insert a poetry resource inline:

---
With three hyphens, the default value of monospaced is true.
___
With three underscores (___), the default value of monospaced is false.

This way, you can vary the default value of monospaced without having to type an attribute list–attribute lists aren’t very poetic!

To repeat: regardles of the value of the monospaced attribute, all whitespace is respected in a poetry resource. So, you can indent the last two lines of a sonnet without requiring a monospaced font.

The following example shows how you can get different default behaviour without an attribute list required:

Here's a Shakespearean sonnet:

___
I grant I never saw a goddess go;
My mistress when she walks treads on the ground.
    And yet, by heaven, I think my love as rare
    As any she belied with false compare.
___

Here's a pretend poem which wants a monospaced font:

---
i
  am
      a        cat
            a        l a z y          cat

me   ow
---

Now, if you want to add captions to the poems which are inserted as inline resources, then you’re stuck adding an attribute list after all:

Here's a Shakespearean sonnet:

{caption: "Sonnet 130"}
___
I grant I never saw a goddess go;
My mistress when she walks treads on the ground.
    And yet, by heaven, I think my love as rare
    As any she belied with false compare.
___

Here's a pretend poem which wants a monospaced font:

{caption: "Peter's Pretentious Poem"}
---
i
  am
      a        cat
            a        l a z y          cat

me   ow
---

Math

Math can be a local, web or inline resource, just like any other resource, and the same resource syntax applies to code as to all other resources.

Per the table of resource types and formats, the following types of math resources can be supported by Markua Processors: LaTeX math or MathML.

Note that Markua procesors do not need to support either math markup syntax (LaTeX math or MathML). If a Markua Processor does not support a math markup syntax, it should simply render the text of the math resource as unformatted monospaced text, much like a code resource of format text.

Supported Attributes for Math

The following is the supported attribute for math resources, in addition to the type, format, caption and class attributes which all resources support:

alt
The alt is the alt text, to be displayed when the mathematical equations cannot be shown. The default alt text for math is “math”. This can be provided in the figure attribute list. This is primarily intended for Markua Processors that output math as images; there are no output requirements for the alt text. This attribute functions as it does for images. (In fact, a Markua Processor may choose to transform the math into an image, for maximum ebook reader compatibility.)

Note that for math, the format is the name of the syntax used to write the mathematical equations. There are two special types of format for math baked into Markua: latex for LaTeX math and mathml for MathML math.

Local Math Resources

Local math resources can be inserted as a figure. In all the following examples of figures, the text in the square brackets is the figure caption, like it is in all figures.

Here's a paragraph before the figure.

{alt: "too large to fit in the alt text"}
![Proof of Fermat's Last Theorem](fermat-proof.mathml)

Here's a paragraph after the figure.

Web Math Resources

This is identical to how local math resources work, including the significance of file extensions. The only difference is that the files are on the web.

Here's a paragraph before the figure.

{alt: "too large to fit in the alt text"}
![Proof of Fermat's Last Theorem](http://markua.com/fermat-proof.tex)

Here's a paragraph after the figure.

Note that in the above examples of figures, the text in the square brackets is the figure caption, like it is in all figures.

Inline Math Resources

Inline math resources are the most flexible way to insert math. They are the only way to insert math as a span resource, and the most straightforward way to add short math examples as figures. Both LaTeX math and MathML can be inserted inline as a figure or as a span.

Span

There is syntactic sugar for LaTeX math which is inserted as a span:

Yada yada `some math here`$ yada yada.

The $ character indicates the inline resource is LaTeX math.

Here’s an example of LaTeX math inserted as a span:

One of the kinematic equations is `d = v_i t + \frac{1}{2} a t^2`$ this one.

If you don’t like syntactic sugar, you can also do a lot of typing to insert math as LaTeX math:

Yada yada `some math here`{format: latex} yada yada.

Or, if you really like typing, you can insert MathML as an inline resource inserted as a span:

Yada yada `really verbose MathML here`{format: mathml} yada yada.

As with code resources, note that this is syntactic salt for MathML, since I consider MathML to be too verbose to be productively inserted as a span resource. However, just as with code resources, since any span can have an attribute list attached to it, there is no reason to explicitly forbid specifying a format of mathml in the attribute list.

Finally, if there is no $ character after the closing backtick and no attribute list specifying a format of latex or mathml, the content of the backticks is treated as code and is output verbatim as monospaced text.

Figure

Both LaTeX math and MathML can be inserted inline as a figure.

LaTeX math can be inserted by specifying either latex or $ after three backticks, or by specifying an attribute list of {format: latex}.

MathML math can be inserted by specifying mathml after three backticks, or by specifying an attribute list of {format: mathml}.

LaTeX math:

Here's a paragraph before the figures.

```latex
\left|\sum_{i=1}^n a_ib_i\right|
\le
\left(\sum_{i=1}^n a_i^2\right)^{1/2}
\left(\sum_{i=1}^n b_i^2\right)^{1/2}
```

Here's the same thing, with even more syntactic sugar:

```$
\left|\sum_{i=1}^n a_ib_i\right|
\le
\left(\sum_{i=1}^n a_i^2\right)^{1/2}
\left(\sum_{i=1}^n b_i^2\right)^{1/2}
```

Here's a paragraph after the figures.

This is a slightly-reformatted example of MathML math from Wikipedia:

```mathml
<apply>
  <plus/>
  <apply>
    <times/>
    <ci>a</ci>
    <apply><power/><ci>x</ci><cn>2</cn></apply>
  </apply>
  <apply>
    <times/>
    <ci>b</ci>
    <ci>x</ci>
  </apply>
  <ci>c</ci>
</apply>
```

Here’s the start of the same thing with a verbose attribute list:

{format: mathml}
```
<apply>
  <plus/>
  (identical code omitted)
</apply>
```

Tables

Tables are important elements in many Markua documents. Tables are also resources, albeit with a special syntax when used as an inline resource.

Per the table of resource types and formats, a Markua table in an external file (either as a local or web resource) will be interpreted as such if it has a file extension of .tbl, or if it has a format of table or type of table specified via an attribute list.

Tables are always inserted as figures. Note, however, that a Markua Processor should list tables as tables, not figures, if the book has a Table of Figures and Table of Tables.

The syntax to insert a table defined in an external file on the local filesystem is the same as the syntax to insert a local resource:

{type: table, optional: attribute_list}
![Optional Table Caption](table_path)

The table_path lists the path to the external file which defines the table.

To insert a table defined inline, you just insert it:

{type: table, optional: attribute_list}
|============|============|============|
| Header A   | Header B   | Header C   |
|============|============|============|
| Content A1 | Content B1 | Content C1 |
|------------|------------|------------|
| Content A2 | Content B2 | Content C2 |
|============|============|============|
| Footer A   | Footer B   | Footer C   |
|============|============|============|
The header is separated from the body cells by a section separator, i.e. a row of = signs and | characters. Every row of cells is separated by a row separator, i.e. a row of - signs and | characters. The | characters MUST line up and MUST start and end each line. The header and footer rows are both optional, of course.

The header and footer rows are both optional. The following are also legal tables…

Just content rows:

|============|============|============|
| Content A1 | Content B1 | Content C1 |
|------------|------------|------------|
| Content A2 | Content B2 | Content C2 |
|------------|------------|------------|
| Content A3 | Content B3 | Content C3 |
|============|============|============|

Header, one content row, footer:

|============|============|============|
| Header A   | Header B   | Header C   |
|============|============|============|
| Content A1 | Content B1 | Content C1 |
|============|============|============|
| Footer A   | Footer B   | Footer C   |
|============|============|============|

No footer:

|============|============|============|
| Header A   | Header B   | Header C   |
|============|============|============|
| Content A1 | Content B1 | Content C1 |
|------------|------------|------------|
| Content A2 | Content B2 | Content C2 |
|------------|------------|------------|
| Content A3 | Content B3 | Content C3 |
|============|============|============|

No header:

|============|============|============|
| Content A1 | Content B1 | Content C1 |
|------------|------------|------------|
| Content A2 | Content B2 | Content C2 |
|------------|------------|------------|
| Content A3 | Content B3 | Content C3 |
|============|============|============|
| Footer A   | Footer B   | Footer C   |
|============|============|============|

If there are only two rows separated by a section separator, they are interpreted as a header and a content row:

|============|============|============|
| Header A   | Header B   | Header C   |
|============|============|============|
| Content A1 | Content B1 | Content C1 |
|============|============|============|

If there are only two rows separated by a row separator, they are just two content rows:

|============|============|============|
| Content A1 | Content B1 | Content C1 |
|------------|------------|------------|
| Content A2 | Content B2 | Content C2 |
|============|============|============|

If there is only one row, it is interpreted as a content row, not a header row:

|============|============|============|
| Content A1 | Content B1 | Content C1 |
|============|============|============|

You may initially balk at typing row separators. My recommended approach is to write the table first, and then copy and paste the row separators. If you get the column widths wrong, updating row separators is a headache, and you’ll end up copying and pasting them anyway.

You can also specify left, center and right alignment of columns with colons in the header separator row, just as with simple tables. The following columns are left-, center-, and right-aligned respectively:

|=============|==============|=============|
| Header A    | Header B     | Header C    |
|:============|:============:|============:|
| Content A1  | Content B1   | Content C1  |
|-------------|--------------|-------------|
| Content A2  | Content B2   | Content C2  |
|-------------|--------------|-------------|
| Content A3  | Content B3   | Content C3  |
|=============|==============|=============|
| Footer A    | Footer B     | Footer C    |
|=============|==============|=============|

Since the alignment is done on the separator row above the first content row, it even works to align a column with no header or footer. The following columns are also left-, center-, and right-aligned respectively:

|:===========|:==========:|===========:|
| Content A1 | Content B1 | Content C1 |
|------------|------------|------------|
| Content A2 | Content B2 | Content C2 |
|------------|------------|------------|
| Content A3 | Content B3 | Content C3 |
|============|============|============|
You can have more than one row of content in cells, and there is no ambiguity since each row of cells is separated with a row of - signs and | characters:
|=============|==============|=============|
| Header A    | Header B     | Header C    |
|:============|:============:|============:|
| Content A1  | Content B1   | Content C1  |
| is really   | is longer    |             |
| really      |              |             |
| long        |              |             |
|-------------|--------------|-------------|
| Content A2  | Content B2   | Content C2  |
|-------------|--------------|-------------|
| Content A3  | Content B3   | Content C3  |
|=============|==============|=============|
| Footer A    | Footer B     | Footer C    |
|=============|==============|=============|
You can specify a column span just by skipping a | in the appropriate place:
|=============|==============|=============|
| Header A    | Header B     | Header C    |
|:============|:============:|============:|
| Content A1 and B1 Merged   | Content C1  |
|-------------|--------------|-------------|
| Content A2  | Content B2   | Content C2  |
|-------------|--------------|-------------|
| Content A3  | Content B3   | Content C3  |
|=============|==============|=============|
| Footer A    | Footer B     | Footer C    |
|=============|==============|=============|

You can specify a row span just by skipping a part-row of - signs in the appropriate place:

|=============|==============|=============|
| Header A    | Header B     | Header C    |
|:============|:============:|============:|
| Content A1  | Content B1   | Content C1  |
| and A2      |--------------|-------------|
| Merged      | Content B2   | Content C2  |
|-------------|--------------|-------------|
| Content A3  | Content B3   | Content C3  |
|=============|==============|=============|
| Footer A    | Footer B     | Footer C    |
|=============|==============|=============|

You can also individually align cells with colons in the - part-row above them. This alignment overrides any alignment already on the column, and it works for merged cells too:

|=============|===============|=============|
| Header A    | Header B      | Header C    |
|:============|:=============:|============:|
| Content A1 and B1 Merged    | Content C1  |
|------------:|:--------------|-------------|
| Content A2  | Content B2    | Content C2  |
|:-----------:| and B3 Merged |-------------|
| Content A3  |               | Content C3  |
|=============|===============|=============|
| Footer A    | Footer B      | Footer C    |
|=============|===============|=============|

In that table, column A is left-aligned, column B is center-aligned and column C is right-aligned. However, cell A2 is right-aligned, cell A3 is center-aligned and merged cell B2 and B3 is left-aligned.

Supported Attributes for Tables

The following is the supported attribute for table resources, in addition to the type, format, caption and class attributes which all resources support:

widths
Tables have a widths attribute, which sizes the column widths from left to right as a percentage of the total table width. In this attribute value, * means for the column to use the remaining space, equally divided between it and any other column with the * attribute. Example: {widths: "10,30,*,10"}, {widths: "10,*,40,*}. If the sums exceed 100 (ignoring the *s), the widths attribute values must be ignored.

Just as with images, the class can be used by Markua Processors to provide the appropriate styling. (In fact, a Markua Processor may choose to transform the table into an image, for maximum ebook reader compatibility–but at the expense of accessibility support in newer ebook readers.)

Optional Simpler Table Syntax Support

The actual syntax to define a Markua table, either in an external file or inline, is slightly more complex than other excellent Markdown table syntaxes, such as the table syntax defined by PHP Markdown Extra and extended by GitHub Flavored Markdown.

The reason for this complexity is as follows: since Markua does not support inline HTML, Markua tables need to be able to support all table features required. It’s not possible to just define a syntax for the simple cases and fall back to inline HTML for the complex cases. So, Markua tables need to support cells that span multiple rows and columns, and need to support alignment both of columns and of individual cells.

Markua makes the following compromise: Markdown Processors are free to support alternative Markdown table syntaxes in addition to the Markua table syntax. For example, Leanpub also supports the GitHub Flavored Markdown table syntax in Markua documents.

Whitespace: Spaces, Tabs and Newlines

The goal for the handling of normal whitespace (spaces, tabs and newlines) in Markua is for everything to just work.

Note that these decisions about normal whitespace handling are decisions about prose, not poetry. Poetry has its own rules, and in poetry, all whitespace is preserved unchanged. The way this is accomplished is that poetry, whether in an external file or in the body of a Markua document itself, is handled as a poetry resource.

So, with poetry taken care of, the question of prose remains.

There are the four principles of Markua’s whitespace handling:

  1. No invisible formatting is allowed. If you can’t see it, it has no effect.
  2. Paragraphs and sentences should be handled consistently, regardless of indentation and spaces after periods.
  3. Manual whitespace formatting should be discouraged.
  4. Newlines are newlines; spaces are spaces. These are different things.

These simple goals have far-reaching consequences:

  1. Whitespace at the end of a line or file is ignored.
  2. It doesn’t matter how many spaces you add after a sentence.
  3. All consecutive newlines after the second newline are ignored.
  4. You can’t manually wrap text with newlines being used as though they are spaces, but you can add forced line breaks without hacks.

Whitespace handling is the largest difference between Markua and Markdown, so it’s discussed here, instead of in the appendix.

Newlines

Single Newline = Forced Line Break

In Markdown, you can manually wrap headings, paragraphs, lists and blockquotes with single newlines with no effect on the HTML output. Markdown, like HTML, treats single newlines as equivalent to single spaces.

In Markua, however, a forced line break in the input is a forced line break in all output formats. This is true for paragraphs, lists, blockquotes, asides and blurbs.

In ancient history, some text editors did not automatically wrap lines of text, so manual wrapping of plain text files was a good thing to do. Also, for computer programmers, we still do not wrap our text when programming. However, for writing, automatic wrapping of paragraphs is essential for staying in the flow while writing, and for being able to edit your text without needing to re-wrap every line in a paragraph. This is one decision that even Microsoft Word gets right.

The decision in Markua to treat single newlines as forced line breaks means that Markua does not need to use the horrible hack that Markdown uses to output forced line breaks. In Markdown, to output a forced line break (a <br/> tag in HTML), you need to add two spaces at the end of the line, followed by a single newline. This means that it is impossible to look at a Markdown document with single newlines in it and understand what they mean: you need to find out if there are invisible formatting characters at the end of the line to find out if the newlines mean “newline” or “single space”. Yuck!

Worse, some text editors (like Emacs, the editor I use) can be configured to remove trailing spaces at the ends of lines automatically when a file is saved. So, it’s possible for me to dramatically modify a Markdown document by simply opening it and saving it unedited. Yikes!

The following is an example of Markua’s single newlines:

I'm paragraph one. Yay!

This is paragraph two.
This is *still* in paragraph two, preceded by a forced line break.
This is also in paragraph two, also preceded by a forced line break.

This is paragraph three.

Three or More Newlines = Two Newlines = One Blank Line

Markua handles two consecutive newlines identically to Markdown: they produce a blank line, which separates block elements like paragraphs from each other.

Similarly, Markua handles three or more consecutive newlines identically to Markdown: they produce one blank line, as though only two newlines had been typed.

When writing prose, there’s basically no reason to add multiple blank lines. Worse, the most popular reason is a bad one: to hopefully accomplish a page break, or to make something look like a section break. However, Markua has special syntax for scene breaks and page breaks, which should be used for these purposes.

If you absolutely must insert a bunch of newlines in a row, you can do this by starting a poetry block and doing so:

...the end of a paragraph.

___



___

That empty poetry block is 3 lines long, so it adds three poetic blank lines to the output.

One Blank Line Is Added When Concatenating Manuscript Files

A Markua document can be written in one file or multiple manuscript files. If a manuscript is written in multiple files, these files are concatenated together by the Markua Processor to produce one temporary manuscript file, and that one file is used as the input.

Importantly, in order to avoid a number of bugs, the files are not just concatenated together unchanged–they must be concatenated together by Markua Processors with two newlines (i.e. one blank line) added between the end of each file and the beginning of the next file.

This is needed in order to separate the content of the two files with one blank line between them, in order to prevent a number of surprises for authors. Note that because of this rule, a paragraph (or any other block element) cannot span multiple manuscript files.

To see why this is essential, see the appendix.

All Blank Lines at the Beginning and End of a File are Removed

Since a blank line is added when concatenating multiple manuscript files, there is no good reason to support blank lines, or lines containing only whitespace, at the beginning or end of a file. So, all blank lines and all whitespace-only lines at the beginning or end of a file are removed.

This is especially important with the whitespace at the end of a file: trailing whitespace at the end of a file is invisible to the author, and supporting invisible formatting–whether at the end of a line or the end of a file–is insanity.

Spaces and Tabs

Spaces and Tabs at the Beginning of a Line are Removed

Markua handles spaces and tabs at the beginning of a line similarly to Markdown: it is only used to determine whether the content is in the paragraph or some nested block element (e.g. a nested list).

So, you can’t manually indent any lines in a paragraph in Markua, even after a forced line break.

If you want to write a poem in Markua, start a poetry resource with ___ or ---. This will have the added benefit of allowing your poetry to be formatted using special font sizes and margins, to be more poetic than prose.

Spaces and Tabs at the End of a Line are Removed

Unlike Markdown, all trailing spaces at the end of a line are ignored by Markua. This way, there is no reliance on invisible formatting to produce newlines, and editors which strip trailing spaces have no effect on a Markua document.

Internal Spaces are Collapsed to One Space, Except At the End of Sentences

Markua handles internal whitespace in a paragpraph in a similar way to Markdown:

First, in Markua and Markdown, multiple internal spaces or tabs in the the middle of a sentence are all collapsed to one space.

However, a Markua Processor should be smart about interpreting what is the end of a sentence, and handle that specially.

At the end of sentences that aren’t followed by newlines, a Markua Processor may output one space, one and a half spaces, two spaces or some other amount of space. (Yes, one and a half spaces at the end of a sentence is a real thing, and it is arguably the one true amount of space at the end of a sentence.)

The amount of space chosen to be output at the end of sentences must be output by the Markua Processor at the end of all sentences which aren’t followed by newlines, regardless of whether any given sentence has one or two spaces at its end.

But what’s the end of a sentence?

This would be a lot easier to determine if all authors typed two spaces at the end of their sentences! This way, a Markua Processor could easily determine that something like “Mr. Armstrong” did not, in fact, contain the end of a sentence.

However, many authors type one space at the end of their sentences. So, a Markua Processor should use heuristics to determine what is the end of a sentence and what is not.

Regardless of how it made the determination about whether a sentence has ended, if a Markua Processor decides that something is, in fact, the end of a sentence, it must output the same amount of space every time. This can be one space, one and a half spaces, two spaces or some other amount.

Lists

Markua supports bulleted lists, numbered lists and definition lists.

Markua distinguishes between “bulleted” and “numbered” lists, not between “unordered” and “ordered” lists (as is done by HTML and Markdown), since all lists have an order–otherwise they wouldn’t be lists!

Bulleted Lists

Markua lets you make a bulleted list by starting each list item with either an asterisk (*) or a hyphen (-), followed by 1-4 spaces or 1 tab, followed by text content. You can’t mix and match asterisks and hyphens in the same list. Here’s how this looks:

You can build a list out of items starting with an asterisk and one space:

* foo
* bar
* baz

You can build a list out of items starting with a hyphen and one tab:

-    one
-    two
-    three

Markua could have chosen only the asterisk (*) or the hyphen (-) and only one amount of spaces or tabs after it, but this would be too prescriptive. Markua is as opinionated as possible, but that would have been overkill.

These are the specific rules for bulleted lists:

  • Start each list item a bullet which is either an asterisk (*) or a hyphen (-).
  • You can’t mix and match asterisks and hyphens in the same list.
  • Between 1 and 4 spaces or one tab is allowed after each bullet.
  • You cannot mix tabs and spaces: if a tab is used after a bullet, tabs must be used after each bullet.
  • If spaces are used after each bullet, the same number of spaces must be used after each bullet in the list.
  • A varied number of spaces or tabs or a mixture of tabs and spaces does not create a bulleted list. Instead, it creates a paragraph with line breaks inside it.
  • A single element bulleted list is a list: although it is a pretty stupid list, treating it as a literal paragraph starting with an asterisk or hyphen would be even stupider.

In terms of style guidance, the preferred bullet type in Markua is the asterisk, and the preferred whitespace after the bullet is one space.

Numbered Lists

In Markua, a numbered list can vary the following:

  1. Numbering system
  2. Numbering direction (ascending or descending)
  3. Initial number (or letter, or Roman numeral)
  4. Period or parentheses after the number (or letter, or Roman numeral)

The following choices of numbering system are supported:

  1. Decimal numbers
  2. Uppercase letters
  3. Lowercase letters
  4. Uppercase Roman numerals
  5. Lowercase Roman numerals

Unlike in Markdown, in Markua the number that begins the list in the manuscript is the number that begins the list in the output.

To make a numbered list in Markua, you start one or more consecutive lines with either a consecutive number or the same number (or letter or roman numeral), followed by between 1 and 4 spaces or 1 tab, followed by text content, followed by a period or a right-parenthesis.

Since Markua supports letters and Roman numerals as well as decimal numbers to start lists, the rules about using consecutive numbers or the same number are actually a bit complex.

Note that there are one or more spaces after the period. Unlike with a bulleted list, the number of spaces does not need to be the same after each item (since numbers may have 2 or more digits, so a variable number of spaces may be desired to line everything up).

This set of examples shows many of the normal use cases of lists with the various numbering systems. For the edge cases, see the next sections.

Ascending decimal numbers starting from 1:

1. foo
2. bar
3. baz

Ascending decimal numbers starting from 1, with parentheses used instead of periods:

1) foo
2) bar
3) baz

Ascending decimal numbers starting from a higher number:

9.  foo
10. bar
11. baz

Descending decimal numbers:

3. foo
2. bar
1. baz

Identical decimal numbers for the lazy (producing 1, 2, 3):

1. foo
1. bar
1. baz

Ascending lowercase letters:

a. foo
b. bar
c. baz

Ascending lowercase letters, with parentheses used instead of periods:

a) foo
b) bar
c) baz

Ascending uppercase letters:

I. foo
J. bar
K. baz

Ascending uppercase Roman numerals:

I.   foo
II.  bar
III. baz

The full set of numbering rules for numbered lists are specified in an appendix. However, it’s important to emphasize what happens with single-element numbered lists.

In Markua, A Single-Element Numbered List is Not a List

Markdown has the interesting combination of supporting one element lists and ignoring the number that a list starts with. This means it’s possible to inadvertently start a numbered list by beginning any line with a number followed by a period. The example that John Gruber cites is the following:

1986. What a great season.

This would produce a single-element numbered list starting with 1.–which in my opinion, is a blatant violation of the Principle of Least Surprise.

Now, in Markua, if we supported single-element numbered lists, this would produce a single-element numbered list starting with 1986.–which would be almost as bad as in Markdown.

(By the way, there is a very gross workaround in Markdown: you prefix the period with a backslash. So, you’d write 1986\. What a great season. to avoid this.)

But what to do?

The answer is simple: in Markua, single-element numbered lists are not lists. This is true for numbered lists only–single-element bulleted lists and single-element definition lists are both lists. (In the case of a bulleted list it’s stupid, but the alternative is stupider. In the case of a definition list there’s actually a legitimate usage of a single-element definition list: a single definition.)

So, in Markua, the automatic creation of a numbered list only happens if you have two or more lines starting with numbers and periods or parentheses.

This still has some possibly incorrect interpretations, but these will be a lot more rare. This matters: if you get burned by the automatic list creation, and you feel that you have to think about whether you can start a sentence with a number, then writing in Markua will feel more like programming than writing.

Multi-Paragraph List Items

If lists were simple, they would contain be a bunch of simple one-line list items like:

* This is simple.
* So is this.
* This too!

However, in Markdown, list items can contain multiple paragraphs, and it makes sense for Markua to support this. If a list is going to contain list items with multiple paragraphs, then there should be blank lines between each list item.

As with Markdown, every paragraph in a list item after the first one must be indented by four spaces or one tab. This lets the Markua Processor know that the list is not over, but is instead being continued.

The following is legal Markdown and legal Markua:

Here's a paragraph before the list.

1.  This is the first paragraph in the first list item. Yay!

    This is a second paragraph in the first list item.

2.  The second list item is simple.

3.  The third list item has three paragraphs.
    This is still part of the first paragraph.

    Here's the second paragraph in the third list item.

    Here's the third paragraph in the third list item.

Here's a paragraph after the list.

Just as with normal non-list-item text, a single newline functions as a forced line break within the list item in question. However, to encourage the text to be lined up nicely in the list item, any leading whitespace after the line break is ignored. This is different from the whitespace being preserved after single newlines in paragraphs. That rule exists to support poetry, and if there’s one thing that lists are not, it’s poetry.

Nested Lists

Lists can nest lists. To do this, simply insert the list nested inside a list item by 2 spaces for each level of nesting.

There is a limit of THREE levels of nesting, including the outermost list. In an ebook, you don’t have infinite space–especially on phones. You can nest any kind of list inside any kind of list.

This example shows the maximum three levels of nesting:

* Foo
  1. One
  2. Two
    a. This is 2a
    b. This is 2b
  3. Three
* Bar
  i.   Lorem
  ii.  Ipsum
  iii. Dolor
* Baz

If you try to nest a fourth level of nesting (or more), the Markua Processor will simply interpret the additional levels as forced newlines and manual indentation.

Nesting Block Elements in List Items

Nested lists are just an example of nesting block elements inside list items.

Other block elements such as figures can also be inserted nested inside list items. This is true for both single paragraph list items (with no blank lines between them) and multiple-paragraph list items (with a single blank line between each list item).

Single-Paragraph List Items

* Foo
  ```ruby
  puts "hello"
  ```
* Bar
  {alt: "too large to fit in the alt text"}
  ![Proof of Fermat's Last Theorem](fermat-proof.mathml)
* Baz

In the single paragraph list items case, indenting the block element is optional but recommended.

Multiple-Paragraph List Items

* This is paragraph 1 in the first list item.

  ```ruby
  puts "hello"
  ```

  This is paragraph 2 in the first list item.

* This is paragraph 1 in the second list item.

  {alt: "too large to fit in the alt text"}
  ![Proof of Fermat's Last Theorem](fermat-proof.mathml)

  This is paragraph 2 in the second list item.

* Baz

In the case of multiple paragraph list items, you need to indent the block element by the same four spaces (or one tab) that you use to indent subsequent paragraphs in the list item. Doing this ensures the continuation of the list.

Definition Lists

Definition lists are supported in Markua. With the rise of mobile and the narrower screen reading experience becoming the new default, definition lists may end up being more important than tables.

To define a definition list in Markua, use the following syntax:

term 1
: definition 1

term 2
: definition 2

There can be one to three spaces after the colon, or one tab.

A definition list can provide multiple definitions for a term:

term 1
: definition 1a
: definition 1b

term 2
: definition 2

A single term definition list is a definition list, regardless of how many definitions for the term exist:

term
: definition

Finally, like list items, each definition list item can contain newlines and multiple paragraphs. What you do here is indent the subsequent lines by the same amount of space as the initial line. (If you do not indent the subsequent lines, then you’re ending the definition list and just starting a new paragraph.) As with list items, one newline is a forced line break; two newlines is a new paragraph:

Here's a paragraph before the list.

one
: This is the first definition of one. It's one paragraph.
: This is the second definition of one. It's two paragraphs.

  This is a second paragraph in the second definition of one.

two
: The second list item is simple.

three
: The third list item has three paragraphs.
  This is still part of the first paragraph.

  Here's the second paragraph in the third list item.

  Here's the third paragraph in the third list item.

Here's a paragraph after the list.

Just as with list items, any leading whitespace after the line break is used to continue the definition list item, and is thus ignored. Like list items, definition list items are not poetry.

Block Elements

Broadly speaking, Markua documents consist of three things: block elements, span elements and metadata. Paragraphs, headings, figures and lists, all discussed earlier in this specification, 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.

Markua Processors can take great liberties in how they output scene breaks. They can output a set number of asterisks, or an image, or whatever else they choose. Note that typically a scene break is not followed by a page break. However, to add this, you can simply add a manual page break after it.

Page Breaks (===)

Three or more equals signs on a line by themselves, with or without spaces between them (e.g. ===, = = =, ==========, etc.), produce a page break.

Page breaks are discouraged in Markua: when you’re writing, unsemantic formatting is procrastination, and most page breaks are exactly this. Much like width and height attributes on images, however, page breaks are supported in Markua due to pragmatic concerns.

Here is an example showing a page break following a paragraph, and a page break following a scene break:

This is before the page break.

===

This is on a new page, after the forced page break. It has a scene break and then a page break after it.

* * *
===

This is on a new page, after the scene break and the forced page 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 a Markua Processor differently than normal headings. Finally, if a Markua Processor is automatically generating a Table of Contents from chapter and section headings, any headings inside blockquotes should be ignored.

A blockquote can have a citation. This is done via the attribute list, which can include a cite attribute with the text of the citation and a url attribute with the URL of the citation. If both are specified, the text of the citation is linked to the URL. If only the cite attribute is specified it is shown as text; if only the url is specified it is inserted as text with a link to itself.

The attribute list can be used regardless of which syntax is used to insert the blockquote:

Lots of people have opinions about software.

Here's the most famous recent one:

{cite: "Marc Andreessen", url: "http://www.wsj.com/articles/SB10001424053111903480904576512250915629460"}
> Software is eating the world.

It's quoted a lot, so let's quote it again:

{blockquote, cite: "Marc Andreessen", url: "http://www.wsj.com/articles/SB100014240531119034809045765122509156\
29460"}
Software is eating the world.
{/blockquote}

That's it!

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), and they can also be formatted differently by Markua Processors.

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:

  • discussion
  • error
  • information
  • tip
  • warning

These blurb types can be set on a blurb as its class attribute. A Markua Processor 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 Blurb Classes: D>, E>, I>, T, W>

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:

Sugar Equivalent To a B> With
D> {class: discussion}
E> {class: error}
I> {class: information}
T> {class: tip}
W> {class: warning}

Examples:

D> This is a discussion blurb.

E> This is an error blurb.

I> This is an information blurb.

T> This is a tip blurb.

W> This is a warning 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: tip}
B> This is a tip blurb.

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

Note that nothing in this section defines what a Markua Processor 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, but other Markua Processors are free to do something different.

Using Extension Attributes on Blurbs to add icon Support

Markua Processors must ignore any attributes which they do not understand.

Because of this, Markua attribute lists can contain any number of extension attributes. An extension attribute is an attribute which is not defined in the Markua specification, but which is understood by some specific Markua Processor.

As an example of an extension attribute, 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. In a Markua implementation that does not understand the icon attribute, nothing will be generated for that attribute–it will be functionally equivalent to the attribute not being present.

Inserting Block Elements Inside Paragraphs

Many block elements such as lists and figures can also be inserted nested in a paragraph. The way this is done is to add single newlines instead of blank lines.

This example shows a list nested in the middle of a paragraph:

This is paragraph one.

This sentence is in paragraph two.
* this list is
* part of
* paragraph two
This sentence is also in paragraph two.

This is paragraph three.

This example shows a figure which is an inline code resource nested in the middle of a paragraph:

This is paragraph one.

This sentence is in paragraph two.
```ruby
puts "hello world"
```
This sentence is also in paragraph two.

This is paragraph three.

This example shows a figure which is a local code resource nested in the middle of a paragraph:

This is paragraph one.

This sentence is in paragraph two.
{format: ruby}
![Hello, World](hello.rb)
This sentence is also in paragraph two.

This is paragraph three.

This example shows figures which are local or web image resources nested in the middle of paragraphs. Note that as with all figures, the square bracket text in both cases is the figure caption (not alt text):

This is paragraph one.

This sentence is in paragraph two.
![A Piece of Cake](cake.jpg)
This sentence is also in paragraph two.

This sentence is in paragraph three.
{alt: "a slice of chocolate cake"}
![A Piece of Cake](http://markua.com/cake.jpg)
This sentence is also in paragraph three.

This is paragraph four.

It is possible to insert a block element as the last part of a paragraph by adding a single newline before it, but a blank line after it:

This is paragraph one.

This sentence is in paragraph two.
* this list is
* part of
* paragraph two

This is paragraph three.

This works for most block elements, like lists, figures and tables. It does NOT work for definition lists, since those rely on blank lines in between elements.

Quizzes and Exercises

The final two block elements that Markua provides are quizzes and exercises. These two block elements are very special, however, in that they enable a single Markua document to construct everything from traditional textbooks and paper-based quizzes to entire online courses (or MOOCs). So, they’re discussed in their own chapter.

Quizzes and exercises are essentially the same. The only difference is that quizzes are intended to be marked, and exercises are not. Because of their similarities, they are discussed here together.

Quizzes or exercises in a textbook consist of two things:

  1. Questions, typically in the chapter itself.
  2. Answers, typically at the back of the book.

The questions in the chapter essentially are placed there like any other block element, such as an aside or blurb. The answers are positioned at the back of the book, along with other elements like the index and appendices. The specific location that they are positioned can be controlled by the author using book section directives, discussed later.

Just like asides and blurbs, there are two syntaxes to add quizzes an exercises.

Quizzes:

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

Exercises:

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

While the {quiz}...{/quiz} or {exercise}...{/exercise} syntax is by far the preferred syntax for longer quizzes or exercises, both syntaxes work. The Q> or X> syntax is supported for consistency with asides and blurbs, and because it is possibly preferable for short, blurb-length quizzes or exercises containing a few questions at most.

Here is a brief example of a quiz, using the curly brace syntax:

{quiz, id: quiz1}
? How many letters are in the word Markua?

a) 5
B) 6
c) 7

? How many unique letters are in the word Markua?

! 5
{/quiz}

This quiz contains two questions: a multiple-choice question where the correct answer is b, and a fill-in-the-blank question where the correct answer is 5. Quizzes and exercises have the same question types, discussed later.

Here’s the same example, but as an exercise, using the X> syntax:

{id: exercise1}
X> ? How many letters are in the word Markua?
X>
X> a) 5
X> B) 6
X> c) 7
X>
X> ? How many unique letters are in the word Markua?
X>
X> ! 5

Note that, as with asides and blurbs, if an attribute list is present it is immediately above the first Q> or X> line.

You can see why the Q> or X> syntax is only intended for very short quizzes or exercises, just as the A> and B> syntaxes are only intended for short asides and blurbs!

Quiz and Exercise Headings and Other Content

A quiz or exercise can contain any Markua content, not just questions and answers. This is true regardless of whether the quiz or exercise is in a MOOC, an ebook or on paper. Note that video and audio resources don’t work so well on paper, however.

If a quiz or exercise starts with a chapter heading (starting with a # ) immediately after the {quiz} or {exercise} line or as the first line of the Q> or X> block, this heading’s content should be considered the name of the quiz or exercise. This can be used in a list of quizzes or exercises produced by the Markua Processor.

Example:

{quiz, id: quiz2}
# Markua Quiz

Watch this [video](https://www.youtube.com/watch?time_continue=1&v=VOCYL-FNbr0) of Peter explaining Markua.

? What year was that video from?

What year? Really? Did it really take that long? What was going on???

a) 2012
b) 2013
C) 2014
d) 2015

{words: 500}
? Why do you think the first version of the Markua spec took so long?

Look at the Leanpub website and read the [pricing essay](https://leanpub.com/pricing).

! Answers could include "bootstrapped startup", the spec evolving, removing HTML mapping, etc.

That's it for this quiz, and this MOOC!

**Thanks for taking my course!**
{/quiz}

A Malformed Quiz or Exercise is an Error

If a Markua Processor encounters a malformed quiz or exercise it must treat this as an error and not generate the output from the Markua document. Quizzes and exercises are not something that should ever be produced in a broken state.

However, it is also an error to parse quiz syntax outside a quiz or exercise block. A Markua Processor must not parse lines starting with ? or ! as representing questions or answers unless those are contained in a quiz or exercise block.

Supported Attributes on Quizzes and Exercises

case-sensitive
true or false. The default is true. This sets the default behaviour of fill in the blank questions. If true, the fill in the blank question answers are case-sensitive. If false, they are not.
points
If present, this is the total number of points the quiz or exercise is worth. (This really only matters for quizzes, but is supported for exercises as well, in case a Markua Processor wishes to display the points on exercises to make them feel more real.) If points is not present, the worth of the quiz is determined by summing the points of the questions. (Questions are worth 1 point each if they have no points attribute.) If the quiz has a points attribute and its questions also have points attributes, the worth of each question in a larger course context is determined as follows: its points are the numerator, and the total points in the quiz or exercise is the denominator.
random-choice-order
true or false. The default is false. This sets the default behaviour of multiple choice questions. If true, the choices in the multiple choice question are randomly arranged; if false, they are presented in the order written.
random-question-order
true or false. The default is false. This sets the default behaviour of the quiz or exercise. If true, the questions are randomly arranged; if false, they are presented in the order written.
start-at
The start_at is the number of the first question. The default is 1. Any integer is permitted. Subsequent questions will have a number which is 1 higher than the previous question.

As discussed above, there is no title or caption attribute for a quiz–you can just add a heading inside the quiz or exercise itself, using the normal Markua formatting for a chapter heading.

Question Types: Multiple Choice, Fill In The Blank, Written

There are three types of questions supported by Markua.

  1. Multiple Choice
  2. Fill In The Blank
  3. Written

These types are not specified by a {type} attribute. Instead, they are inferred from properties of the answers or from other attributes of the question.

Multiple Choice Questions

A multiple choice question has 2 or more answer choices, and 1 or more correct answer choices. Correct answer choices have capital letters before the parentheses; incorrect answer choices have lowercase letters before the parentheses.

Examples:

? How many letters are in the word Markua?

a) 5
B) 6
c) 7

? How many letters (either the total number, or the number of unique letters) are in the word Markua?

A) 5
B) 6
c) 7

Obviously, when generating the question in the actual quiz or exercise, a Markua Processor must make all answer choices have the same type of letter. This is usually a lowercase letter, although either all lowercase or all uppercase letters would be fine.

The multiple choice answers all must start from a or A, and must use a right-parenthesis after the a or A. Any line starting with a) ar A) in a quiz is considered a set of multiple choice quiz answers, not a numbered list using a) or A) as a delimiter. If you want to put a numbered list in a quiz body, use periods for the delimiter.

Supported Attributes on Multiple Choice Questions

points
The number of points the question is worth.
random-choice-order
true or false. The default is false. This sets the behaviour of the specific multiple choice question. If true, the choices in the multiple choice question are randomly arranged; if false, they are presented in the order written. If this attribute is omitted, its value is determined by the random-choice-order attribute on the quiz itself, which defaults to false if absent.

Fill In The Blank Questions

A fill in the blank question consists of a question and an answer. The answer is specified by ! and then the acceptable values of that answer. For a fill in the blank question with more than one acceptable answer value, each legal answer value is separated by a space, followed by a semicolon, followed by a space ( ; ). (To put an actual space, followed by a semicolon, followed by a space in a single fill in the blank answer value, the semicolon must be backslash-escaped ( \; ).)

Examples:

? How many unique letters are in the word Markua?

! 5

? What's the global capital of investment banking?

! New York ; London

{case-sensitive: false}
? What's pi?

! "The ratio of a circle's circumference to its diameter" ; 3.14 ... 3.1416

If there are multiple answers to a fill in the blank question and an answer key is being output by the Markua Processor for use by human markers, the acceptable values should be clearly distinguished from each other. The recommendation is to use a bulleted list of acceptable values, one per line, but there are no requirements here.

As shown by the last answer, acceptable answer values in a fill in the blank question can be of completely different types, and numeric answer values can be expressed as ranges (min <= x <= max), expressed as min ... max.

If you’re a programmer, you may wonder what number types and formats are supported. Are they integers? Floating point numbers? Can you use scientific notation? And how are the numbers formatted? Are they US or Canadian numbers (123,456.78) or EU numbers (123 456,78)? What if there’s a number that means something different in the US and EU–does 123,456 mean 123456 or 123.456?

These questions are made worse by the fact that Markua can be used to create human-marked paper quizzes as well as automatically-marked MOOCs. So, specifying rules which made the syntax unambiguous for MOOCs would mean that the answers for human-marked paper quizzes could not be specified with a tolerable amount of ambiguity.

So, the format of the answer values in a fill in the blank question is out of scope of the Markua Specification. The spec is simply that the answer values are separated by a space, a semicolon, and a space:

! first legal answer value ; second legal answer value ; third legal answer value ; etc.

Supported Attributes on Fill In The Blank Questions

points
The number of points the question is worth. This number can be 0 or higher.
case-sensitive
true or false. The default is true. This sets the behaviour of the specific fill in the blank question. If true, the fill in the blank question answer is case-sensitive. If false, it is not. In the case of multiple acceptable answer values, this attribute applies to all of them.

Written Questions

A written question corresponds to short answer, long answer or essay questions in traditional tests. It looks the same as a fill in the blank question, except the answer is optional.

A question is interpreted as being a written question, as opposed to a fill in the blank question, if either the words, lines or pages attribute is specified, or if there is no answer provided.

Note that an answer may be provided in a written question. If this is done, the answer is not matched like a fill in the blank answer. Instead, the answer is essentially a “note to markers”, whether those markers are underpaid graduate students or unpaid AIs. Markua does not specify any microformat for this note to markers.

A Markua Processor generating a MOOC may handle written questions at its own discretion, including not including them or giving them a points value of 0.

Examples:

{pages: 2, points: 10}
? Why is 2017 like *1984*?

! If the student mentions Newspeak, give them an extra mark.

{words: 100, points: 2}
? Why is doubleplusungood the worst?

Since a written question can have long answers, this increases the likelihood that typing these anwers after a bunch of ! delimiters will be a pain. So, written quesions (and only written questions) support answers in the form of {answer} ... {/answer}, like this:

{quiz, points: 0}

{lines: 10}
? Write a function in Ruby that takes an argument and returns three times that argument.

{answer}
The most straightforward way to do this is like this, since the last value evaluated in the function is return\
ed:

```ruby
def triple(y)
  y*3
end
```

However, you can also explicitly say `return` if you like:

```ruby
def triple(y)
  return y*3
end
```
{/answer}

? Show how to evaluate 2 + 2 in irb.

! `2 + 2`
{/quiz}

Supported Attributes on Written Questions

Note that only one of words, lines or pages may be provided. Providing more than one is an error.

points
The number of points the question is worth.
words
The maximum number of words the answer can be. Obviously this is more useful for online quizzes than paper ones.
lines
The maximum number of lines the answer can be. Obviously this is more useful for paper quizzes than online ones. On paper, this is most useful for a short or long answer question.
pages
The maximum number of pages the answer can be. Obviously this is more useful for paper quizzes than online ones. On paper, this is most useful for an essay question.

Markua Processor Behaviour

A Markua Processor has many degrees of freedom in terms of whether, and how, to output quizzes and exercises.

For example, when outputting an online course or MOOC, the Markua Processor can basically do whatever it wants. It can choose to ouptut an ebook of the course material only, and put all quizzes and exercises only in the online version. Or it can choose to put all the quizzes only in the online version, and include the exercises in the ebook version as well. Or it can include the quizzes and exercises in the ebook version, but only include the answers for the exercises in the ebook version.

If, on the other hand, a Markua Processor is outputting a textbook, it may choose to output the quizzes in an entirely separate ebook or print-ready PDF, for use in physical classrooms.

If a Markua Processor does output a quiz or exercise, it needs to do so in a medium-appropriate way. This includes outputting multiple-choice questions without showing their answers, of course. The display of fill in the blank and essay questions varies greatly based on whether the question is in an online quiz or exercise, in an ebook or on paper.

Markua Processors are encouraged to be creative here.

However, there are some rules. If a given quiz or exercise is output by a Markua Processor in an ebook or a physical book, the following things must occur:

  1. The quiz or exercise must be output as questions-only, in the place in the document where the quiz was defined.
  2. The questions must be numbered sequentially, incrementing by 1 for each question.
  3. The questions must be numbered starting from the number specified by the start-at attribute if specified, or 1 if no start-at attribute is specified.
  4. The multiple choice options in any question must be converted into a set of choices which all look the same, so that the correct answer is not indicated. Converting all choice letters to lowercase is sufficient here.
  5. The answers, if provided, must be positioned somewhere separate from the questions, typically at the back of the book. This position can be controlled by the author using book section directives, discussed later.

Creating a Course or MOOC from a Markua Document

Over the past decade, there has been a steady growth of interest in courses delivered over the internet at massive scale. These Massive Open Online Courses, or MOOCs, consist of essentially four things:

  1. Reading material
  2. Video or audio lectures
  3. Exercises, with answers provided to the student
  4. Quizzes, with answers used to automatically mark the quiz

It turns out the four things in this list all work perfectly in a Markua document. So, not only can Markua be used to easily create a textbook which includes video, audio, images and quizzes, it is also an amazingly simple and flexible way of creating a MOOC. A MOOC is essentially just a textbook which is executable, plus discussion forums and credentials. For example, Leanpub authors can click one button1 to create a massive open online course (MOOC), complete with automated marking for all the quizzes in the course, entirely from one Markua source document.

The fact that a Markua document can be used to create an online course or MOOC means that certain aspects of the syntax for quizzes and exercises are more robust than they would otherwise. One example of this is question alternates.

Question Alternates

In an online course or MOOC, some professors might not want every question the same, despite the fact that question order and answer order can be randomized. So, Markua supports question alternates, using a simple (if slightly ugly) syntax. Question alternates are only supported in quizzes, since they make no sense to include in exercises.

To create question alternates, every question in the quiz (not just those with alternates) must be numbered sequentially, starting from 1, using a ?# syntax. This is a question mark followed by the number of the question, e.g. ?1, ?2, ?3. The questions in a quiz are numbered using sequential positive integers starting from 1: 1, 2, 3, etc.

The alternates are specifyied by providing the same number for multiple questions, e.g. ?1, ?1, ?1, ?2, ?3, ?4, ?4, ?5. When the actual quiz is given, only one of the questions for the given question number is used.

Note that only the first question with a given number may have a points attribute–since all other alternates must use the same points value, specifying it would be pointless.

The following is an example of a quiz which uses question alternates. This ensures that to ensure that students get randomly selected versions of questions 1 and 4. Also, since random-question-order: true is used, the actual position of the questions is randomized after the specific questions are selected from the alternates.

{quiz, id: "midterm", random-question-order: true}
?1 What's 2 + 2?

! 4

?1 What's 2.2 + 2.2?

! 4.4

?2 what's 3 + 3?

! 6

?3 What's 4 + 4?

! 8

{points: 2}
?4 What's 5 + 5?

! 10

?4 What's 6 + 6?

! 12

?5 What's 7 + 7?

! 14
{/quiz}

Note that the syntax for question alternates is very strict. Every question must have a number, and these numbers must be in ascending order (except for the alternates, which have the same number as each other). A Markua Processor must treat any deviation from this rule as an error, and not generate the quiz if there is any error. This is preferable to a Markua Processor of trying to guess at what the author meant, and trying to do the right thing. Fixing a syntax error takes a couple minutes of editing and a few minutes to publish the book or course again. However, fixing the consequences of a quiz being administered to hundreds–or thousands, or tens of thousands–of people with an incorrect number of questions, or with questions incorrectly used as alternates for each other, would be much more difficult.

Span Elements

We’ve already seen many examples of span elements in this specification, especially in the resources section showing resources inserted as spans. These are the rest of them…

Markua’s hyperlink support is a subset of that of Markdown. The inline link syntax is supported, as is the automatic link shortcut.

The normal way to create a link is as follows:

[link text](absolute_url)

Example:

Markua was developed at [Leanpub](http://leanpub.com).

To create a link where the text displayed for the link text is the URL itself, the automatic link syntax can be used. In this syntax, an absolute URL is enclosed in angle brackets.

Some text <absolute_url> some text.

Example:

Markua was developed at <http://leanpub.com>.

Explicitly Creating Spans with []

Surrounding text in square brackets can be useful not just for giving it a URL to link to. If you wish to add attributes to an arbitrary span of text, you can create an arbitrary span of text using square brackets and then add an attribute list immediately afterward:

Some text [then a span]{and: an, attribute: list} attached to the span.

You can use any attribute list on this span, and you can also just use the id syntactic sugar {#theid} on this span. The most common uses of this are to add ids or index entries, which are discussed later.

Sometimes a Square Bracket is Just a Square Bracket

If there are no round brackets or curly braces immediately after some text in square brackets, the text in square brackets is just that: text in square brackets. In this case, the square brackets are output as normal text.

This is useful when you want to [sic.] something, etc.

Footnotes and Endnotes

Footnotes

Books often have footnotes.

To add a footnote, you insert a footnote tag using square brackets, a caret and the tag, like this:

This has a footnote[^thenote].

Then, you define the footnote later in the document, using the same square brackets, caret and tag, followed by a colon, a space and the footnote definition:

[^thenote]: This is the footnote content.

If you wish to write multiple paragraphs in the footnote, you must indent the subsequent paragraphs by four spaces or one tab:

This has a footnote[^thenote].

Here is some unrelated text.

[^thenote]: This is the first paragraph of footnote content.

    This is the second paragraph of footnote content.

Here is some more unrelated text.

Whether the numbering of footnotes restarts every chapter is something that can be specified by the restart-footnote-numbering setting.

Endnotes

Books often have endnotes. Sometimes these are instead of footnotes, but other times, these are in addition to footnotes. So, it makes sense for Markua to define separate syntaxes for both, rather than just defining one “footnote or endnote” syntax and letting the author pick whether the notes are footnotes or endnotes via a global setting.

To add an endnote, you insert an endnote tag using square brackets, two carets and the tag, like this:

This has an endnote[^^thenote].

Endnotes are like footnotes, but happier (^^).

Then, you define the endnote later in the document, using the same square brackets, two carets and tag, followed by a colon, a space and the endnote definition:

[^^thenote]: This is the endnote content.

Just as with footnotes, if you wish to write multiple paragraphs in an endnote, you must indent the subsequent paragraphs by four spaces or one tab.

Whether the numbering of endnotes restarts every chapter is something that can be specified by the restart-endnote-numbering setting.

Single Reference to Footnotes and Endnotes

You can only refer to a footnote or endnote once. You can’t define a footnote or endnote in one place and refer to it multiple times in the same Markua manuscript. If you wish to refer to a parenthetical piece of text from multiple places in a Markua manuscript, the best approach is to put it in a section (or sub-section, sub-sub-section, etc.) or aside and refer to it from multiple places using a crosslink.

Footnotes and Endnotes Support Required for Paragraphs Only

A Markua Processor must support footnote and endnote references inserted in normal paragraph content. However, that’s it.

However, sometimes authors want to get creative with their footnotes and endnotes. Sometimes they want to add them in headings, or in footnotes or endnotes themselves. This latter style has been used on rare occasions, most notably by David Foster Wallace.

However, supporting inserting footnotes and endnotes in places other than normal paragraph content puts a hugely increased burden on implementors of Markua Processors. As such, there is no requirement for a Markua Processor to support inserting a footnote or endnote anywhere other than in normal paragraph content.

Authors should not assume that a particular Markua Processor supports inserting a footnote or endnote anywhere other than in normal paragraph content unless its documentation specifically states that it does. For example, Leanpub only supports inserting footnotes or endnotes in normal paragraph content.

There are two parts to making a crosslink.

  1. Define an id.
  2. Reference that id with a crosslink.

Defining an id

There are two ways to define an id:

  1. Using an id attribute {id: some-id} in an attribute list which can contain other attributes.
  2. Using a shorter “syntactic sugar” approach when the id is by itself: {#some-id}

The shorter approach is preferred. The main reason the {id: some-id} syntax is supported is that it allows it to be added in with other attributes in a larger attribute list. You CANNOT add the {#some-id} to an attribute list.

In terms of the value of an id, it has some special restrictions:

  1. The first character in the id has to be a lowercase or uppercase letter, i.e. [a-zA-Z] if you think in regular expressions.
  2. The remaining characters in the id have to be a lowercase or uppercase letter or a digit or a hyphen (-) or an underscore (_).
  3. You can only define an id value once in an entire Markua document, even one that is split over multiple files.

These restrictions ensure that your ids can then be linked to by a crosslink from anywhere in the Markua document.

The id needs to be defined on either a block or span element.

Defining an id on a Block Element

To define an id on a block element like a paragraph, figure, heading or even a definition list item, you simply stick the id definition on a line above the start of the block element. Note that exactly one newline must separate the attribute list from the block element–if two newlines are used, the attribute list will be interpreted as a directive, and the id won’t be correctly applied.

Here’s how to use the attribute list syntax to define an id attribute:

{id: some-id}
This is a paragraph with the id of `some-id`.

Here’s how to use the shorter “syntactic sugar” approach to define an id attribute:

{#some-id}
This is a paragraph with the id of `some-id`.

Defining an id on a Span Element

To define an id on a span element you simply add the id definition immediately after the span element.

Here’s how to use the attribute list syntax to define an id attribute on a span element:

The word Markua{id: markua} has an id.

Leanpub is based in **Victoria, BC, Canada**{id: victoria}.

Here’s how to use the shorter “syntactic sugar” approach to define an id attribute:

The word Markua{#markua} has an id.

Leanpub is based in **Victoria, BC, Canada**{#victoria}.

Here’s how to define an id on a custom span:

The [quick sly fox]{#quick_sly} jumped over the lazy dogs.

If you want to define an id on a span while also defining other attributes like index entries, the id: syntax must be used in a full attribute list:

The [quick sly fox]{id: quick_sly, i: "Fox, Sly and Quick"} jumped over the lazy dogs.

Regardless of how you defined the id, you then link to it to create a crosslink. To do this, you use the # character and the id in a link:

[link text](#some-id)

This syntax is intended to be reminiscent of HTML anchor tags, not of h1 titles in Markua.

Note that order of definition and use does not matter: crosslinks will work regardless of whether the id is defined before or after the use of it.

  • If a Markua document contains duplicate id attribute values, the first one is used and the subsequent ones are ignored. A Markua Processor should output a warning about duplicate ids.
  • Crosslinks that reference an unused id may either be created as a (broken, non-functional) link or be created as normal text (not a link) by a Markua Processor. The Markua Processor may also output a warning about this somewhere, but not in the actual document text itself.

Chapters, sections and figures with captions often have two useful properties for writers:

  1. A name which is often short and useful to reference.
  2. A number, if numbering is turned on.

Whether the numbers exist is determined by the number-chapters, number-parts and number-figures attributes .

In your writing, it’s often desirable to refer to these figures from elsewhere in your book. When creating such a reference, it’s helpful to be able to reference the title and number of the chapter, section or figure.

Here’s how these references to titles and numbers work:

  • #t is for “title”
  • #n is for “number”
  • #d is for “description” (e.g. “Figure”, “Chapter”, “Section”)
  • #f is for “full title”

So, for “Figure 8.2: Anatomy of a Squirrel”, these are:

  • #t is “Anatomy of a Squirrel”
  • #n is “8.2”
  • #d is “Figure”
  • #f is “Figure 8.2: Anatomy of a Squirrel”

Note that in this example, “Anatomy of a Squirrel” was typed by the author, whereas “Figure 8.2: “ was generated by the Markua Processor. It does not matter; both can be referenced.

Also, note that regardless of section level, sections referenced in #d or #f are all called “Section” (not “Sub-Section”, “Sub-Sub-Section”, etc.)

The expectation is that #f will be used by authors who don’t mind verbosity, and #t and #n will be used by authors who prefer control and brevity. The #d is for very lazy authors who like saving keystrokes and/or who don’t know whether their publisher will call the code samples “Listing”, “Example” or some other word and want to protect themselves against extra work.

The code-sample-names, figure-names and table-names settings control the words used to name things.

Examples:

This is discussed in [section #n, #t](#crosslinks).

This is discussed in [#f](#crosslinks).

This is discussed in a [#d](#crosslinks) above.

See [chapter #n](#span-elements), which is the best chapter in this book.

This is in figure [#n](#fancy-diagram), arguably the fanciest diagram in this document.

The only way to reference the title and numbers is in crosslinks. There’s no syntax to do so without creating a crosslink–a crosslink is more helpful, since it is clickable, and adding another syntax simply to be less helpful to the reader is a bad idea. Markua has enough syntax as it is.

Note that resources, chapters and sections all have implicit numbering. So, #n always works even if numbering is off. However, you will confuse readers if you refer to numbering they cannot see. Also, if numbering is off, the #f must not include either the #d or #n parts: it will be “Anatomy of a Squirrel” not “Figure 8.2: Anatomy of a Squirrel”.

Character Substitution (X-- for X—, X -- for X –, ... for …)

All Markua documents are written in UTF-8, so to produce any Unicode chracter, it possible to just use the proper Unicode characters. However, in certain cases, it’s desirable for Markua to specify automatic replacement of certain combinations of characters with a Unicode replacement. If a Markua Processor encounters one of these combinations of characters outside of a code block, the Markua Processor must replace the combination of characters with the appropriate Unicode character in the output.

--
To produce an em dash (—), what is thought of by non-typography people as a “dash” or a “long dash”, you can just type two hyphens (--) directly after a non-space character. You can also use the proper Unicode character, U+2014, of course. The following all produce em dashes: foo--bar, foo-- bar, foo--.
--
To produce a space followed by an en dash (–), or the kind of dash that’s wider than a hyphen but narrower than an em dash, you can just type a space, followed by two hyphens ( --). You can also use the proper Unicode character, U+2013, of course. The following both produce en dashes preceded by spaces: foo -- bar, foo --. (With foo -- bar, there’s a space before and after the en dash; with foo --, there’s no space after it (e.g. at the end of a paragraph).
...
To produce a horizontal ellipsis (…), you can just type .... You can also use the proper Unicode character, U+2026, of course.

Optional Automatic Curly Quotes Outside of Code Blocks and Spans

A Markua Processor may replace the " character with the appropriate “curly quote” at its discretion. This lets "typography" become “typography”, and it's become it’s as appropriate.

Note that this is an optional behaviour: a Markua Procesor may support this fully, only in some output formats, or not at all.

Also, note that it is NEVER acceptable for a Markua Processor to do this, or any character substitution, to text inside a code block or code span. In almost all instances this would completely break the code. (If you wonder how I got curly quotes into the code spans for “typography” and it’s above, it’s because I pasted them into the manuscript that way. Just as a Markua Processor doesn’t make straight quotes curly in a code span, it doesn’t make curly quotes straight in a code span either.)

Soft Hyphen

In certain rare situations, it’s desirable to be able to give hints to a Markua Processor about where hyphenation can be done.

This attribute makes me sad. However, it’s a nod to reality. Hopefully this attribute is never used by authors writing the first draft of anything.

To insert a soft hyphen, used a backslash followed by a hyphen:

Example:

My name is Rumpel\-stiltskin.

Escaping Special Characters with Backslash (\)

Curly braces and backticks are special in Markua.

At the beginning of a line, an opening curly brace ({) starts an attribute list. In the middle of a block element, an opening curly brace starts an index entry. And, at the top of a manuscript.txt file (if the single file approach is used), an opening curly brace starts a settings block.

So, to use a curly brace as an actual curly brace character, you need to backslash-escape it like this: \{. (Note that this does not apply inside code or other resources: Markua does not process anything inside them.)

Similarly, a backtick is special. In text content (such as this paragraph), a backtick starts an inline span resource such as a code resource. And three backticks on a line by themselves start a code block. So, to show a literal backtick in a span, you preface it with a backslash (\).

Unicode Entities with \u

Typing obscure Unicode characters is hard. So, markup and programming languages often support outputting entity references to Unicode characters. For example, consider the unicode character with the code point U+1F602. In HTML, this is the entity &#x1F602; in hexadecimal or &#128514; in decimal. In JavaScript and many programming languages it is \u1F602.

Markua supports Unicode entity references as well. To output a Unicode character, you can type a backslash (\), followed by a u, followed by the hexadecimal value of the Unicode code point, followed by a semicolon. For example, you can type \u1F602; in Markua. The reason the semicolon is required is to clearly indicate the end of the Unicode hexadecimal value to the Markua Processor.

Now, there’s no guarantee that a given Unicode character will be present in a given font.

If a Markua Processor recognizes that a given Unicode character is not present in the font it is currently using, it may switch to a font that it knows will support that character. However, it is entirely acceptable for a Markua Processor to not do anything fancy, and to just attempt to output the character in the font it is using. In this case, what will typically happen is that the font will output a box in place of the missing character. These boxes are affectionately referred to as “tofu” by font people. (You may also encounter a diamond with a question mark in it in this case.)

Emoji

In 2015, emoji fully arrived. The 2015 Oxford Dictionaries Word of the Year was, in fact, the Face with Tears of Joy emoji. You may think of it a a smiling face with tears of joy, but you can also can think of it as \u1F602;, which is its Unicode code point.

However, Unicode characters aren’t the only way to do emoji. Another popular syntax for emoji is :emoji_name: – that is a colon (:), followed by the underscore-separated name of the emoji, followed by a colon.

What should Markua do?

Well, first of all, this is fantastic news. Emoji are the single legitimate use case for an inline span image, but any syntax I could invent to specify alt text on an inline span image was either disgusting or was inconsistent with how images are inserted as figures with figure captions.

So, now that emoji are on the rise and have two syntaxes to support them, this problem is solved: emoji can be inserted using either Unicode entities or the special emoji syntax, and the output generated by a Markua Processor is (hopefully) the emoji. So, there’s no need for an inline span image syntax!

Markua handles both emoji syntaxes, but it handles them differently.

For the Unicode entity syntax, you just type the Unicode entity. For example, you could write the following sentence:

The emoji support in Markua makes me \u1F602;

Again, as discussed above, there is no requirement for a Markua Processor to support a given Unicode character.

With the :emoji_name: syntax, a similar, slightly less happy, sentence would be:

The emoji support in Markua makes me :smile:.

When outputting a sentence containing emoji inserted using the :emoji_name: syntax, the Markua Processor can either:

  1. Output the emoji as a span image (right in the flow of the text with no line breaks before or after it) with the :emoji_name: (including the colons) as alt text.
  2. Output the emoji using an emoji-aware font, having mapped the emoji name to some Unicode code point using some cannoical table somewhere. There are online resources such as http://www.webpagefx.com/tools/emoji-cheat-sheet/ which may be a starting point for any Markua Processor wishing to do this.
  3. Output the :emoji_name: as an inline code span showing the :emoji_name: verbatim.

CriticMarkup

CriticMarkup is supported in Markua. CriticMarkup describes itself as follows:

a way for authors and editors to track changes to documents in plain text. As with Markdown, small groups of distinctive characters allow you to highlight insertions, deletions, substitutions and comments, all without the overhead of heavy, proprietary office suites.

Basically, supporting CriticMarkup gives Markua authors the benefit of track changes in Word, but with all the benefits of using Markua. An editor can use CriticMarkup to make suggestions about text to add, delete or replace, as well as leaving comments and highlights on selected text.

The largest benefit to using the CriticMarkup syntax in Markua is that since Markua documents are in plain text, you can use proper version control (like Git or Mercurial) with them, and this includes having the comments versioned right along with the rest of the Markua manuscript. Finding a comment that you deleted six months ago is as easy as checking out the revision that contained the comment.

If you enjoy using track changes in Word, then you’ll enjoy using CriticMarkup. If you don’t enjoy working with editors or getting feedback about your writing in the text itself, then CriticMarkup isn’t for you! If this is the case, don’t worry about it: the support for CriticMarkup has no impact on the rest of Markua. If you don’t want to use it, you don’t need to learn about it.

There are five types of changes supported by the markup in CriticMarkup:

Change Markup
Addition {++++}
Deletion {----}
Substitution {~~~>~~}
Comment {>><<}
Highlight {====}{>><<}

These types of markup do not conflict with any Markua markup for attribute lists, since the opening curly brace is always followed by special characters.

Markua Processors can support CriticMarkup in one of two ways:

  1. By outputting the additions, deletions, substitutions, comments and highlights appropriately, as defined in the very well-written CriticMarkup spec.
  2. By outputting the original text, removing all suggestions made in CriticMarkup.

Both ways are appropriate, and a Markua Processor could support both. For example, a Markua Processor could output CriticMarkup when previewing, but output only the original text when publishing.

For example, the following example shows a paragraph annotated with all five types of CriticMarkup:

If you enjoy using track changes{>>Who enjoys this?<<} in Word, then {~~you'll enjoy~>you may like~~} using
CriticMarkup {++annotations++}. If you don't enjoy working with editors{-- or getting feedback about your
writing in the text itself--}, then CriticMarkup isn't for you! If this is the case, don't worry about
it: {==the support for CriticMarkup has no impact on the rest of Markua==}{>>This sounds ambivalent.<<}.
If you don't want to use it, you don't need to learn about it.

Note that to hide an entire chapter or section, it’s cleaner to use the book attribute, described here.

Metadata

Attributes

Attributes are used to do everything from specify the language of code blocks, add ids for crosslinking and even support extensions to Markua. We have already seen attributes throughout the specification in the attribute lists we have encountered.

Attribute List Format

An attribute list is one or more key-value, comma-separated pairs:

{key_one: value1, key_two: value_two, key_three: "value three!", key_four: true, key_five: 0, key_six: 3.14}

Note that you can skip the space between the colon and the value: the following {format: ruby} and {format:ruby} both work. However, for consistency I recommend always adding a space.

An attribute list can be inserted into a Markua document in one of three ways:

  1. Immediately above a block element (e.g. heading, figure, aside, blurb, quiz, etc.), with one newline separating it from the block element.
  2. Immediately after a span element (e.g. a word, italicized phrase, etc.), with no spaces separating it from the span element.
  3. On a line by itself, with one blank line above and below it. In this format, the attribute list contains directives.

Regarding #2 and #3: Any line outside of a code resource which starts with an opening curly brace { and ends with a closing curly brace } is assumed to be an attribute list, and will not be output by a Markua Processor. If you want to start a line with a literal opening curly brace { you need to preface it with a backslash (\).

Attribute Keys

The keys of attributes must consist exclusively of lowercase letters, hyphens (-) and underscores (_). Uppercase letters are not permitted in attribute keys: a Markua Processor must treat uppercase letters in attribute keys as an error.

If a key is duplicated in an attribute list, the first key value is used and subsequent ones are ignored. A Markua Processor should add a warning in its list of warnings, which are not output in the ouptut itself.

Attribute Values

All attributes are text. Markua Processors should interpret text values of “true” and “false” as representing true and false. Quotes are optional for attribute values, and are only needed if the attribute value contains whitespace or special characters.

If a text attribute value contains a quote, it must be “escaped” with a backslash: e.g. {caption: "\"Fresh\" Fish"}

id Attributes

As previously discussed, there is special syntactic sugar for ids: {#foo} is equivalent to {id: foo}. However, ids are just attributes.

title Attributes

Markua headings (part, chapter, section, sub-section, etc.) and figures can all have title attributes specified in an attribute list. This is text which overrides what is displayed for the heading or figure in the table of contents. For a heading, it is analogous to the title attribute on a resource inserted as a figure, which specifies the text to use for the figure in the appropriate list of figures (e.g. List of Illustrations, Table of Tables, etc.). If a heading does not have a title attribute, the text of the heading itself is used–which is quite often exactly what is desired. Use of a title attribute is always optional; it’s only used when the default behaviour of using the heading text (or the caption attribute for a resource) is not appropriate, say if it’s too long.

Conditional Inclusion Attributes: book, sample, etc.

Markua headings may have various attributes which specify which output formats their content (of the part, chapter, section, sub-section, etc.) should be included in. If the given attribute is not present, the default value of it is that specified by the nearest ancestor heading. If no such attribute is present at a top-level heading, the default is given by the default value for the attribute defined of Markua.

There are six attributes which specify conditional inclusion in output targets; three for books, and three for courses.

book
If true, include this heading and its content (including nested sections, subsections, etc.) in the book that is being generated. If false, omit it. The default is true. Setting this to false is an easy way to “comment out” a section of your book.
sample
If true, include the content under this heading (including nested sections, subsections, etc.) in the sample of the book that is being generated. If false, omit it. The default is false. Note that this attribute just governs the inclusion of the content, not the heading itself. A Markua Processor may choose to include every heading in the sample version of a book or course, in order to produce a representative Table of Contents. In a case such as this where sample is false, the Markua Processor may output special content inside the chapter, section or subsection to indicate that the content itself is being omitted from the sample.
instructor
If true, include this heading and its content (including nested sections, subsections, etc.) in the instructor version of the book that is being generated, if one exists. If false, omit it. The default is true.
course
If true, include this heading and its content (including nested sections, subsections, etc.) in the course material that is being generated. If false, omit it. The default is true. Setting this to false is an easy way to “comment out” a section of your course.
course-sample
If true, include this heading and its content (including nested sections, subsections, etc.) in the sample of the course material that is being generated. If false, omit it. The default is false.
course-instructor
If true, include this heading and its content (including nested sections, subsections, etc.) in the instructor version of the course material that is being generated, if one exists. If false, omit it. The default is true.

This set of defaults means that by default, there is no book or course content included in the sample version of a book or course. As discussed, the headings themselves may all be included, in order to generate an appropriate Table of Contents for the sample book or course.

The reason that there are different attributes used for books and courses, instead of a course just reusing the same values that are used by a book, is that this way the same manuscript can be used to produce a book and a course. This approach is obviously not for everyone, but it may appeal to highly technical authors who wish to not repeat themselves.

Note that specifying one of these attributes in a nested section overrides any value inherited from its ancestors, or from the default. This way, you can include a chapter in the sample, except for a specific section of the chapter.

Example:

{sample: true}
# Chapter One

This is included in the sample.

## Section One

This is included in the sample.

{sample: false}
## Section Two

This is *not* included in the sample.

## Section Three

This is included in the sample.

{book: false, sample: true}
# Buy the book!

What you read was just a sample. Why not buy the full book?

# Chapter Two

This is not included in the sample.

Extension Attributes

Markua Processors may encounter attributes which they do not understand. If the Markua Processor is being used to output HTML or EPUB, it must output these attributes unchanged. If the Markua Processor is being used to output a different format, it must just ignore and discard the unrecognized attribute. This is true whether the attributes are inserted in an attribute list attached to a span, block or even in free-floating directives.

Because of this, Markua attribute lists can contain any number of extension attributes. An extension attribute is an attribute which is not defined in the Markua specification.

This encourages competition in the Markua ecosystem, while ensuring that Markua implementations do not choke on Markua input which goes beyond their capabilities.

Extension attributes go far beyond adding icons to blurbs: they allow for specialized uses of Markua. Since CSS is so powerful, with creative uses of custom attributes and custom CSS, Markua documents can be transformed. Some obvious uses of extension attributes include adding CSS classes which can then be styled to set fonts, adding custom types to figures for things like lemmas and theorems, etc.

This ensures that new attributes can be added to future versions of Markua without a negative effect on older Markua implementations. It also ensures that new versions of Markua can simply stop supporting attributes defined in this version of Markua without needing to specify anything special.

Index Entries

Markua supports adding index entries via the attribute list syntax. Index entries let authors or indexers produce professional-looking indexes in Markua books.

Index entries can either be attached to block or span elements using the same attribute list syntax. In fact, index entries can just be added as part of a larger attribute list.

The actual syntax of what the value of an index entry looks like is inspired by LaTeX.

The key of an index entry is i, for index.

In its simplest form, an index entry is simply {i: "hello"}. Like any attribute list, you don’t need a space between the colon and the quote–you can also do {i:"hello"}.

These are the various formats of an index entry:

{i: hello}
{i: "hello"}
{i: "Armstrong, Peter"}
{i: "Yahoo\!"}
{i: "*hello*"}
{i: "**hello**"}
{i: "hello!Peter"}
{i: "hello!*Peter*"}
{i: "hello!**Peter**"}
{i: "Peter|see{i:'hello'}"}
{i: "Jen|seealso{i:'Jenny'}"}

Here’s what they do:

{i: hello}
Adds an index entry for hello. If an index entry has no punctuation or formatting then it does not need quotes.
{i: "hello"}
Adds an index entry for hello. Quotes are always fine to use, even when not required.
{i: "Armstrong, Peter"}
Adds an index entry for Armstrong, Peter. The quotes are always omitted. Their function is to allow things like exclamation marks and other punctuation to be added without fear, in case you don’t feel like learning which punctuation is safe.
{i: "Yahoo\!"}
Adds an index entry for Yahoo!. Note that the exclamation mark must be backslash-escaped because ! is a delimiter otherwise. The |, {, } and \ characters also must be backslash-escaped.
{i: "*hello*"}
Adds an index entry for hello, with hello in italics.
{i: "**hello**"}
Adds an index entry for hello, with hello in bold.
{i: "hello!Peter"}
Adds an index entry for Peter which is a sub-entry of hello.
{i: "hello!*Peter*"}
Adds an index entry for Peter (with Peter in emphasis) which is a sub-entry of hello. Note that this cannot be combined with a see or seealso (the syntax).
{i: "hello!**Peter**"}
Adds an index entry for Peter (with Peter in strong emphasis) which is a sub-entry of hello. Note that this cannot be combined with a see or seealso (the syntax).
{i: "Peter|see{i:'hello'}"}
Adds an index entry for Peter, which references the index entry hello with the equivalent of “see” in the language of the book. Note that this cannot be combined with a sub-entry (the ! syntax).
{i: "Jen|seealso{i:'Jenny'}"}
Adds an index entry for Jen, which references the index entry Jenny with the equivalent of “see also” in the language of the book. Note that this cannot be combined with a sub-entry (the ! syntax).

Index entries are case sensitive. For example, {i: "mark"} and {i: "Mark"} are distinct entries. (The first is for a result or a smudge, the second is a person’s name.)

To attach an index entry to the start of a block, put it on its own line above a block:

{i: "hello"}
I just came to say hello, hello, hello, hello

To attach an index entry to a word, just add the index entry after the word:

I just came to say hello{i: "hello"}, hello, hello, hello

To attach an index entry to a span element, just add the index entry after the span element:

The first program that a programmer writes in a language is usually *Hello World*{i: "Hello World"}

Index entries can have commas and other punctuation (except colons) in their definition:

My wife read some book about a whale by Herman Melville{i: "Melville, Herman"}.

Multiple index entries can exist in a block, or even a sentence:

Supposedly the great-great-great-granduncle of the musician Moby{i: "Moby"} was Herman
Melville{i: "Melville, Herman"}, the author of a book about a whale{i: "Moby-Dick; or, The Whale"}.

Note that adding index entries is best left until the author is done writing the book. At that time, ids like {#myid} can be converted to {id: #myid, i: “blah”} if index entries are being added where ids already are.

Directives

Directives are switches which affect the future behaviour of a Markua Processor.

The syntax for directives is simple: they are just contained in an attribute list. The only difference is that the attribute list is inserted an a line by itself, with one blank line above and below it. (There are two exceptions: if the directive is at the beginning of a manuscript file, you can omit the blank line above it; if it’s at the end of a manuscript file, you can omit the blank line below it.)

A directive does not have any kind of “closing tag”–it simply remains in effect for the rest of the Markua document, or until the directive is overridden by another use of the same directive with a different value.

The lang Directive

A book has a global lang setting, which defaults to eng, for English.

However, many books are written in more than one language. Switching between languages in accomplished using the lang directive.

For example, say I’m writing a book about Waka. If I want to switch to Japanese to display a poem I can do so using a lang directive {lang: jpn} and then switch back to English using {lang: eng}.

The value of the lang directive must be a valid ISO 639-3 language code.

The two main things that the lang directive affects are:

  1. the direction of the text (left-to-right or right-to-left)
  2. the font used for the language

Since English is the default language of a Markua document, all Markua Processors must support the eng value of the lang directive. Support for all other language codes is optional. If the language code given as the value of a lang directive is not supported or is unrecognized, it must be interpreted as eng and switch the font accordingly and switch the direction to left-to-right. This way, a Markua Processor can add support for right-to-left languages such as Arabic ({lang: ara}) or Hebrew ({lang: heb}), and know that when a different language is specified the direction will switch to left-to-right even if the given language was not supported–there are a lot of languages, but almost all of them are left-to-right languages.

Book Section Directives

Most published books have three types of material in them: the front matter, the text and the back matter.

What authors write, the manuscript, is typically what goes into the text, or main matter, of the book. In style guidelines such as the Chicago Manual of Style this is called the text; in formats such as TeX and LaTeX it is called main matter. It’s what is numbered with Arabic numerals starting from 1.

There’s a bunch of other stuff (the Dedication, Epigraph, Table of Contents, Foreword, Preface, etc.) which can come before the main text of the book. This is called “front matter”. Some of the front matter comes before the Table of Contents and is not numbered; the rest of the front matter that comes after the Table of Contents gets numbered with Roman numerals.

There’s also a bunch of other stuff (acknowledgments, appendices, the index, etc) which can come after the main matter. This is called the “back matter”.

If Markua just relied on its headings support there would be no good way to accomplish the division of a manuscript into front matter, main matter and back matter. (We could try some convention about heading names, but that would be a highly objectionable, English-centric hack.) Furthermore, there would be no good way to determine which parts of the front matter got numbered and which did not. Also, there would be no good way to give explicit hints to Markua Processors about how to style the various parts of a book.

The book section directive is the solution to this. You add a book section directive like this:

{section: mainmatter}

Adding multiple instances of the section directive throughout the book lets you indicate to Markua Processors what section of a book they are in, in order to affect numbering, formatting and other concerns like the placement of the Table of Contents.

Markua is a fairly minimalist format, so this is all accomplished with one directive. Furthermore, for authors who do not know about this directive, nothing bad or unexpected will happen.

There are three types of values of the book section directive: front matter values, the mainmatter value and back matter values. These values are named for the different book sections identified in the Chicago Manual of Style.

The following values of the section directive can occur in front matter:

  • half-title
  • series-title
  • title-page
  • copyright
  • dedication
  • epigraph
  • table-of-contents
  • figures
  • tables
  • foreword
  • preface
  • acknowledgments
  • introduction
  • abbreviations
  • chronology

The {section: mainmatter} value indicates that the front matter is over. It is the start of the first numbered page of the text. Note that the acknowledgments, abbreviations and chronology directives can also occur after the {section: mainmatter} directive, as a matter of style preference.

The following values of the section directive can occur in back matter:

  • appendices
  • notes
  • glossary
  • bibliography
  • contributors
  • illustration-credits
  • index
  • exercise-answers
  • quiz-answers

The bibliography directive allows a Markua Processor to specially format the text inside that section appropriately. The exercise-answers and quiz-answers directives are used to position the answers to any exercises or quizzes in the text of the Markua document. If neither of these directives are present, a Markua Processor should position the exercise answers somewhere near the back of the book (in the back matter, if it exists). For quiz answers, on the other hand, a Markua Processor may do whatever it wants in terms of whether the quiz answers are included in the book, regardless of the presence or position of the quiz-answers directive. For example, in Leanpub’s online courses, the quiz answers are only provided when quizzes are completed and automatically marked, and are never output in the material book for the course.

You can write a book or document in Markua without using any directives at all, including book section directives. However, if you add a section directive with a value of any of the front matter values, the {section: mainmatter} directive is required.

If you’re an author and this seems confusing, don’t fear. Almost all of the book section directives will typically be added either by someone working for a publisher or automatically by book generation software. The only section directives that many authors will use are {section: dedication} and {section: mainmatter}.

Also, note that Markua Processors may ignore all of the book section directives. Book section directives are only hints that indicate that the Markua Processor may wish to do things like switch to hanging indents, change the font size, insert a table of contents at that location, use a custom layout, etc. based on what section of the book they are in.

While these book section directives are mere hints, there are strict rules about their use:

  1. Each value of a book section directive can only appear once.
  2. The book section directives are all optional; it is legal to have a Markua document with no book section directives.
  3. If any book section directives with values which occur in front matter are present, a {section: mainmatter} directive is required.

Authors new to Markua can completely ignore all directives, including book section directives. Only when they wonder how to make certain sections excluded from the numbering, or to have Roman numerals etc, do they have to worry about book section directives. And using directives is very simple, despite how formally specified this section makes them.

Settings

As discussed earlier, a Markua document can be written in one file or multiple manuscript files. If a manuscript is written in multiple files, these files are concatenated together by the Markua Processor to produce one temporary manuscript file, and that one file is used as the input.

At the very beginning of the first (or only) manuscript file, a Markua document can contain settings. The settings are just newline-separated key-value pairs which contain information about the document. This will include things like the title, subtitle, copyright, author names, etc.

These settings are enclosed in a “settings hash” in curly braces like this:

{
title: Markua Specification
authors: Peter Armstrong
contributors: Scott Patten, Braden Simpson and Len Epp
copyright: Peter Armstrong
}

# The Magical Typewriter

Imagine you owned a magical typewriter...

The format of the metadata is one entry per line, with the keys and values separated by a colon and a space. Any whitespace at the beginning or end of the keys and values will be stripped. Only the first colon is important; subsequent colons on a line will just be part of the value.

There is a blank line between the settings hash and the manuscript content.

A Markua Processor may also get settings from elsewhere, like a web interface. However, in the case of a conflict, any settings specified in the settings hash must win.

Markua-Defined Settings

The following settings must be supported by all Markua Processors. Markua Processors can also add their own settings, just as Markua Processors can understand their own extension attributes.

authors
The authors of the Markua document.
contributors
Any contributors to the Markua document who are not authors.
copyright
The owner of the copyright.
default-code-language
The default language that code is. The default is guess, which means to guess at the code language based on the syntax encountered (or the file extension for external code samples), and attempt to syntax highlight appropriately. A good alternative is text, which means no syntax highlighting should be used, but the code should be in a monospaced font suitable for a programming language. Besides these options, you can specify a particular programming language used, such as ruby or java. If a Markua Processor does not recognize the programming language specified, it must format it as text.
lang
The IS0 639-3 three character language code of the language that the Markua document is written in. The default is eng.
number-chapters
true or false. Default true. Whether the chapters are numbered.
number-sections
true or false. Default false. Whether the sections (and sub-sections) are numbered.
number-figures
true or false. Default true. Whether resources are numbered when inserted as figures. Note that different types of resources (e.g. code listings, tables, images, etc.) have different numbering.
restart-endnote-numbering
true or false. Default true. Whether the endnote numbering is restarted at the end of a chapter.
restart-footnote-numbering
true or false. Default true. Whether the footnote numbering is restarted at the end of a chapter.
title
The title of the Markua document.

Appendices

These appendices contain details which would be distracting or boring if included in the main body of the Markua specification. These include highly technical details, differences with Markdown, discussions of HTML mapping and notes for Leanpub authors.

Origins of Markua

At Leanpub, my cofounder Scott Patten and I created a dialect of Markdown called “Leanpub Flavoured Markdown”. Leanpub Flavoured Markdown was basically Markdown minus inline HTML plus a number of extensions needed to write books. This Markdown dialect has been used for years by Leanpub authors to create all kinds of books.

Markua is the evolution of how Markdown is used at Leanpub. After years of experience with Leanpub Flavoured Markdown, I set out to specify it properly. I originally thought that this is what Markua would be: just a formalization of Leanpub Flavoured Markdown. But as the specification work evolved, I realized that Markua was really a descendant of Markdown, not just a flavour of it.

Books have different abstractions than HTML. All abstractions leak, so HTML’s abstractions leak into Markdown and the abstractions of books leak into Markua. So, I started over. I started with Markdown. I then removed or changed the few things which were either not needed for books, or which were overly complex. I then found new, more appropriate abstractions for books–most importantly resources, figures and attribute lists. I then reassembled the pieces around these abstractions into this (hopefully coherent) whole.

Why the Name “Markua”?

When I set out to specify Markua, I realized I needed a name. I wanted a name that conveyed the warmth and love that I have for Markdown, for writing and for writers, while not implying endorsement by John Gruber in any way. I also did not want a name which refenced Leanpub: Markua is a standalone specification with its own identity, which anyone (including Leanpub competitors) can freely implement. Finally, I was on vacation in Hawaii when I named Markua, and I wanted something that sounded happy, friendly and almost Hawaiian. (Yes, I’m aware that there is no r in Hawaiian.) I also wanted a name that had its .com domain name available, and that was short and spellable, for branding purposes. The Markua name does have all these these properties, and I feel it is a really good brand for what I’m trying to accomplish.

Plain Text Encoding in UTF-8

Markua documents are written in plain text. Specifically, Markua documents must be saved in the UTF-8 character encoding. ASCII text (what “plain text” means to most westerners) is a valid subset of UTF-8, so for many western authors their favorite text editor already saves files as UTF-8 text.

No Inline HTML

Inline HTML, in which HTML is inserted directly in the content of a Markua document, is not supported in Markua.

HTML is just one possible output format, and other possible Markua output formats (such as PDF) are not based on HTML. If inline HTML was supported, a Markua Processor would have to support parsing and meaningfully outputting all of HTML syntax as well as all of Markua syntax.

Markua and Markdown have different use cases. Markdown is a better way to write HTML; Markua is a better way to write a book. Since Markdown’s only output format target is HTML, it might as well support inline HTML: generating HTML from HTML is as simple as passing the HTML through. From an implementation perspective, Markdown gets inline HTML support for free.

By not supporting inline HTML, Markua imposes more constraints on writers who would be tempted to use inline HTML for layout purposes. Since Markua does not support inline HTML, attempting to do complex layout in Markua using HTML is just not possible. And since it’s not possible, the temptation to procrastinate by doing formatting is reduced.

Now, one design benefit of the support for inline HTML in Markdown is that Markdown’s syntax can stay artificially small–since Markdown authors can always fall back to using HTML directly, Markdown does not need to be able to produce all of HTML. Since Markua does not support inline HTML, Markua must contain all concepts that it supports directly expressed using Markua syntax. For example, there is no official table syntax in Markdown, and Markdown authors can just use inline HTML tables. Since Markua does not support inline HTML, and since books often require tables, Markua needs to add a table syntax.

Markua Specification Scope

The Markua specification specifies the Markua syntax and the conceptual mapping from Markua syntax to book concepts. It does not specify the specific mapping from Markua syntax to any output format.

To be clear: the Markua Specification defines the syntax and semantics of a plain text writing format. This writing format can be used to produce a type of document which can be understood by a Markua Processor. The Markua Specification defines the input to a Markua Processor, but it does not define the output.

Markua Processors can output any number of output formats from a Markua document. For example, Leanpub can output PDF, EPUB, MOBI, HTML and InDesign all from the same Markua source document. None of these output formats is required to be supported by a given Markua Processor. To be useful, however, a Markua Processor should output some output format. (For the programmers: /dev/null is not a good Markua Processor.)

Not only are there no required output formats for a Markua Processor, the mapping from a Markua document to any output format is also not formally specifed–not even for HTML.

No Canonical HTML Mapping

There are a number of reasons that the Markua specification does not contain a canonical mapping from Markua to HTML:

  1. The main reason that the mapping from Markua to HTML is not specified is that HTML is not special; it’s just one possible output format of a Markua Processor. Specifying the mapping from Markua to HTML but not to other output formats would be inconsistent and wrong.
  2. HTML and HTML5 are evolving specifications. Including a mapping to one specific version of them would be arbitrary, and would force the Markua Specification to be constantly updated or become dated. The Markua Specification is intended to be stable.
  3. HTML5 has certain strong opinions toward concepts like emphasis, whitespace, paragraphs and lists which I do not agree with. If I was to specify a canonical mapping to HTML5, I would either have to adopt positions I don’t agree with or fight battles I have no interest in winning. Life is too short to do either.
  4. By not specifying an HTML mapping, this maximizes implementation flexibility and encourages competition among implementers of Markua Processors. Markua is very feature-rich, and specifying every single detail of the HTML output would highly limit flexibility. It doesn’t make much sense to only specify the HTML output for a subset of the Markua specification: it’s all-or-nothing, so I choose nothing.
  5. This specification is long enough as it is.

Obviously, Leanpub has a mapping from Markua to HTML5: we use it to produce the EPUB versions of our ebooks. An incomplete version of this mapping is specified in the book An Unofficial Mapping from Markua to HTML5. As the title of that book suggests, that mapping, and any mapping that we specify, is just one possible mapping from Markua to HTML5. In the delightful phrasing of the W3C, it is “non-normative”.

Differences with Markdown

Markua has a number of differences from Markdown as defined by John Gruber. These are the main ones:

  1. Markdown supports inline HTML; as discussed earlier, Markua does not.
  2. Markua defines many more types of numbered list numbering than Markdown. In Markdown, the only type of numbering supported is decimal numbering starting from 1. If you need any more features, you need to use inline HTML. However, since Markua does not support inline HTML, Markua provides more list types and features.
  3. Unlike in Markdown, in Markua the number that begins the list in the manuscript is the number that begins the list in the output.
  4. Markdown does not specify a table syntax. Since Markdown supports inline HTML, it does not need to–if you want a table, you can simply use an inline HTML table. Since Markua does not support inline HTML, Markua defines a table syntax.
  5. Images in Markua are inserted in essentially the same way they are in Markdown for what Markdown calls “inline images”. Markdown’s inline images are not to be confused with Markua’s inline image support, which means to define an SVG image in the text of a Markua document. Markdown’s reference style image syntax is not supported in Markua for any type of resource–including images. There are two main reasons for not supporting reference style resource syntax in Markua. First, resources in Markua are complex enough without also having a reference syntax for them. Second, in something as large as a book, the potential for id collisions in link definitions using the reference link syntax is a lot higher than in the blog post length of typical Markdown documents.
  6. Markua supports definition lists; Markdown does not (except via inline HTML).
  7. Markdown lets you use a plus sign (+) before each item in an unordered (“bulleted” in Markua) list; Markua does not. Having three syntaxes is just overkill, so Markua drops the plus–it’s far less common than the asterisk and hyphen. This is the same decision made by GitHub Flavored Markdown, which also supports * and - but not +.
  8. Markdown does not support closing parentheses ()) as ordered (“numbered” in Markua) list delimiters; Markua does.
  9. Markua and Markdown handle spaces, newlines and indentation differently. This is discussed in the Whitespace: Spaces, Tabs and Newlines section.
  10. In Markdown, lists and other block elements cannot be nested inside a paragraph; in Markua they can. This is discussed further below.
  11. Markdown’s reference link syntax and its implicit link name shortcuts are not supported in Markua. Markdown is a way of writing HTML designed by bloggers, and links are so plentiful in that medium that it makes some sense to support four syntaxes to create links. In ebooks, however, links are not as prevalent, so it makes sense to be opinionated here. Furthermore, in something as large as a book, the potential for id collisions in link definitions using the reference link syntax is a lot higher than in a blog post.
  12. Markua and Markdown handle headings differently. This is discussed further below.
  13. The backtick syntax of adding inline code resources as spans is identical to the code span syntax of Markdown, however the optional attribute list is Markua-specific.
  14. The syntax for inline code resource figures is similar to the “fenced code blocks” syntax of many Markdown extensions, such as PHP Markdown Extra and GitHub Flavoured Markdown.
  15. The “four space indent” method of creating code blocks in Markdown is not supported in Markua. You cannot create an inline code figure this way. It may be slightly more pleasant to read, but it’s obnoxious as hell to write, and it has terrible effects on the rest of the specification.
  16. In Markdown links, a URL can be either absolute (starting with http:// or https://) or relative (just referring to a path like /foo/bar.html), since relative URLs can make sense when writing blog posts which live on web servers. In Markua, however, all URLs must be absolute.
  17. In Markdown, there are three types of ways of producing horizontal rules in HTML: by putting three or more asterisks (***), hyphens (---) or underscores (___) on a line by themselves, with or without spaces between them. Markua isn’t in the business of producing HTML or horizontal rules. The *** is used for scene breaks, ___ starts poetry, and --- starts monospaced poetry.

Differences with Inserting Block Elements Inside Paragraphs

In Markdown, lists and other block elements cannot be nested inside a paragraph. Instead, they all function like top-level siblings to a paragraph. This makes sense since Markdown is a way of producing HTML, and in HTML5 the W3C has told anyone who wants to embed a list inside a paragraph to go pound sand:

“The solution is to realise that a paragraph, in HTML terms, is not a logical concept, but a structural one. In the fantastic example above, there are actually five paragraphs as defined by this specification: one before the list, one for each bullet, and one after the list.”

So, basically, you can’t embed a <ul> or <ol> inside a <p> tag in HTML5. Since Markdown is a way of producing HTML, you can’t do it in Markdown either.

In Markdown, a block element like a list or figure is a sibling of the paragraphs before or after it:

This is paragraph one.

* this is a
* sibling of
* paragraphs one and two

This is paragraph two.

Markua supports this method of inserting block elements.

However, Markua is more than just a way of producing HTML. Markua is a way of authoring books. HTML is just one of the many output formats of Markua. And in books, there is a long history of embedding lists, code samples and figures in the middle of a paragraph–not in a separate top-level element, in the actual middle of the paragraph. So, Markua supports this too.

Design Goals of Markua Headings

The following are the design goals of Markua headings:

  1. From looking at a heading in a Markua manuscript, an author must be able to know exactly what it is. It’s not acceptable to need to reference metadata to know what the headings mean.
  2. Only existing Markdown syntax can be used, to ensure that Markdown-aware tooling will work unchanged in essentially the correct way.
  3. The number of leading pound signs must match the level of heading.
  4. For a book with chapters only (no parts), the chapter headings must feel “top-level”.
  5. The syntax to create parts must be as economical as possible.
  6. There must be only one way to create every level of heading. Headings structure Markua documents, and must be clear and unambiguous.
  7. It should be possible to switch back and forth between having parts in your book without having to modify all existing headings.
  8. Books with parts and chapters must be able to have the same number of levels of sub-sections, without arbitrarily losing the ability to create a sub-sub-sub-sub-section.
  9. Documents can have parts, chapters and sections just like books.

The design of Markua headings meets these requirements, in a better way than any other design I could come up with.

Differences with Markdown Headings

Markdown is a way of writing HTML, and HTML has 6 heading levels: h1, h2, h3, h4, h5 and h6. In Markdown, you can create the 6 HTML heading levels using Markdown syntax.

What Markua does is to use a subset of the Markdown heading syntax, and then reinterpret those headings as specifying the heading levels that define the structure of the book.

Markua is also a lot more strict about heading syntax than Markdown. In Markdown, not only are there two syntaxes (atx and Setext) for making headings, what’s worse is that both of them can take many forms. However, in Markua there is exactly one way of making every type of heading. It is a subset of the atx headings in Markdown; Setext headings are not supported.

To understand Markua headings and the differences with Markdown headings, it’s helpful to understand the atx and Setext headings of Markdown.

Setext Headings in Markdown

In the Setext-style of Markdown headings, top level headings can be made by adding a row of equals signs ======== below the heading, and second level headings can be made by adding a row of minus signs -------- below the heading.

These are some Setext headers in Markdown:

This is an h1
=============

This is also an h1 (really)
=

This is an h2
-------------

This is also an h2 (really)
-

There are two main issues with this style of heading in Markdown:

  1. It is inconsistent: It only supports defining h1 and h2; to define h3 and below, the atx style of heading must be used.
  2. It is confusing: Authors are confused about how many equals or minus signs you need to use. (As we saw above, the answer is 1, which looks disgusting.) Also, it’s unclear whether you need to add a blank line below the row of equals signs or minus signs, and whether a heading is still produced if this is not done.

atx Headings in Markdown

In Markdown, the other heading syntax is “atx” headers. The atx format was created by Aaron Swartz in 2002, and is an important predecessor to Markdown. To create an atx heading, you put the following on a line by itself, with a blank line above and below it: between one and six pound signs (#), followed by one or more spaces or tabs, followed by text, followed optionally by whitespace and any number of # characters. The number of # characters determines the level of heading.

These are some atx headers in Markdown:

# This is an h1

# This is also an h1 ####################

## This is an h2

## This is also an h2 ###################

### This is an h3

### This is also an h3 ##################

Note that all the trailing # characters are ignored and are not part of the heading text.

From reading this, you’ll recognize that Markua headings are a subset of Markdown’s atx headers.

Differences with Leanpub Flavoured Markdown

Besides differences with Markdown in general, Markua also has a number of specific differences with Leanpub Flavoured Markdown (LFM):

  1. In LFM, parts are created with -#. In Markua, parts are created with # Part #.
  2. In LFM, there is a special syntax for inserting code samples: <<[Optional Title](code/some_code_file.rb). In Markua, however, code is just a resource, and the LFM syntax is not supported.
  3. In LFM, to mark code as added or removed, the magic words were leanpub-start-insert, leanpub-end-insert, leanpub-start-delete and leanpub-end-delete. In Markua, the magic words are markua-start-insert, markua-end-insert, markua-start-delete and markua-end-delete.
  4. In LFM, there is a special syntax for inserting math: {$$}...{/$$}. This looks nice to people who like LaTeX, and looks like nothing else in Markdown. In Markua, however, math is just another resource, and that LaTeX-inspired syntax for wrapping math resources is not supported.
  5. In LFM, there are G> “generic boxes”. In Markua, these are replaced with blurbs (B>).
  6. In LFM, X> defines an exercise block which is similar to a blurb in Markua, but styled as an exercise. In Markua, X> is used for structured exercises, which are essentially unmarked quizzes that have questions and answers provided. So, Markua does not define a blurb with a class of exercise, or any syntactic sugar for it.
  7. In LFM, we had {rtl} and {ltr} directives. These are not supported in Markua, and neither is a {dir} attribute in general: any given language is either a left-to-right or a right-to-left language, so specifying the language is sufficient.
  8. In LFM, we had a {pagebreak} directive. This is replaced by ===.
  9. In LFM, we used Book.txt to define the book content. In Markua, the way that the list of manuscript files is defined is considered out of scope of the Markua specification itself. (Leanpub still uses the Book.txt approach to specify which files are in a book, but other Markua Processors could use other approaches.)
  10. In LFM, we used Sample.txt to define the sample content. Markua moves the definition of what constitutes sample content into a {sample: true} attribute on parts, chapters and sections. So, in Markua, inclusion in the sample is at the content level, not the file level. This helps avoid a number of bugs that could happen with including at the file level, if a file did not clearly break at a chapter boundary. (So, in Leanpub, the Sample.txt approach is not supported for books which use Markua.)

Numbered List Numbering Rules

There are a number of rules about what does and does not trigger the creation of a numbered list. These rules are designed to help authors stay sane when writing in Markua, and also to help implementors of Markua Processors stay sane. In all cases, the first number, letter or Roman numeral is the start of the list numbering. This never changes.

If, because of the correct application of these rules, a numbered list is not created, what happens is that a paragraph is created instead, with a break tag for each single newline. In this instance, the output directly matches the input, including all the numbering.

In theory, Markua supports creating a numbered list when either of the following two conditions occur:

  1. Every item in the list begins with a consecutive number, either increasing or decreasing.
  2. Every item in the list begins with the same number.

This is not actually quite true.

See, the notion of “consecutive” is easy to explain and to check for decimal numbers, either in increasing or decreasing order. 1, 2, 3, ..., 456, 457, 458, ..., or 5, 4, 3 are all easily verified as consecutive, both by humans and computers.

However, Markua also supports numbered lists using uppercase and lowercase alphabetical numbering, as well as uppercase and lowercase Roman numeral numbering, and in increasing or decreasing order.

In the case of alphabetical numbering, checking “consecutive” is harder. It’s relatively straightforward for the first 26 items, but then all bets are off. In case you’re curious, here is the sequence used in HTML for increasing alphabetical numbering:

a, b, ..., z, aa, ab, ..., az, ba, bb, ... bz, za, zb, ..., zz, aaa, aab, ..., aaz, aba, abb, ...

In terms of Roman numerals, it’s even worse. I’m sure that someone in a Classics department (or in the NFL) knows the algorithm by heart, but I don’t.

So, what are Markua authors and implementors of Markua Processors to do?

Markua makes this simpler by specifying the following rules.

Markua actually supports creating a numbered list based on a different set of conditions based on the numbering type.

For decimal numbers, Markua actually supports creating a numbered list when either of the following two conditions occur:

  1. Every item in the list begins with a consecutive number, either increasing or decreasing.
  2. Every item in the list begins with 1.

For uppercase and lowercase alphabetical numbering, Markua actually supports creating a numbered list when either of the following two conditions occur:

  1. Every item in the list begins with a consecutive letter, followed by a period, and the lettering does not extend past z. for lowercase, or Z. for uppercase. (This way, implementors of Markua Processors don’t need to check the aa, case, and authors writing in Markua don’t need to remember it.)
  2. Every item in the list begins with a. for lowercase letters or A. for uppercase letters.

These rules mean you can’t start a list with aa. or higher. This is preferable to Markua having many variants of the Markdown 1986. problem. If you want to write a paragraph starting with “AA.”, to write a dramatic statement about either anti-aircraft fire or alcoholism, you would be really surprised to have created a single-element list beginning with “AA” instead!

For uppercase and lowercase Roman numeral numbering, Markua actually supports creating a numbered list when either of the following two conditions occur:

  1. Every item in the list begins with a consecutive Roman numeral, followed by a period, and the lettering does not extend past xii. for lowercase Roman numerals or XII. for uppercase Roman numerals. To be clear, this means that the only valid consecutive lowercase Roman numerals are i, ii, iii, iv, v, vi, vii, viii, ix, x, xi, xii, and that the only valid consecutive uppercase Roman numerals are I, II, III, IV, V, VI, VII, VIII, IX, X, XI, XII.
  2. Every item in the list begins with i. for lowercase Roman numerals or I. for uppercase Roman numerals.

The combination of the rules for Roman numeral numbering means that you can have an arbitrarily long Roman numeral list starting from i. or I., but that implementors of Markua Processors don’t need to write code to figure out whether MCMLXXV is a valid Roman numeral, and what the consecutive Roman numeral sequence after it is.

If you’re wondering why I picked xii and XII for the last consecutive lowercase and uppercase Roman numerals to respect: this is Roman numeral 12, and the main usage of Roman numerals in modern life is in clock faces.

Speaking of clock faces, I have bad news for fans of watches and antique clocks:

  • The only supported version of the Roman numeral 4 is the subtractive iv (in lowercase) or IV (in uppercase); the additive iiii or IIII form is not supported.
  • The only supported version of the Roman numeral 9 is the subtractive ix (in lowercase) or IX (in uppercase); the additive viiii or VIIII form is not supported.

It turns out that the question of additive versus subtractive forms of Roman numerals is actually interesting; see this article and this Wikipedia entry for a starting point.

In Markua, list numbers must all either be consecutive, given the type of numbering that is used, or the same as the first number. Otherwise, the list is interpreted as a paragraph with a bunch of break tags in it, and lines starting with the numbers given. The principle is the following: the numbers which are shown in the manuscript must be the same as those in the output, or the numbers must be clearly intended to be numbered list numbers. Otherwise, a list will not be produced.

If you want to prevent a list from being created with consecutive numbered items separated by single newlines, the backslash escape in front of the period used in Markdown to prevent lists also works in Markua. However, it is needed a lot less often.

Example of Why One Blank Line Is Added When Concatenating Manuscript Files

As discussed, one blank line is added when concatenating multiple manuscript files. To see why this rule is important, consider the following single-file Markua manuscript:

manuscript.txt
# Chapter One

Lorem ipsum dolor.

# Chapter Two

Yada yada yada.

Suppose instead a multiple-file approach was used, in which there were two files, ch1.txt and ch2.txt, with the following content:

ch1.txt
# Chapter One

Lorem ipsum dolor.
ch2.txt
# Chapter Two

Yada yada yada.

If Markua did not add any newlines between files, then these files would produce the following manuscript:

IncorrectTemporaryAuto-CreatedManuscript#1
# Chapter One

Lorem ipsum dolor.# Chapter Two

Yada yada yada.

If Markua only added one newline when concatenating, this would produce the following manuscript:

IncorrectTemporaryAuto-CreatedManuscript#2
# Chapter One

Lorem ipsum dolor.
# Chapter Two

Yada yada yada.

However, since Markua requires that headings be separated by blank lines above and below them, the Chapter Two heading would not be a heading. It would be considered part of the previous paragraph! This would be very surprising and the source of a number of bugs. Worse, since a number of text editors such as Emacs have a “strip blank lines at the end of files” setting, it would be possible to introduce such a bug if Markua simply relied on blank lines being added to the end of a file by the author.

So, because of the blank line rule, concatenating the files produces the same manuscript as the single-file manuscript above:

CorrectTemporaryAuto-CreatedManuscript
# Chapter One

Lorem ipsum dolor.

# Chapter Two

Yada yada yada.

Markua Specification Status

This is an in-progress, beta-quality specification. It is being constantly updated at https://leanpub.com/markua. To read the specification in PDF, EPUB, MOBI or HTML format, go there.

To read the specification manuscript in Markua, see https://github.com/markuadoc/markua.

To stay current on Markua progress, follow @markuadoc or @peterarmstrong on Twitter.

A Note For Leanpub Authors

If you’re reading this, you are a really, really early adopter of Markua.

Markua should be fully supported in Leanpub and in the open source version by the end of June 2017.

Markua support is currently in VERY EARLY BETA on Leanpub. Many portions of the Markua specification have not yet been implemented in Leanpub. In these cases, Markua will still function like Leanpub Flavoured Markdown. Leanpub Flavoured Markdown has been used in Leanpub for about 5 years. Below, I’m briefly listing what does and does not work in Leanpub’s current Markua support. Arguably this should not be done in this spec, but I’m doing it here until Leanpub fully supports Markua for two reasons:

  1. It will save Leanpub authors who are reading this spec a lot of pain.
  2. It will give readers of the spec a sense of which parts of the Markua spec have been tested, and which have not.

If you are curious to try Markua, to see what currently works (not much!) and what doesn’t (lots!), now you can! We have now made Markua mode available to all Leanpub authors. This makes sense, since writing a book can take a long time. We will have Markua fully supported in Leanpub in the next few months, so for many authors, Markua will be complete before their books will be complete. So, we want to enable all Leanpub authors to choose to write in Markua starting now.

I’m publishing the Markua spec in-progress, since I believe in Lean Publishing. (Lean Publishing is the act of publishing an in-progress book using lightweight tools and many iterations to get reader feedback, pivot until you have the right book and build traction once you do.)

Here’s an incomplete list of some of the work we still need to do in Leanpub to support Markua. Hopefully it gives you a clue about some things that do not work yet:

TODO in Leanpub

- There are now exercise (unmarked) and quiz (marked) as separate elements, much like aside and blurb are separate.
- There is no more type attribute on quizzes. Quizzes are always marked.
- Support Nested Lists.
- Support Nesting Block Elements in List Items. Ensure that nesting code resources works.
- Confirm ids work on definition list items.
- Add section directives to Leanpub, and convert the frontmatter and mainmatter directives in this spec to Markua section directives once supported in Leanpub.
- Ensure that the toc directive is used to position the Table of Contents, so that people can add things like endorsement pages in advance of it, etc.
- Support tables in external files.
- Support poetry in external files and poetry resources in general.
- Support updates to en dashes, em dashes, scene breaks and page breaks.
- Support parentheses in numbered lists
- Remove HTML comment syntax, since the CriticMarkup comment syntax is enough.
- Support question alternates (?1, ?1).
- Support the other directives.
- Support cite and url on blockquotes.
- Use table-of-contents not toc.
- Support exercise-answers and quiz-answers.
- Auto-create images, audio, video, code, math and tables directories in resources directory.
- Support cite and url attributes on images.
- Vary the code format default based on delimiter.
- Tables seem to mess up the alignment of some text after them.
- The kerning on figure captions is a disaster. It looks like one word!
- Support crosslinks on spans
- Our definition lists sometimes don’t force newlines after the term, e.g. “type This is the resource type…” - SVG support
- Support External and local tables, tables as resources in general
- Be stricter about headers (#foo should not start a chapter, blank lines before and after, etc)
- Support inline resources
- Support type attribute on resources
- Support image attributes fullbleed, height, cite, url
- Decide what we are doing with the cite and url attributes
- Specifically forbid local video resources
- Support video attributes embed, fullbleed, float, height, width
- Support dashed attributes for code resources line-numbers, number-from, crop-start, crop-end
- Support three-tildes defaults to text, backticks default to guess approach
- Support inline math with format attribute
- Support table widths attributes on columns
- Support - for lists
- Support tab instead of space for lists
- Support descending lists
- Support specs for all of the list types
- Support multi-paragraph lists and whitespace
- Support max list-nesting in Markua of three levels
- Support scene breaks and page-breaks
- Support blockquotes inside of a paragraph
- Support cite and url attributes for blockquotes
- Support the quiz or exercise chapter heading being considered the name of the quiz or exercise.
- Does this quiz or exercise heading show up in the ToC?
- Support ids and other attributes on span elements
- Support smart crosslinks
- Support Emoji
- Support CriticMarkup.
- Support index entries and index generation.
- Support language directives
- Support Section directives
- Finish Leanpub for Courses
- Support conditional inclusion targets for books and courses: book, sample, instructor, course, course-sample and course-instructor
- Support {answer} blocks in quizzes
- Only support Sample.txt in LFM books, not Markua books
- Investigate regression of formatting in caption attributes of figures; should support text formatting

Acknowledgments

I (Peter Armstrong) am the creator of Markua, but I’m getting lots of help, especially from my Leanpub cofounders Scott Patten, Len Epp and Braden Simpson.

First, a huge thanks to Scott Patten. Scott is the lead developer of Leanpub’s book generation engine. Leanpub Flavoured Markdown would not have existed without Scott’s code. Furthermore, Scott provided lots of valuable feedback in the development of the Markua specification, as well as adding Markua support to Leanpub’s book generation engine. Scott gave me opinionated feedback on the Markua syntax, just as Aaron Swartz gave John Gruber feedback on the Markdown syntax. In many instances, e.g. the poetry syntax, what happens is that I come up with an idea which is good but flawed, Scott points the flaws out and suggests an alternative which often feels like giving into the status quo or feels too much like programming, I get really mad, and then I come up with something better than I would have otherwise. So, Markua probably also wouldn’t exist if I couldn’t–repeatedly and productively–get mad at Scott. (This sums up much of Leanpub’s development, actually!)

Second, I’d like to thank Len Epp. Len has been instrumental in the development of Leanpub. He joined in the very early days, and has greatly helped our customer development process, helping (as he likes to tease me) grow Leanpub over 100x before Scott and I made him a co-founder. Besides giving the Markua spec a thorough copy edit, he has been a strong advocate for the way a non-programmer thinks about writing. For example, Len got me to change my mind about the three-or-more newline handling case–so, if you enjoy using extra newlines, you have Len to thank!

Third, I’d like to thank Braden Simpson. Braden has been instrumental in the development of the open source ES6 Markua parser, as well as the open source MarkuaPad editor and its usage in Leanpub. Braden has also been key in developing the test suite for Markua, and along with Scott has given me great feedback on crucial design decisions such as the image syntax.

I’d like to thank my father, who has read the manuscript and given me feedback more than once. This was a horrible slog when the spec included a partial HTML mapping!

I’d also like to thank Assaf Arkin, Alberto De Lucca, André Bacci, Ann Chia-hui Tai, Axel Rauschmayer, Dave Warnock, Iva Cheung, Jacob Evelyn, Joseph Harfouch, Justin Damer, Ken Pratt, Matt Fikowski and Michael Müller.

Perhaps most important, Markua is benefiting from years of feedback about Leanpub Flavoured Markdown from many Leanpub authors. If it wasn’t for these authors, there would be no Markua.

Finally, I would like to thank my wife Caroline and my son Evan: while this is not as long as my other books, a lot of thought and effort went into it, and a lot of sacrifice. Thanks very much.

Notes

Quizzes and Exercises

1That’s a forward-looking statement–Leanpub for Courses is currently in private beta!