# 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.

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__*.

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.

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.

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.
6. Tabs cannot be used to separate the pound signs and the heading text. Despite the increased conceptual consistency with list formatting, this would make Markua documents ugly and less consistent. The tradeoff is not worth it.

## 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.

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.

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:

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.

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:

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

# 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:

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:

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.

Finally, if any resource is missing during book generation, a Markua processor can either fail to generate the book or can insert something like the “missing image” often seen on web pages into the book. This behaviour is up to the implementor of the Markua processor, and could even be something which is configurable by the author. (In general, a Markua Processor should error if the author is trying to do something unsupported, and should recover if the author is trying to do something which is supported, but in an erroneous way.)

## 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:

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

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:

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. If no caption is provided but a title is provided, then the title should be used as the caption: it does not make sense to refer to a figure with a title, but for the figure itself to have no caption.
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:

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:

#### 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:

#### 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:

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

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:

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

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.

Note that inside a code span, whitespace must be preserved by a Markua Processor. The reasoning here is simple: in source code, whitespace matters, so it must not get collapsed into a single space. Thankfully, this is easy to do. If a Markua Processor is producing HTML, the following CSS prevents spaces from being collapsed to one space:

(There may be other CSS in future which meets this requirement, so this exact CSS is not a requirement for a Markua Processor to use. However, the behaviour that results when this CSS is added is a requirement for a Markua Processor.)

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:

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:

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:

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 should be 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 should be referenced as ![](images/bar.png)–not as ![](/images/bar.png) or ![](/resources/images/bar.png).

Note, however, that a Markua processor must ignore the part of a path which starts with resources/. So, you can also do the following:

• A file called foo.jpg in the resources directory can be referenced as ![](resources/foo.jpg).
• A file called bar.png in a subdirectory images of the resources directory can be referenced as ![](resources/images/bar.png).

The reason for this is that there are, and always will be, more Markdown-aware tools in the world than Markua-aware tools. So, supporting relative paths is a must, and a relative path does include the resources/ part of that path.

Nested directory trees work as well. A file called foo.rb in a ch1/examples/ruby directory tree inside the resources directory is referenced as ![](ch1/examples/ruby/foo.rb).

Again, you cannot navigate upward in paths with ../: this would be a security hole, so it must be forbidden by a Markua Processor.

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 align or 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:

align
The align can be left, right or middle. The default is middle. Combined with width and height, this provides basic image formatting. When align is specified, text goes above and below the image, but the image and its surrounding whitespace occupies the entire width of the page. In terms of the specific values of align, a Markua Processor must interpret left as “on the left side of the page”, right as “on the right side of the page” and middle as “in the middle of the content area of the page, respecting margins” in all cases. Finally, note that inside and outside are not supported for align. If you are using those attributes, chances are you should be floating the text around the image by using the float attribute, not the align attribute.
alt
The alt is the alt text, to be displayed when the image cannot be shown. This is provided in the figure attribute list.
cite
An image can have a citation. A Markua Processor is free to combine this citation with the caption attribute or display it separately.
float
The float can be left, right, inside or outside. The left and right attribute values mean the same thing as they do with align. When float is specified, text flows around the image. It is an error to specify both align and float. Note that middle is not supported for float, since Markua is not a good choice for the types of advanced layouts which flow text on both sides of an image. For that, you should use something like InDesign; this is why Markua Processors such as Leanpub can export InDesign files. Also, note that float supports inside or outside, but align does not. What a Markua Processor does with inside and outside is more complex. A Markua Processor must interpret inside as “near the spine” and outside as “away from the spine” in a print book. In an ebook, however, a Markua Processor has some flexibility in terms of the meaning of inside and outside: it can either interpret inside as “left” or it can interpret inside as “left if the language is left-to-right, and right if the language is right-to-left”. Similarly, a Markua Processor can either interpret outside as “right” or it can interpret outside as “right if the language is left-to-right, and left if the language is right-to-left”. If that makes your head hurt, just use left and right instead.
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 align 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 followed by a percentage sign (%). The quotes are optional. So, you can say {height: "70%"} or {height: 70%}.
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 followed by a percentage sign (%). The quotes are optional. So, you can say {width: "70%"} or {width: 70%}.

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:

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:

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:

#### Inline Images (SVG only)

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

### 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, fullbleed, height and width attributes apply to the poster image for the video–not to the video itself during playback.

align
The align can be left, right or middle. This applies to the poster image for the video, and works just like it does with images.
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, inside or outside. This applies to the poster image for the video, and works just like it does with images. It is an error to specify both align and float.
fullbleed
true or false. The default is false. This applies to the poster image for the video, and works just like it does with images.
height
This applies to the poster image for the video, and works just like it does with images.
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.
poster-format
The format of the poster image, if it exists. If this attribute is not specified, the format of the poster is inferred from the poster image file extension. This attribute needs to exist only to support poster images which do not have file extensions.
transcript
The URL or path to a transcript of the video, which should be shown or dictated to people who cannot view video. This helps people with visual disabilities view course material, and helps with ADA compliance. For example, what Leanpub does with a transcript is as follows: a URL is linked to in the caption (but in a way which does not affect the Table of Contents), and a path is assumed to be a path to a Markua file which is then used to produce a web page at a public URL, which then is also linked to in the caption in a way which does not affect the Table of Contents. With the Markua files for transcripts, Leanpub only supports certain resource types to be included in the transcript files themselves. Specifically, images, video, audio are not supported, but code, poetry, math and tables are supported. When Leanpub generates a transcript, the URLs are publicly accessible but obscure. Identical transcripts should not make duplicate transcript files on the web, and using a new UUID every time would violate this. However, not changing the transcript URL when its content changed could lead to bad outcomes. So, the URL of a transcript on the web should be scoped to the book and affected both by its filename and its content. What Leanpub does is: (filename minus extension minus period plus hyphen plus the SHA hash).html. Including the filename eliminates collisions if filenames are unique but the hashes are not.
width
This applies to the poster image for the video, and works just like it does with images.

#### Web Video

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

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

transcript
The URL or path to a transcript of the audio, which should be shown to people who cannot hear audio. This helps people with auditory disabilities view course material, and helps with ADA compliance. Transcripts should be produced and handled in an identical way to video resources. For example, Leanpub does this. See the Video resource section above for more information.

### 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.

However, while a complete set of the values of the format attribute is not specified, Markua does specify the console value of the format attribute to indicate console input. A Markua Processor should format console input as such. (For example, Leanpub uses the open source Pygments library for its code formatting, and Pygments handles console format correctly, so Leanpub gets this for free.)

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”.

Finally, note that there is a default-code-language setting on the entire Markua document. The value of this setting only affects local resources, web resources or inline resources inserted with backticks–it has no effect on inline resources inserted with tildes. The default language for inline resources delimited by three tildes is always text.

#### 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:

That is equivalent to:

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

Note that the caption is optional in all figures:

#### 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:

That is equivalent to:

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

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:

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:

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:

That is equivalent to:

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

This Ruby code may be formatted as such if the Markua Processor understands ruby. If not, the ruby format will be ignored.

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

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

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:

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

Finally, as discussed previously, console input and output should be formatted as such by a Markua Processor:

#### 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.

#### 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.

#### 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:

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:

### 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.

#### 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.

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:

The $ character indicates the inline resource is LaTeX math. Here’s an example of LaTeX math inserted as a span: If you don’t like syntactic sugar, you can also do a lot of typing to insert math as LaTeX math: Or, if you really like typing, you can insert MathML as an inline resource inserted as a span: 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:

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

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

### 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:

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

The following are the principles of Markua tables:

1. Formatting never applies to anything above it.
2. Use the fewest formatting characters possible.
3. Use the fewest attributes possible.

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

You don’t need type: table when the table is defined inline, of course, since it’s clear.

 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…

A header row and three body rows:

Just body rows:

No footer:

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

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

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

Finally, headers and footers can have multiple rows in them. This won’t be used that frequently, but it is fully supported:

You may initially think that typing row separators would be annoying. 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.

#### Table Column Alignment

You can also specify the left, center and right alignment of columns. This can be done separately for the header, for the body, and for the footer. Also, any individual table cell–except the first one in the header, body or footer–can override the column alignment of the header, body, and footer.

This is in keeping with the principles that formatting never applies to anything above it, and to use the fewest formatting characters possible.

The exact rules will be specified shortly, but it helps to start with a few examples.

By default, all cells in the table header, body and footer are left-aligned.

So, the following table has left-aligned headers, but its body columns are left-, center-, and right-aligned respectively:

You can use different alignments for the header and the body of the table.

This table is just like the previous one, but it has left-aligned (Header A), centered (Header B) and right-aligned (Header C) header columns, with right-aligned, left-aligned and then centered body columns.

You can also override the alignment of an individual cell. This table is just like the previous one, but its Body B2 cell is overridden to be centered not left-aligned:

Formatting a separator row (====) cascades downward. Header alignent cascades into the body and footer; body alignment cascades into the footer.

However, individual cell separater row (----) footing does NOT cascade downward. It overrides an individual cell only; it does not change the column alignment going forward. In the above table, Body B3 is left-aligned (like its body column) not centered (like Body B2).

This has the following consequence:

The cells in the first row of a table header, table body or table footer must have the same alignment as the header, body or footer column they are in. They are used to define the alignment, not override it. If you need other cells in the table header, body or footer to have different alignments, those must do the overriding.

So, if you want every other cell in a column to have a different alignment than the first non-header cell in that column, each of them must have the overridden alignment. This would not be true if alignment overrides cascaded downward, but that would confuse a lot more people than helping this small edge case.

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

You can override alignments anywhere.

The following table has left-aligned (A), centered (B) and right-aligned (C) header and footer columns, with right-aligned (A), left-aligned (B) and then centered (C) body columns–and it also overrides Header B2 to be right-aligned, Body A2 to be centered and Footer C2 to be left-aligned:

However, just because you can, doesn’t mean that you should.

#### Multiple-line rows, row spans and column spans

 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:
 You can specify a column span just by skipping a | in the appropriate place:

Note that the alignment of the cell in the merged columns is that of its leftmost column, if no override is done. So, in the above table, Body A1 and B1 Merged is left-aligned not centered.

Now, if you want to override the alignment on a merged cell, you do that in the leftmost cell. So, in the below table, Body A2 and B2 Merged is centered not left-aligned.

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

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:

In that table, column A is left-aligned, column B is centered and column C is right-aligned. However, cell A2 is right-aligned, cell A3 is centered 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:

column-widths
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. Examples: {column-widths: "10,30,*,10"}, {column-widths: "10,*,40,*"}. If the sums exceed 100 (ignoring the *s), the Markua Processor must raise an error. Every specified value must be at least 1, and every * must compute to at least 1, or the Markua Processor must raise an error.
style
The style of the table. Values can be simple, grid or any other value. All Markua Processors must support values of simple and grid for tables. The default is simple. A Markua Processor may use whatever formatting it wants with simple, but it should be clear which cells are part of the table header, body and footer. A Markua Processor may also use whatever formatting it wants with grid, but it must show grid lines around each table cell. If a Markua Processor does not recognize the value of the style, it must format it as simple instead of producing an error. (It can, however, produce a warning.)
width
The width of the table, in percentage of page content area width (respecting margins). This is specified as an integer between 1 and 100 followed by a percentage sign (%). The quotes are optional. So, you can say {width: "70%"} or {width: 70%}.

A Markua Processor may do whatever it wants when outputting a table. For example, 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.

#### A Markua Processor May Optionally Support The GitHub Flavored Markdown Table Syntax

The Markua specification only defines one table syntax. Tables are complex enough without other table syntaxes cluttering things up.

However, if a Markua Processor understands the GitHub Flavored Markdown table syntax, which is based on the syntax originally specified by PHP Markdown Extra, then it may support it as well.

There are many Markdown documents in the world which use the GitHub Flavored Markdown table syntax, and implementors of Markua Processors may wish to support them.

There is no requirement for a Markua Processor to support any table syntax except that defined by the Markua specification, however.

Also, another good reason to support the GitHub Flavored Markdown table syntax is that the Markua table syntax is more complex than the GitHub Flavored Markdown table syntax. 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.

Since Markua tables support increased complexity, there were three choices for how to handle the simple cases:

a) Define a separate “simple” table syntax as part of the Markua spec. This would be similar to the simple versus complex lists.
b) Just use the same Markua table syntax for every type of table.
c) Allow alternate table syntaxes to be supported by Markua processors.

Frankly, there is no perfect decision here. Choice (a) may be the best solution; choice (b) is the simplest and most opinionated; choice (c) is the most pragmatic. In this case, pragmatism wins: it’s arguably better to just optionally support the GitHub Flavored Markdown table syntax verbatim than for Markua to define a “simple” table syntax which is incompatible with it.

# 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. You should be able to look at a Markua document and know what is produced. Invisible formatting is frowned upon.
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 blank lines after the first blank line are ignored when separating paragraphs, and all consecutive blank lines after the second blank line are ignored when separating lists.
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:

### 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:

### 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 Only to Determine List Containment, and Extra Spaces are Removed

Spaces and tabs at the beginning of a line are only used to determine whether the content is contained in a list item–or, in the case of a nested list, which list the list item is contained in.

Besides this, in a paragraph, any manual indentation (using spaces or tabs at the beginning of a line) is just removed. This is even true after a forced line break, using a single newline.

So, if you’re writing a sonnet, you can’t manually indent the last two lines just by hitting Enter and adding two spaces at the beginning of the line. Instead, you need to use a poetry resource. To do this, you 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 two types of lists, bulleted lists and numbered lists, which can be formatted as either simple or complex lists.

The basics of bulleted and numbered lists are discussed first. This is followed by a discussion of simple and complex lists, which will contain examples of both.

Note that 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 one space, followed by text content. You can’t mix and match asterisks and hyphens in the same list.

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

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

Markua could have supported just one of the asterisk or the hyphen, but this would have been too prescriptive.

To make a bulleted list in Markua:

• Start each list item with either an asterisk (*) or a hyphen (-).
• You can’t mix and match asterisks and hyphens in the same list.
• Only one space is allowed after each bullet. Just as with headings, there is no reason to support any other number of spaces, and the increased consistency is a benefit.
• 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.

## 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 same number that begins the list in the output.

To make a numbered list in Markua:

• Start two or more consecutive lines with either a consecutive (e.g. 1., 2., 3.) or the first (e.g. 1., 1., 1.) number, letter or Roman numeral, each followed by either a period or right parenthesis, then exactly one space, then text content.
• 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. These are discussed later.
• You need to follow the period or parenthesis with exactly one space. Markua very deliberately does not allow more than one space following the period or right-parenthesis: if your list grows to 10 or more items, you should not waste time adding a space to items 1-9 to line their content up with item 10; similarly, if your list grows to 100 or more items you should not waste time adding yet another space to items 1-99 to line their content up with item 100. So, Markua just forbids more than one space after the period or parenthesis. Besides the time saved, the increased consistency is a benefit.

Note that a Markua Processor must output the same number, letter or Roman numeral which is in the manuscript. A Markua Processor may choose to respect the parentheses versus period decision, or it may choose to use all periods or all parentheses, or it may choose to use parentheses in, say, PDF, but use periods in, say, HTML, EPUB and MOBI. There is no formal, official mapping of Markua to any output format, to encourage competition and dynamic ecosystem of Markua Processors.

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.

You can build a numbered list out of ascending decimal numbers starting from 1:

You can build a numbered list out of ascending decimal numbers starting from 1, with parentheses used instead of periods:

You can build a numbered list out of ascending decimal numbers followed by periods starting from a higher number:

You can build a numbered list out of ascending decimal numbers followed by parentheses starting from a higher number:

You can build a numbered list out of descending decimal numbers:

You can build a numbered list out of identical decimal numbers, if you are lazy (producing 1, 2, 3):

You can build a numbered list out of ascending lowercase letters:

You can build a numbered list out of ascending lowercase letters, with parentheses used instead of periods:

You can build a numbered list out of ascending uppercase letters:

You can build a numbered list out of ascending uppercase Roman numerals:

You can build a numbered list out of ascending lowercase Roman numerals:

### In Markua, There Are No Single-Element Numbered Lists

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.

In Markdown, this would produce the following single-element numbered list:

1. What a great season.

In my opinion, is a blatant violation of the Principle of Least Surprise. (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.)

Now, if Markua supported single-element numbered lists, this would produce a single-element numbered list:

1986. What a great season.

This wouldn’t be as bad as what Markdown does, but it wouldn’t be good either! Exactly how stupid it would look would be determined by how numbered lists were formatted by the Markua Processor, but it certainly would look wrong.

But what to do?

In Markua, there are no single-element numbered lists.

If you try to make one, it just turns into a paragraph.

This is true for numbered lists only–single-element bulleted lists are lists. (It’s stupid, but the alternative would have been stupider.)

So, in Markua, the automatic creation of a numbered list only happens if you have two or more lines starting with consecutive or identical numbers, letters or Roman numerals, followed by a period or right parenthesis, followed by a space, followed by text content.

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 would feel more like programming than writing.

### Numbered List Numbering Rules

This section is highly technical, and can be skipped or quickly skimmed by almost all authors. It’s probably only interesting to someone writing a Markua Processor.

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 forced line break 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.

## Simple Lists

Both bulleted and numbered lists can either be simple lists or complex lists. Whereas the distinction between bulleted and numbered lists was based on the list delimiter, simple and complex lists are distinguished by the indentation and newlines.

Yes, this distinction essentially comes down to the ancient computer science debate of tabs versus spaces.

A simple list uses one tab per nested indentation level.

If you use spaces for indentation, what you are creating is a complex list, which is discussed next.

Besides the formatting rules for bulleted or numbered lists, the rules for a simple list are:

• There are no newlines in list items. Each list item in a simple list is one paragraph with no forced line breaks or blank lines.
• You cannot insert resources with attribute lists in list items. These are inserted after forced line breaks or blank lines, both of which require newlines, and there are no newlines in list items of simple lists.
• There is a maximum of four levels of nesting of lists, including the outermost list. (So, you can have three levels of nested lists under each outermost list item.)
• If you try to nest a fifth level of nesting (or more), the Markua Processor must raise an error.
• The first indentation level is no indentation: it is at the left margin.
• You must use exactly one tab per nested indentation level. (So, the number of tabs you can have is 0, 1, 2 or 3.)
• You cannot use spaces to indent list items.

This is an example of a simple list which has the maximum number (four) of levels of nested list:

## Flat Lists

The examples of bulleted and numbered lists in the Bulleted Lists and Numbered Lists sections above were flat lists, which did not contain any indentation.

Every item in a flat list is at the outermost level, and there are no newlines in list items. A flat list is a special case, in that it conforms to all the rules for both a simple list and a complex list.

A flat list is so simple that it is not just a simple list, it’s also a complex list. Whoa.

## Complex Lists

Whereas simple lists use tabs for indentation and cannot have newlines within list items, a complex list uses spaces for indentation levels and can have newlines within list items.

Using spaces allows for a lot more complex formatting of list items which is still understandable, including lining up nested resources and multiple-paragraph list items. So, these are called complex lists not “spaces lists”, since the distinguishing feature is the complexity supported by the spaces, not the spaces themselves.

Besides the formatting rules for bulleted or numbered lists, the rules for a complex list are:

• Each list item in a complex list can be one or more paragraphs, and each paragraph can contain forced line breaks. Specifically, there can be forced line breaks (formed by single newlines) and blank lines (formed by exactly two consecutive newlines) in list items.
• You can insert resources with attribute lists in list items. These are inserted after forced line breaks or blank lines.
• After any forced line break or blank line, the content must be lined up with the content in the above line using the appropriate number of spaces (not tabs). This is slightly more annoying to type than if there were no indentation requirements, but it is a lot more pleasant for you to read later.
• There is a maximum of four levels of nesting of lists, including the outermost list. So, you can have three levels of nested lists under each outermost list item.
• If you try to nest a fifth level of nesting (or more), the Markua Processor must raise an error.
• The first indentation level is no indentation: it is at the left margin.
• You must use spaces to line up the content after newlines in a list item with the start of the content in the first line of the list item. So, the amount of indentation inside a list item is actually not arbitrary; it is completely determined by how many spaces you need to line up with the content in the first line of the list item. For a bulleted list this will always be 2 spaces (1 for the * or -, followed by 1 for the space); for a numbered list this will always be at least 3 spaces (1 or more for the number/letter/Roman numeral, 1 for the . or ), and 1 for the space).
• You cannot use tabs to indent list items or line up content in list items.

As discussed, if you attempt to nest more than four levels of nesting, the Markua Processor must raise an error. However, if you violate the indentation rules or newline rules of both simple lists and complex lists, the Markua Processor must just interpret your list as normal non-list content, such as a paragraph with line breaks. The reason for this is simple: every block element which is not a list violates the rules for lists–otherwise it would be a list! So, the only “this is not a list” property which actually causes an error is an attempt to add more that four levels of nesting to a simple or complex list. Any other mistake just results in the list being not a list, in order to be more permissive about how Markua documents can be formatted.

You can do everything with a complex list that you can do with a simple list. This is a complex list which is the equivalent of the nested list above:

However, you can do a lot more with a complex list as well.

You can add optional blank lines between some or all of the nested lists, just for readability:

You can make multiple paragraph list items using blank lines, and add forced line breaks using single newlines:

Note that the amount of space to indent is determined by the content, and that is determined by the width of the number:

This is a numbered list which contains five list items. It includes an inline code resource, a local code resource, and multiple-line list items:

This is a bulleted list with the same complexity:

Neither the numbered or bulleted list above had multiple paragraphs in it, just forced line breaks. This is what those lists look like with multiple paragraphs instead…

This is the numbered list version:

This is the bulleted list version:

To reiterate, single blank lines (two newlines) make paragraphs, and forced line breaks (single newlines) stay in the same paragraph.

### Blank Lines in Complex Lists

#### Single Blank Lines Within Complex List Items

It is legal to add single blank lines in between list items, to separate the list item into multiple paragraphs.

If there is a blank line within a list item, there must also be a blank line at the end of the list item.

The reason for this is simple: since paragraphs are separated by blank lines, and since lists support multiple-paragraph list items, you need to add a blank line at the end of a multiple-paragraph list item for symmetry. Otherwise, you can write something ugly like this:

The above example is so ugly it’s not a legal Markua complex list, and instead must be interpreted as paragraphs.

The correct way to write it is:

#### Two Consecutive Blank Lines End A Complex List

Whereas one blank line can be used in between list items for spacing or between other list item content to separate it into paragraphs, two blank lines always end a list and start a new block element, such as a paragraph or a new list.

There is no reason to be able to add two blank lines in between list items. However, there are reasons to wish to have two lists in a row in a Markua document. So, two blank lines in between two list items stops the previous list and starts a new list. There is no need to use some kind of garbage syntax to separate lists–just add an extra blank line.

Note, however, that two blank lines between single-element numbered lists would actually not produce two numbered lists since, again, in Markua single-element numbered lists are not lists.

This all sounds a bit complex, but it actually results in behaviour which is as unsurprising as possible to the author, and a lot less surprising than standard Markdown. This is shown by the following examples…

This is one flat list, which is both as simple list and a complex list:

This is one list. Since there are blank lines, it’s a complex list:

These are two flat lists. Again, flat lists are both simple lists and complex lists:

These are two complex lists:

These are two flat lists. The first is a one-element list; the second is a three-element list:

These are also two flat lists. The first is a one-element list; the second is a three-element list:

These are two flat lists:

These are two complex lists:

This is a normal paragraph followed by a flat list, since single-element numbered lists are not lists. This example shows the correctness of this decision:

This is also a normal paragraph followed by a flat list, since, again, single-element numbered lists are not lists. This highly-contrived example will confuse anyone reading your manuscript:

This is also a normal paragraph followed by a complex list, but this more-contrived example would confuse anyone reading your manuscript:

Again, this is also a normal paragraph followed by a complex list, but this even-more-contrived example would confuse anyone reading your manuscript:

### Parsing of Inline Code Resources Inside List Items

When inserting a code resource as an inline resource in a list item, it must be indented to line up with the list item content it is a sibling of.

For example, in the following list, the inline code blocks are indented by three spaces:

When the code itself is output, the number of spaces that the list was indented by must be subtracted from the output by the Markua Processor.

So, when this list is output, in the first example, puts "hello" and public class Hello { would both start with no indentation, while the  public static void main(String[] args) { line would be output with 4 spaces of indentation, not 7.

# Definition Lists

Definition lists are also supported in Markua. Definition lists are related to lists, but they are neither flat, simple nor complex. Instead, they are what they are: definition lists.

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

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

A definition list can provide multiple definitions for a term:

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

Finally, like list items in complex lists, 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:

You can nest resources inside a definition list. You cannot nest definition lists inside definition list items, however–that would be highly confusing.

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.

With the rise of mobile and the narrower screen reading experience becoming the new default, definition lists may end up being more useful than tables in many Markua documents.

Finally, with definition lists, one thing you often want to do is link to a specific definition, not just to the list itself. This is useful to do, since in a document with many definitions, it’s helpful if the reader scrolls to the right spot or opens to the right page.

To do this, just define an id on the element itself, and then link to it. Note that the first attribute list is actually for the definition list itself, and the remaining ones are for the items. So, you can’t add an attribute list to the first element of a definition list which applies just to it. (TODO - Note to Leanpub authors: id attributes on definition list items do not work yet.)

A Markua Processor

# 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:

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:

## Blockquotes (>)

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

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:

These Markua blockquotes are nested in the 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.

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:

## 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:

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

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

## 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:

### Supported Attributes for Blurbs

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

#### Blurb class Types

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

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

These blurb types can be set on a blurb as its class attribute. 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:

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

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

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

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

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

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

Examples:

These are equivalent to:

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

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

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

Also note that nothing in this section defines what 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.

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

A Markua Processor is free to either override this silently, or to raise an error if this happens.

### Using Blurbs to Center Text with C>

You can also use a blurb to center text.

The following two ways to do this are equivalent:

This is the only way to center text in Markua.

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

### Using Extension Attributes on Blurbs to add icon Support

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:

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 example shows a figure which is an inline code resource nested in the middle of a paragraph:

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

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):

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 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.

There is only one syntax to create a quiz or exercise. For a quiz, it’s by wrapping the quiz in {quiz}{/quiz}; for an exercise, it’s by wrapping the exercise in {exercise}{/exercise}.

Here is a brief example of a 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.

With a quiz, the id attribute is required. This is so the identity of a quiz can be preserved across generations of a course.

Here is the same example, but as an exercise:

Just like with quiz, with an exercise the id attribute is required. This is so the identity of an exercise can be preserved across generations of a course.

## 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 any type of heading immediately after the {quiz} or {exercise} line, 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. Typically the heading will be a chapter heading (# ), but section headings (## ) and lower headings also are supported. (The reason for this is that quizzes are sometimes top-level things, and other times are nested inside chapters, sections or sub-sections. Some course authors would correctly feel that the quiz should have the appropriate level of heading given their position in the document.

Example:

## 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/or Exercises

attempts
The number of allowed attempts on a quiz. The default is defined by the value of default-quiz-attempts on the containing course, or 1 if this is not present. A value of 0 means the quiz cannot be taken (yet). A value of -1 means the quiz has an unlimited number of attempts. Since an exercise does not count toward the mark on a course, an exercise always has an unlimited number of attempts.
auto-submit
true or false. The default is true. If true, an incomplete quiz is submitted when the time-limit is expired. If false, it is not. Either way, an incomplete quiz counts as an attempt.
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.
id
All Markua elements support an id attribute. The reason the id attribute is explicitly listed here is to emphasize that a Markua Processor may require an id attribute on a quiz or exercise. For example, Leanpub requires the id attribute on all quizzes, in order to determine the identity of quizzes when a course is being published in-progress. (As a student, you’d be pretty unhappy if you had to re-take an unchanged quiz simply because a professor published a new course version.)
mark-request-url
If omitted, all the quiz or exercise answers are defined in the Markua document. If present, some or all of the quiz or exercise questions are externally marked via an API defined at the URL specified in this attribute. When the quiz or exercise is completed, the entire quiz or exercise should be sent to the endpoint at the mark-request-url. Here’s how this works in Leanpub; other Markua Processors should presumably do something similar. When a quiz or exercise with this attribute defined is completed, its state is set to “pending”. Leanpub then sends the quiz or exercise data as a JSON payload to the marking endpoint. This JSON contains the following attributes: mark-response-url (which defines where responses are sent), quiz_id, quiz_version, quiz_hash (an SHA hash, for an automated quiz versioning approach which does not rely on the course author updating a version attribute), quiz_results (an array of question data structures containing the question, the possible answers, the correct answer according to the Markua document, the answer provided by the student, and (if the question is markable) the mark determined automatically). The API endpoint should send results to the mark-response-url. (Even though exercises are not worth points in a course, they can be marked, for the benefit of the student. However, the expectation is that this attribute will be used primarily by quizzes.) The mark-response-url in the payload contains URL to respond to with the results of the marking the quiz or exercise. The format of the expected payload should be defined by the Markua Processor. For Leanpub this is a JSON payload containing the question ids and the marks for each question. The mark is a decimal number of points between 0 and the maximum number of points for the question, inclusive. The decimal supports two decimal places, so you can get 3.75 out of 4, for example. The mark response must include marks for all questions that are unmarked. It may also include marks for questions that Leanpub marked, and those will override Leanpub’s marks. Finally, note that even though exercises are not worth points in a course, they can be marked, for the benefit of the student. So, since they can be marked, they can also be externally-marked via a mark-request-url. However, the expectation is that this attribute will be used primarily by quizzes.
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.
show-answers
This can be all, incorrect or none. It affects how answers are shown after a quiz or exercise is completed, say in a MOOC. For exercises, the default value is determined by the value of the default-exercise-show-answers global setting, with all being the default value of that attribute. For quizzes, the default value is determined by the value of the default-quiz-show-answers global setting, with incorrect being the default value of that attribute. Global settings are discussed later.
time-limit
The time limit to finish the quiz, once started. The format is XdYhZm. For example, 3 days, 6 hours and 45 minutes is expressed as 3d6h45m; 7 days is expressed as 7d. The default is 7d.
use-result
best or latest. Whether the best result on the quiz is used, or the latest one. The default is the value of default-quiz-use-result on the course.
version
The version of the quiz. This does not replace the function of the id; it’s more for use in analytics by the instructor. The default is 1.

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 correct answer choice.

The correct answer choice is in capital letters before the parentheses; incorrect answer choices have lowercase letters before the parentheses.

Example:

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.

Unless a choose-answers attribute is used, 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.

A multiple choice question may also have a dynamic number of answer choices, including for the correct answer. This done with the special choose-answers attribute, shown and explained below.

The choose-answers attribute specifies how many answer choices should be shown. This includes one of the correct answers (indicated with C), all of the mandatory incorrect answers (indicated with m) and as many of the optional incorrect answers (indicated with o) as are needed.

So, in the above example, either 453 or 454 will be shown, along with the mandatory incorrect answer choices 451 (a literary joke) and 1000 (a kilogram, not a pound) and one of the optional incorrect answers (100, 150, 200, 250, 300 or 500).

When a choose-answers attribute is used, the question will always have random-choice-order.

The following are errors in a question where a choose-answers attribute is used:
- 0 correct (C) answers
- not enough mandatory (m) or optional (o) incorrect answers for the choose-answers
- if choose-answers is n, a number of mandatory (m) answers >= n
- if choose-answers is n and the number of mandatory (m) answers is n - 1, then any optional (o) incorrect answers existing
- answers starting with something other than C, m or o

#### Supported Attributes on Multiple Choice Questions

choose-answers
This is described above. If choose-answers is used, random-choice-order is forced to true.
points
The number of points the question is worth.
random-choice-order
true or false. The default is false, unless choose-answers is used. 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 ( \; ).)

Instead of alternating acceptable answer values with semicolons, the acceptable answer value can instead be exactly one regular expression (regex). A Markua Processor should interpret any answer which starts with a forward slash (/) and ends with a forward slash followed by some word characters (e.g. i) as being a regular expression. (This is exactly one regex, not n of them separated by semicolons, since regular expressions are powerful enough that all alternating of matches can be done within them.)

Support for regular expression marking of fill in the blank questions is optional. Also, the particular format of the regular expression is implementation-specific. For example, Leanpub uses Ruby regular expressions. Other Markua Processors could, for example, use Perl or JavaScript regular expressions.

Examples:

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 second 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:

#### 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 a written question if either the words, lines or pages attribute is specified, if there is no answer provided, or if an answer is provided using the {answer} syntax discussed shortly.

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:

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:

#### 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. A Markua Processor generating a MOOC may override this. For example, when generating a MOOC, Leanpub overrides all written questions to have a points attribute of 0, regardless of what (if anything) is specified for this attribute by the author.
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.

### Hints on Questions

Any question can contain a hint, regardless of question type or whether an answer is provided.

The hint starts on a line with a percent sign (%) followed by a single space. It must follow the question, but it can come either before or after the answer choices.

Hints can span multiple lines, if each line starts with a % sign. This is similar to Markdown handles block quotes with >.

The hint can be used by a Markua processor to show to students at appropriate times, such as when they get the answer wrong or leave it blank. The exact specifics are implementation-dependent. Hint support is optional in a Markua processor. However, if it’s not supported, it must be ignored.

The hint can be a useful feature for a Markua Processor. There is a lot of discretion here for Markua Processors to compete on features.

For example, here’s how Leanpub handles hints:

1. We will show the hint as a popup next to the question in the web and mobile quiz views.
2. We will track if the student looked at the hint.
3. We will not subtract points for looking at hints for Leanpub-marked questions.
4. Whether the hint was used will be provided in the analytics, such as a CSV download that we make available to professors.
5. We will also output the hints for exercises in the “material book” for a course, in a section near the end of the book. This will be linked to via crosslinks from each exercise.
6. The answers page for a quiz or exercise will show the question, hint and answers for each 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:

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 button[^fwdstmt] 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.

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).

Question alternates can also be grouped by a choose-questions attribute attached to the first question alternate. In this case, the Markua Processor must choose the number of questions m specified from the given alternates with that number n, or n choose m. Note that in this scenario, the numbering after the alternates increases by m: for example, if a quiz starts with a choose: 3, the next question is numbered 4, not 2. This ensures that the person constructing the quiz knows what they are doing, and saves them from having to keep track in a scenario where there are multiple questions with a choose-questions attribute.

A Markua Processor must treat any error in the numbering of question alternates (and the questions which follow) 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:

Example:

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.

Example:

## 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:

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:

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:

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

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:

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:

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}
2. Using a shorter “syntactic sugar” approach: {#some-id}

The shorter “syntactic sugar” approach is usually preferred. However, it can look a bit odd in an attribute list with other attributes in it. So, in that case, the {id: some-id} syntax is preferred.

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:

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

#### 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:

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

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

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:

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:

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:

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:

## 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.

## Code Spans and Backticks ()

You can create a code span by using pairs of 1, 2 or 3 backticks to surround a span of text within a paragaph, like this:

You cannot show a literal backtick in a normal code span, however, since you cannot backslash escape anything inside it. Inside a code span, a backslash is just a backslash.

So, if you want to output a backtick in a code span, you need to delimit the code span using two backticks:

## 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:

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:

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.
4. Output a “missing image” character, if it does not recognize the given emoji.

Because of this, Markua’s emoji support can also optionally be used by Markua Processors for a wide range of emoji. For example, a Markua Processor could output Font Awesome icons with an emoji syntax, such as :fa-leanpub: to output the Leanpub logo in Font Awesome. Since all Font Awesome icons have an fa- prefix, these are namespaced nicely.

## 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:

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

## 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 on Headings: book, sample, etc.

Markua headings (and only 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 eight attributes which specify conditional inclusion in output targets; four for books, and four for courses.

book
If true, include this heading and its content (including nested sections, subsections, etc.) in the book (PDF, EPUB and/or MOBI) 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.
web
If true, include this heading and its content (including nested sections, subsections, etc.) in the web version of the book that is being generated. If false, omit it. If book, then include it or exclude it based on the value of the book attribute. The default is book, meaning that if this attribute is omitted, every section which is included in the book is included in the web version of the 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. This attribute applies to both the book version (PDF, EPUB and/or MOBI) and the web version of 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. If book, then include it or exclude it based on the value of the book attribute. The default is book. Note that to make some content (like an answer key) appear in the instructor version of a book only, you need to do {instructor: true, book: false} not just {instructor: 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. If book, then include it or exclude it based on the value of the book attribute. The default is book. The reason there is a separate attribute is in case the same version of a manuscript is powering both a book and a course. Our recommendation is to use git branches instead of this approach, however, since that is usually more flexible.
course-web
If true, include this heading and its content (including nested sections, subsections, etc.) in the web version of the course that is being generated. If false, omit it. If web, then include it or exclude it based on the value of the web attribute. The default is web. The reason there is a separate attribute is in case the same version of a manuscript is powering both a book and a course. Our recommendation is to use git branches instead of this approach, however, since that is usually more flexible.
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. If sample, then include it or exclude it based on the value of the sample attribute. The default is sample. The reason there is a separate attribute is in case the same version of a manuscript is powering both a book and a course. Our recommendation is to use git branches instead of this approach, however, since that is usually more flexible.
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. If instructor, then include it or exclude it based on the value of the instructor attribute. The default is instructor. The reason there is a separate attribute is in case the same version of a manuscript is powering both a book and a course. Our recommendation is to use git branches instead of this approach, however, since that is usually more flexible.

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, and who don’t want to have to maintain separate git branches for a book and a course. Our assumption, however, is that most books or courses will require separate git branches, and that thus this approach merely saves some labour at the cost of some added complexity.

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:

To be clear: ALL conditional inclusion attributes ONLY have meaning when used as an attribute list on headings, i.e. the things that are defined with 1-6 # signs followed by a space, followed by text.

For example, you can only say {sample: true} immediately above a heading. You can’t have a blank line below it (otherwise it would be a directive, and not be valid) and you can’t attach it to anything other than a heading (like a paragraph, figure, etc.).

A Markua Processor must raise an error if it encounters a conditional inclusion attribute used incorrectly, so as to help the author understand how to properly use them.

### 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:

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:

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

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

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

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

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:

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.

If a Markua Processor also provides a UI to define settings which are specified here, the Markua Processor should respect the settings defined in the Markua manuscript over the settings defined in the UI. This can be phrased as “document wins”, not “database wins”.

authors
The authors of the Markua document.
contributors
Any contributors to the Markua document who are not authors.
copyright
default-code-language
The default language that code which is a local resource, web resource or inline resource inserted with backticks is interpreted as. The default value 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. Finally, note that the value of this setting only affects local resources, web resources or inline resources inserted with backticks–it has no effect on inline resources inserted with tildes. The default language for inline resources delimited by three tildes is always 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-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.
number-sections
true or false. Default false. Whether the sections (and sub-sections) are numbered.
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.
version
The version of the Markua document. This is primarily intended for use when producing analytics for courses. The default is 0.1.

### Settings for Courses

The following settings are defined by Markua, but only make sense in the context of a course. So, a Markua Processor which is not generating a course can ignore them.

course-attempts
The number of allowed attempts on the course itself. The default is 1.
course-completeness
How “done” the course itself is. Expressed as a percentage, in decimal value. The default is 0. A value of 100 or 100.0 is the maximum. A Markua Processor may do something smart when a course which is 100% complete changes the id values of a quiz or quizzes, since this will affect current students.
default-exercise-show-answers
This can be all (the default), incorrect or none. It affects how answers are shown after an exercise is completed, say in a MOOC.
default-quiz-attempts
The default number of allowed attempts on a quiz. The default is 1. Note that for quizzes, a value of 0 means the quiz cannot be taken (yet). A value of -1 means the quiz has an unlimited number of attempts. Setting either of these as the value of default-quiz-attempts is a legitimate value, and has the effect of changing the default value for all quizzes. Again, an exercise always has an unlimited number of attempts, so there is no corresponding default-exercise-attempts value.
default-quiz-auto-submit
true or false. The default is true. If true, an incomplete quiz is submitted when the time-limit is expired. If false, it is not. Either way, an incomplete quiz counts as an attempt.
default-quiz-show-answers
This can be all, incorrect (the default) or none. It affects how answers are shown after a quiz is completed, say in a MOOC.
default-quiz-use-result
best or latest. The default is best. Whether the best result on the quiz is used, or the latest one.
default-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.
default-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.

# 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:

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.

## 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, we had the C> syntax to center text, but we didn’t have the same effect on generic boxes, and blurbs did not exist. In Markua, a C> syntax is just syntactic sugar for a centered blurb, for greater consistency. Because of this, the blurb also gets the ability to be centered by adding a {class: center} attribute.
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.)

## 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:

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

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

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

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:

## 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.

## A Note For Leanpub Authors

If you’re reading this, you are a really, really early adopter of Markua.

Markua support is currently in an 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 7 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 and what doesn’t, 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.

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 a list of many of the parts of Markua which are still not supported in Leanpub:

- The {#some-id} syntax does not currently work when there are other attributes in the attribute list. So, in that case, you must currently use the {id: some-id} syntax if you are adding other attributes in a larger attribute list. You currently CANNOT add the {#some-id} to an attribute list. (This is also mentioned in the body of the spec. Once this works, remove it from both places.)
- Definition list id attributes on definition list items do not work yet.
- Quizzes and exercises: support show-answers, default-exercise-show-answers and default-quiz-show-answers
- 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 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!
- 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 align, cite, url
- Decide what we are doing with the cite and url attributes
- Specifically forbid local video resources
- Support video attributes embed, fullbleed, 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 Emoji
- Support Font Awesome in emoji syntax, such as :fa-leanpub:
- 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.