1.1The magical typewriter (M)

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, and EPUB for everywhere else. The book would look great on phones.

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

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

If you decided to make a print book, you could press a key on your magical typewriter to get a print-ready PDF. All you would need to do is add a cover.

If you wanted to work with a designer, you could press a different key to generate InDesign. They could then use this as a starting point for producing a beautiful print book.

Or, if you wanted to work with a publisher, you could press a different key to get a Word document.

Your magical typewriter could even transform your completed book manuscript into a course that anyone in the world could take. All you’d need to do is to add some quizzes and exercises and then press a key for your magical typewriter to publish an online course for you. The quizzes and exercises would mark themselves, and students would get certificates based on how well they did.

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, free, plain text format for a book or course manuscript.

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

This simple format is called Markua.

This is its specification.

1.2Markua: Markdown for books and courses (M)

Markua, pronounced “mar-coo-ah”, is Markdown for books and courses.

Markua maps Markdown syntax to book concepts, and then adds some new syntax and concepts of its own.

Markua documents can be automatically transformed into every 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 and HTML from the same Markua document, and can even output print-ready PDFs and InDesign files from them as well.

Markua has been developed with extensive real-world testing and feedback. Markua has been used by Leanpub authors for years, both to create books and online courses.

Markua was started at Leanpub in 2014, and benefited from the years of lessons that Leanpub had learned from Leanpub Flavoured Markdown (LFM). Markua is the successor to LFM. We have been iterating on our Markua support for many years.

1.3Markua’s five key additions to Markdown (M)

Markua’s five main additions to Markdown are the following:

1. The mapping of Markdown headings (h1, h2, h3, etc.) to book structures (chapters, sections, sub-sections, etc.), which provides the ability for Markua Processors like Leanpub to produce an ebook from a Markua manuscript with one click.
2. The unified resource syntax, which lets Markua handle audio, code, iframe, math, verbatim and video resources in the same way that it does images and tables, and which supports inline, local and web resource locations.
3. The attribute list syntax, which lets Markua define properties for resources using the same syntax that is used for other document elements, such as part headings and index entries.
4. A comprehensive definition of document settings, so that authors can use Markua to produce documents which are styled via global switches, rather than by tedious micromanagement.
5. The mapping of book structures to online courses, and the creation of a plain-text microformat for course quizzes and exercises, which supports automated marking and automated production of everything which is required for an online course.

If you have written something (say blog posts or lecture notes) in Markdown, you can use a Markua Processor, such as Leanpub, to turn them into an ebook or course with one click. Then, as you go down the path of enhancing the manuscript and adding things which only make sense in books or courses, this process will feel like decorating, not converting.

The goal is for writers who are familiar with Markdown to feel that with Markua, Markdown just grew an understanding of book and course concepts.

1.4Markua’s one key subtraction from Markdown: raw HTML is removed (M)

Markua also has one key subtraction from Markdown: support for raw HTML, either as inlines or blocks, is completely removed.

Markdown and CommonMark support raw HTML. Markua does not support raw HTML.

Instead, in Markua all raw HTML elements are removed.

This is true both for raw HTML which is inserted as leaf blocks, and raw HTML which is inserted as inlines. Neither of these are supported by Markua.

In both cases, raw HTML must be completely removed by the Markua Processor.

As a side effect of this, since HTML comments are HTML, authors can use HTML comments (<!-- a comment -->) as comments in Markua: since these comments are HTML, they will be completely removed from the output (along with any other raw HTML tags).

Markua and Markdown have different use cases. Markdown is a better way to write HTML; Markua is a better way to write a book or course.

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

Since Markdown’s only output format target is HTML, it might as well support HTML blocks: generating HTML from HTML is as simple as passing the HTML through. From an implementation perspective, Markdown gets inline HTML support for free. This is not true in the case of Markua.

Note that besides raw HTML, Markua does not remove anything else from Markdown. (As is discussed later, the Markua spec is written with the CommonMark spec as a starting point, so that you can verify this for yourself.)

1.5How to write a novel in Markua (M)

The Markua specification is long. However, if you’re an author, the amount you need to learn to write in Markua is actually very short.

This example shows everything you need to know to write a novel in Markua:

# Chapter One

This is a paragraph. You just write.

Blank lines separate paragraphs. This is *italic text*.

This is another paragraph. You can manually wrap your paragraphs
however you want. Single newlines function like single spaces by
default.

* * *

That was a thematic break, which is used as a "scene break" in a novel.

# Chapter Two

This is a paragraph in a new chapter.

By the way, everything in the above example is identical in the following Markdown dialects:

• Markua as specified in this document
• Leanpub Flavoured Markdown as described in the Leanpub Flavoured Markdown (LFM) Manual
• GitHub Flavored Markdown as specified in the GFM Spec
• CommonMark as specified by John MacFarlane in the CommonMark Spec
• Markdown as originally described by John Gruber

In the simple case, Markua is just a mapping from Markdown concepts to book concepts. This is deliberate.

1.6How to write almost any book in Markua (M)

The longer example below shows everything you need to know to write almost any type of book, such as a computer programming book, in Markua. This example also serves as a tutorial which explains most of Markua’s important syntax in its content. Some parts of this syntax are just standard Markdown or CommonMark syntax, and other parts are Markua extensions.

# Paragraphs

This is a paragraph. You just write.

Blank lines separate paragraphs. This is *italic text* and **this is bold**.

This is another paragraph. You can manually wrap your paragraphs
however you want. Single newlines function like single spaces by
default.

* * *

That was a thematic break, which is used as a "scene break" in a novel.

# Lists

Here's a numbered list (called an "ordered list", even though all lists are
ordered):

1. foo
2. bar
3. baz

Here's a bulleted list (called an "unordered list", for irony):

* foo
* bar
* baz

You can even have definition lists!

term 1
: definition 1a
: definition 1b

term 2
: definition 2

# Tables

You can also use tables, which work best for numeric tabular data
involving a small number of columns containing small numbers:

| Central Bank | Rate      |
|--------------|-----------|
| JPY          | -0.10%    |
| EUR          |  0.00%    |
| USD          |  0.00%    |
| CAD          |  0.25%    |

Note that definition lists are preferred to tables for most use cases,
since typing text in a table quickly gets annoying.

# Headings

Markua supports both of Markdown's heading styles.

The preferred style, called atx headers, has the following meaning in Markua:

```
{class: part}
# Part

This is a paragraph.

# Chapter

This is a paragraph.

## Section

This is a paragraph.

### Sub-section

This is a paragraph.

#### Sub-sub-section

This is a paragraph.

##### Sub-sub-sub-section

This is a paragraph.

###### Sub-sub-sub-sub-section

This is a paragraph.
```

Note the use of three backticks in the above example, to treat the Markua like
inline code (instead of actually like headers).

The other style of headers, called Setext headers, has the following headings:

```
{class: part}
Part
====

This is a paragraph.

Chapter
=======

This is a paragraph.

Section
-------

This is a paragraph.
```

Setext headers look nice, but only if you're only using chapters and sections.
If you want to add sub-sections (or lower), you'll be using atx headers for at
least some of your headers. My advice is to just use atx headers all the time.
(The `{class: part}` attribute list on a chapter header to make a part header
does actually work with Setext headers, but it's really ugly.)

Note that while it is confusing and ugly to mix and match using atx and Setext
headers for chapters and sections in the same document, you can do it. However,
please don't.

Finally, headers and their mapping to document structure concepts are discussed
later in the Document Structure section.

# Images

You can add images like this:

![](mac.jpg)

You can specify the alt text and figure title like this:

![alt text for accessibility](image.png "Figure Title")

An example of the difference between alt text and a figure title is:

![a red apple](mac.jpg "The Original Mac")

You can also set the alt text and/or the figure title in an attribute list:

{alt: "a red apple", title: "The Original Mac"}
![](mac.jpg)

Attribute lists are one of Markua's additions to Markdown, and are discussed
later in this specification.

Finally, you can set an image figure title using the alt text, if the
`alt-title` document setting is set to `all`:

![The Original Mac](mac.jpg)

The default value of `alt-title` is `all`, which means that all resources
can have their title specified in the alt text. There is also a value of
`text`, which means that only text-based resources like code can have their
title specified in the alt text. Finally, there is a value of `none`, which
means that no resources can have their title specified in the alt text. The
`alt-title` document setting is discussed
[in great detail here](#the-alt-title-document-setting-m-).

# Document Settings

Various document settings can be specified at the start of a Markua document to
affect the behavior of the Markua Processor. For example, if you want single
newlines to insert a forced line break in the PDF, EPUB and HTML output formats
(instead of the single space that results by default), set the `soft-breaks`
document setting to `break` instead of the default of `space`:

```
{
soft-breaks: break
}

# Chapter One

This will be on a line
and this will be on the next line.
```

This `soft-breaks` setting is so important it is discussed in its own
section below.

# Code Samples

The generalization of the Markdown image syntax into resources is one of
Markua's most important additions to Markdown. For example, the image syntax
is the inspiration for the syntax for external code samples:

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

Just like with images, you can also use an attribute list for the title:

{title: "Hello World in Ruby"}
![](hello.rb)

Note that you can also specify the figure title as the alt text, as long as
the document setting of `alt-title` is not set to `none`:

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

You can also have inline code samples, which can only have a title using an
attribute list:

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

You can also include single lines of code like `puts "hello"` in paragraphs
using backticks.

# Other Stuff

Note that you can easily add math `d = v_i t + \frac{1}{2} a t^2`$ as well,
either inline in a paragraph or as a figure, using LaTeX math as the format.

> Blockquotes are really easy too.
> --Peter Armstrong, *Markua Spec*

Markua has lots of features not discussed in this example. Read the manual or
the rest of the spec!

1.7For Leanpub authors (M)

There are three ways to write in plain text on Leanpub. These are their user manuals:

1. Leanpub Flavoured Markdown (LFM) - LFM was launched in 2011, and evolved until 2013. It is now obsolete, and is on long-term support.
2. Markua 0.10 - Markua 0.10 was launched in 2014, and evolved until 2021. It is currently the only way to write courses on Leanpub.
3. Markua 0.30 Beta - The Markua 0.30 beta was launched on Leanpub in 2021. Currently, Markua 0.30 is the default for new books on Leanpub. The user manual for Markua 0.30 is not yet stable, so for now you’re much better off reading this spec!

Not all features in the Markua spec are supported in the Markua 0.30 beta. However, the Markua 0.30 beta is good enough that it is the default choice for new Leanpub books!

You can still choose to use Leanpub’s Markua 0.10 support, of course. This is also true if you want to create courses. Leanpub’s Markua 0.30 implementation does not support courses yet.

You can also choose to use LFM, but unless you’re dealing with a legacy Leanpub book, there’s no good reason to do so. You’re much better off using the Markua 0.30 beta than LFM.

Markua 0.30 is compared to LFM and Markua 0.10 in the next sections below. These sections are primarily here for the benefit of Leanpub authors, but also to show the origin of how Markua 0.30 evolved.

1.8Markua 0.30 vs. Leanpub Flavoured Markdown (LFM) (M)

If you have used Leanpub Flavoured Markdown (LFM) in the past, you may be curious about the main differences between Markua 0.30 and LFM.

First, to emphasize the most obvious point: If you are writing a new book or course on Leanpub, you should absolutely choose Markua over LFM. For new books, you should choose Markua 0.30. For new courses, you should choose Markua 0.10 for now, since we do not support Markua 0.30 for courses yet.

There is no good reason to start any new project using LFM. The only reason we continue to support LFM on Leanpub is for updates to legacy books.

There are many differences between Markua 0.30 and LFM. This list highlights 10 of the more important ones…

1. In LFM, parts are created with -# Part. In Markua, parts are created with a {class: part} attribute list above an atx (# Foo) or Setext (using ===) chapter heading.
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. LFM 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. LFM 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 with the lang document setting and the {lang: ___} directive is sufficient.
8. LFM 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.)
9. LFM 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, or could just support parsing single files or input streams.)
10. Most importantly, a number of features (courses, index entries, smart crosslinks, etc.) exist in Markua and do not exist in LFM.

1.9Migrating a Leanpub Flavoured Markdown (LFM) Book to Markua 0.30 (M)

Migrating a Leanpub Flavoured Markdown (LFM) Book to Markua 0.30 is actually really easy.

Here are the steps you do:

1. Move the images folder inside a resources folder.
2. Convert the part syntax, if you use parts.
3. Generate the book, look at the output, and make any other changes needed.

These are all described below.

1.9.1Move the images folder inside a resources folder

In LFM, images live here:

manuscript/images/some_image.png

To convert this to Markua 0.30, the simplest thing to do is just move the images folder inside the resources folder:

manuscript/resources/images/some_image.png

This way, your image paths will be unchanged (as they will both start with images/).

1.9.2Convert the part syntax, if you use parts

In LFM, parts are defined like this:

-# Some Part Title

To convert this to Markua 0.30, you do this:

{class: part}
# Some Part Title

1.9.3Generate the book, look at the output, and make any other changes needed

The above list of changes are the main ones, but there are other differences between LFM and Markua 0.30.

However, at this point, the best thing to do is to just generate the book using Markua 0.30 instead of LFM, and see what is produced. Then, consult that list and the LFM manual to learn more about how to make any other changes needed to finish the migration.

One thing that Markua 0.30 defines which is not done in LFM is the concept of document settings, which are a set of global switches which customize the output of your book. You will want to review the standard document settings section below to learn more.

1.10Markua 0.30 vs. Markua 0.10 (M)

If you are writing a new book on Leanpub, you should absolutely choose Markua 0.30 over Markua 0.10.

If you are writing a new course on Leanpub, you’re stuck with Markua 0.10 for a while longer: our Markua 0.30 support don’t support courses yet.

Leanpub’s Markua 0.10 support is fully documented in its own user manual. Everything documented in that manual should work as described for Markua 0.10 books and courses, and our Markua 0.10 version will continue to be supported for years to come.

Leanpub’s Markua 0.10 support is based on a private fork of an open source Ruby library. It is not based on CommonMark or Pandoc. So, there are a number of quirks to our Markua 0.10 support. If you are using Markua 0.10 on Leanpub, consult the user manual, NOT this spec.

1.11Migrating a Markua 0.10 Book to Markua 0.30 (M)

When I defined how Markua 0.10 worked, I was a number of years younger than I am now. I cared less about compatibility with Markdown defaults, and more about trying to fix what I thought were mistakes.

This was youthful hubris, which Markua 0.30 corrects.

What Markua 0.30 does is functions like Markdown (minus inline HTML, and then extended) by default, but also provides the ability to override behavior using global document settings. These document settings allow you to customize the behavior of an entire Markua document via global switches. This way, the behavior of a Markua 0.30 document can be changed in sweeping ways via these global settings.

If you are updating a large Markua 0.10 document to Markua 0.30, you will probably want to start by doing these three steps:

1. Rename all caption attributes to title
2. Preview the book
3. Update any document settings

These are all described below.

1.11.1Rename all caption attributes to title

First, you will want to do a find-replace in your Markua manuscript to update all caption: attributes to be title:, since the caption attribute was renamed to title in Markua 0.30 for consistency.

Now, if you’re like most Leanpub authors who wrote in Markua 0.10, chances are you did not use any caption attributes, but instead relied on the alt-title behavior. The alt-title document setting is discussed in great detail here.

1.11.2Preview the book

Before making any more changes, you should preview your book to see what it looks like unchanged.

1.11.3Update any document settings

After previewing the book, you will want to review the PDF output and decide on the appropriate values of the document settings.

If you want maximum compatibility with Markua 0.10, you will want to override the soft-breaks and two-space-hack settings as follows:

1. Set the soft-breaks setting to break
2. Set the two-space-hack setting to false

Note that both of these settings are against the default behavior of Markdown, so unless you are already relying on that behaviour in Markua 0.10, you should consider leaving them at their default values.

You can change these settings on Leanpub in the Settings > Generation Settings section of the author app, or you can set the document settings at the top of the first manuscript file like this:

{
    soft-breaks: break
    two-space-hack: false
}

# Chapter One

Lorem ipsum dolor...

Make sure you add a blank line below the document settings, and also make sure you put the curly braces on lines by themselves!

Note that you only define this list of document settings once, at the start of your first file in your Markua manuscript.

Besides the specifics of the soft-breaks and the two-space-hack document settings, the big point is that regardless of whether you are upgrading a large Markua 0.10 document to Markua 0.30 or starting a new Markua 0.30 document, you can make sweeping changes to how a Markua 0.30 document functions with a little bit of metadata at the top.

I strongly recommend that you review all of the document settings to learn what choices are available, and decide which make sense for you. There’s no one true right answer here; it’s entirely based on personal preference and whether you are starting a new book or upgrading an existing one.

1.12Origin and structure of this document (M)

This is the Markua Spec, written by Peter Armstrong.

The Markua Spec is based on the CommonMark Spec, whose author is John MacFarlane.

This document also incorporates the specification of two of the five GitHub Flavored Markdown (GFM) extensions from the GFM Spec.

Like the CommonMark Spec and the GFM Spec, the Markua Spec is licensed under the Creative Commons license CC-BY-SA 4.0.

This document has two types of intended readers:

1. authors with advanced questions about Markua syntax
2. developers implementing Markua Processors

The Markua Spec is a strange hybrid of the CommonMark Spec, the GFM Spec and the specification of the Markua extensions.

The starting point is the CommonMark Spec. With the exception of the removal of the HTML Blocks and Raw HTML sections, the entire CommonMark Spec is preserved unchanged.

Next, two of the five GFM extensions are added. These are discussed below.

Finally, many new chapters or sections about Markua are added. These are all labeled with “(Markua extension)”.

So, for any given chapter or section of this document, it is either:

1. written by John MacFarlane about CommonMark
2. written by GitHub employees about GFM, and ending with “(GFM)”
3. written by Peter Armstrong about Markua, and ending with “(M)”

To be clear: every chapter or section which does not end with (M) or (GFM) is from the original CommonMark Spec, and was written by John MacFarlane.

Together, these sections combine to specify Markua, since Markua is CommonMark, minus HTML blocks and Raw HTML, plus two GFM extensions, plus many Markua extensions.

While this hybrid approach of creating the Markua specification is somewhat odd, it has a number of significant benefits:

1. The CommonMark Spec is very good, and is licensed under the Creative Commons license CC-BY-SA 4.0. Not starting with the CommonMark Spec would be an exercise in vanity.
2. The CommonMark Spec is the defacto standard specification of Markdown. Any specification not based on CommonMark will need to be compared to CommonMark, so the most helpful thing to do is to just start with CommonMark.
3. Writing this specification as a series of extensions to CommonMark will enable people who are implementing it to just start with a compliant CommonMark implementation and modify it appropriately.
4. Defining all Markua changes as extensions to CommonMark or deletions from CommonMark makes it abundantly clear whether something that Markua does originates in CommonMark, or whether it was added by GFM or by Markua. This is potentially helpful for authors, since it will show them what will work in other Markdown dialects, and what won’t.
5. It means that updating this document to keep it current with the CommonMark and GFM specs will be very easy.

In terms of the GFM extensions, the following two GFM extensions are included in the Markua Spec:

1. Tables (GFM)
2. Strikethrough (GFM)

Their content is unchanged, but their titles are renamed to say “(GFM extension)” instead of “(extension)”, to more clearly specify their provenance.

The other three GFM extensions are omitted:

1. Task list items is omitted since Markua is for books and courses, not task lists.
2. Disallowed Raw HTML is omitted since Markua goes farther and completely removes all raw HTML, both HTML added as HTML blocks or as raw HTML inlines.
3. Autolinks is omitted, because the extra work to create a link is literally typing two characters (< and >), so the added complexity both in parsing and in documentation is not worth it. (It does make sense for, say, a discussion forum. It does not make sense for books and courses.)

1.13About the HTML output (M)

The HTML mapping defined in this specification is NOT a complete specification of the HTML documents produced by Markua Processors.

Also, the HTML mapping defined in the specification is NOT considered to be canonical.

For example, consider the following Markua:

![a red apple](mac.jpg "The Original Mac")

A Markua Processor can produce HTML that looks like this:

<p><img src="mac.jpg" alt="a red apple" title="The Original Mac" /></p>

(That is what was produced at https://spec.commonmark.org/dingus/ on 2020-05-27, for example, and it is valid Markua as well as valid CommonMark.)

A Markua Processor can also, however, produce HTML that looks like this:

<p>
  <figure>
    <img src="mac.jpg"
         alt="a red apple">
    <figcaption>The Original Mac</figcaption>
  </figure>
</p>

Both approaches are completely legitimate, and have pros and cons.

So, why show any HTML at all? There are two reasons:

1. The CommonMark Spec shows HTML, and the Markua Spec tries to only be additive to the CommonMark Spec.
2. Showing HTML helps Markua Processors to test their parsers.

Finally, besides not being canonical, the HTML is not complete. It is only a specification of the parts of the HTML mapping where there is less need to have flexibility on the part of the Markua Processor.

The HTML mapping should be thought of specifying HTML fragments, not HTML documents. In all of the examples, a Markua Processor may add more HTML before and after the relevant content, as well as changing the relevant content itself.

If a Markua Processor wishes to test that it produces the correct HTML, it should test that the HTML produced contains the specified output, not that it is identical to the specified output.

Every example uses the default Markua document settings, unless otherwise specified. Any custom settings are specified in a document settings list in the top of the example.

1.14Why the name “Markua”? (M)

When I set out to specify Markua, I realized I needed a name. I wanted a name that conveyed the love that I have for Markdown while not implying endorsement by John Gruber in any way. I also did not want a name which referenced 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 had all these properties.

So, I named it Markua, registered the domain name, and filed a trademark. Markua and the Markua logo is a registered trademark of Ruboss Technology Corporation, the company which created, owns and operates Leanpub.

2.6Emoji (M)

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 as a smiling face with tears of joy, but you can also can think of it as 😂, which is the HTML entity reference to its Unicode character (in hexadecimal).

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.

Markua supports both the HTML character reference approach for emoji as well as the :emoji_name: syntax.

Which emoji are supported is up to the Markua Processor.

One recommended list of emoji names is at https://www.webfx.com/tools/emoji-cheat-sheet/.

The preferred thing to do when a Markua Processor recognizes an emoji is to replace it with the Unicode code point HTML entity reference, assuming that those are also handled correctly:

This makes me 😂.

This makes me :joy:.
```

<p>This makes me &#x1F602;.</p>
<p>This makes me &#x1F602;.</p>

However, it is also acceptable for a Markua Processor to just output the “tofu” characters for the HTML entity references while still supporting the :emoji_name: style emoji. Presumably with this approach, either a set of images or an emoji font will be used for the supported emoji.

Finally, if Font Awesome icons are going to be supported by a Markua Processor, using the :emoji_name: syntax, they must have their :fa- prefix which they always come with. So, the Leanpub logo in Font Awesome would be output as :fa-leanpub:.

3Document semantics (M)

As discussed in the introduction, Markua is an extension to Markdown. The goal is for Markua to feel as though Markdown just magically grew a knowledge of how to produce books and courses.

Recall that Markua’s five main additions to Markdown include the mapping of Markdown headings to book structures, the unified attribute list syntax and a comprehensive definition of document settings. These three key additions are discussed in this section. (The other two key additions, resources and online courses, are both big enough to need their own sections.

Markua adds a number of extensions to support metadata in a consistent way. These include attributes (on everything), settings (at the beginning of a document) and directives (at certain points throughout the document). All metadata is enclosed in curly braces { … }.

Metadata is not actually output in the Markua document itself. Instead, it changes the behavior of the Markua Processor, sometimes dramatically.

First, however, it is important to start with how Markua headers and metadata are used to define document structure.

3.1How headers define document structure (M)

Markua is a way of writing books and courses. Books have things like chapters, sections and subsections. Courses typically call their chapters “modules”, but it’s the same idea. Sometimes books or courses organize their chapters or modules in parts.

Markdown defines two types of heading styles.

Markua’s first innovation is to map both of these heading styles to document structure concepts.

The preferred style, called atx headers, has the following meaning in Markua:

{class: part}
# Part

This is a paragraph.

# Chapter

This is a paragraph.

## Section

This is a paragraph.

### Sub-section

This is a paragraph.

#### Sub-sub-section

This is a paragraph.

##### Sub-sub-sub-section

This is a paragraph.

###### Sub-sub-sub-sub-section

This is a paragraph.

The other style of headers, called Setext headers, defines two levels of heading only. Here’s how those are used in Markua:

{class: part}
Part
====

This is a paragraph.

Chapter
=======

This is a paragraph.

Section
-------

This is a paragraph.

Setext headers look nice, but only if you’re only using chapters and sections. If you want to add sub-sections (or lower), you’ll be using atx headers for at least some of your headers. My advice is to just use atx headers all the time. (The {class: part} attribute list on a chapter header to make a part header does actually work with Setext headers, but it’s really ugly.)

Note that while it is confusing and ugly to mix and match using atx and Setext headers for chapters and sections in the same document, you can do it. However, please don’t.

Now, regardless of whether you are using the atx or Setext header style of header, the key point is that Markua is mapping the headers to document structure concepts. The header defines the name of the part, chapter, section, etc., and the content underneath it becomes the content of that given thing (until the next header is reached).

In the HTML output, the Part and Chapter heading (for atx or Setext headers) both produce an h1, the Section heading produces an h2, and the Sub-Section heading produces an h3. Lower levels go down to h6.

To be clear, these are the Markdown “atx” header mappings:

# : Used for a Chapter heading when there is no {class: part} attribute list, and used for a Part heading when there is. This produces an h1 in HTML.

## : Used for a Section heading. This produces an h2 in HTML.

### : Used for a Sub-Section heading. This produces an h3 in HTML.

#### : Used for a Sub-Sub-Section heading. This produces an h4 in HTML.

##### : Used for a Sub-Sub-Sub-Section heading. This produces an h5 in HTML.

###### : Used for a Sub-Sub-Sub-Sub-Section heading. This produces an h6 in HTML.

The reason that a Part heading and a Chapter heading both use the # symbol, and are only differentiated by the presence of a {class: part} attribute list, is that not all books have parts, so it would be awkward to start chapters with the second-level heading.

{class: part}
# Part

This is a paragraph.

# Chapter

This is a paragraph.

## Section

This is a paragraph.

### Sub-section

This is a paragraph.

#### Sub-sub-section

This is a paragraph.

##### Sub-sub-sub-section

This is a paragraph.

###### Sub-sub-sub-sub-section

This is a paragraph.

<h1 class="part">Part</h1>
<p>This is a paragraph.</p>
<h1>Chapter</h1>
<p>This is a paragraph.</p>
<h2>Section</h2>
<p>This is a paragraph.</p>
<h3>Sub-section</h3>
<p>This is a paragraph.</p>
<h4>Sub-sub-section</h4>
<p>This is a paragraph.</p>
<h5>Sub-sub-sub-section</h5>
<p>This is a paragraph.</p>
<h6>Sub-sub-sub-sub-section</h6>
<p>This is a paragraph.</p>

These are the Setext header mappings:

{class: part}
Part
====

This is a paragraph.

Chapter
-------

This is a paragraph.

<h1 class="part">Part</h1>
<p>This is a paragraph.</p>
<h1>Chapter</h1>
<p>This is a paragraph.</p>

In the HTML output, the only difference between a part and chapter heading on the heading itself is that there is a class="part" attribute shown. However, obviously, the part and chapter headings are treated differently elsewhere, such as in the table of contents of the book or the navigation structure of the course.

The {class: part} is an example of an attribute list, which is another of Markua’s main additions to Markdown. There can be no blank line between the attribute list and the header it is attached to. Attribute lists are discussed in the Metadata section later.

Note that adding a {class: part} attribute list to any other heading level than an h1 is ignored by Markua.

Here’s an example of this being incorrectly added to an atx section header, which will have no effect:

{class: part}
## Section Heading

Foo

<h2>Section Heading</h2>
<p>Foo</p>

Here’s an example of this being incorrectly added to a Setext section header, which will also have no effect:

{class: part}
Section Heading
---------------

Foo

<h2>Section Heading</h2>
<p>Foo</p>

3.2Attribute lists (M)

Attribute lists are used to define everything from specify the language of code blocks, add ids for crosslinking and even support extensions to Markua.

3.2.1Attribute list format

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

{one: v1, two: "v2", three: 'v3!', four: true, five: 0, six: 3.14, seven: a b}

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.

Note that attribute values can be in no quotes, in double quotes (") or single quotes ('). Whenever an attribute contains spaces, using either double or single quotes is preferred to no quotes, but you can get away with using no quotes as long as the attribute value does not contain a comma.

The choice of double or single quotes is mostly personal taste. However, inside double quotes, a double quote must be backslash-escaped (\"); inside single quotes, a single quote must be backslash-escaped (\'). So, if your attribute value has a lot of double quotes, then it’s more convenient to wrap it in single quotes, and vice-versa.

Regardless of whether quotes are used, leading and trailing spaces are removed from all attribute values, but internal spaces within the attribute values are preserved.

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 (not a blank line) separating it from the block element.
2. Immediately after a span element (e.g. a word, italicized phrase, etc.) in normal paragraphs and in similarly-simple contexts, 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.

One common use of attributes is to add id attributes to headings:

{id: foo}
# Chapter Foo

foo

<h1 id="foo" class="chapter">Chapter Foo</h1>
<p>foo</p>

You can also use an {#id} syntactic sugar:

{#bar}
# Chapter Bar

bar

<h1 id="bar" class="chapter">Chapter Bar</h1>
<p>bar</p>

One common use of attributes is to add id attributes to span elements:

Here [is lorem]{id: lorem}.

This is ipsum{#ipsum}.

<p>Here <span id="lorem">is lorem</span>.</p>

<p>This is <span id="ipsum">ipsum</span>.</p>

If there is an error in the syntax of an attribute list, or if the Markua Processor does not support an attribute list in a given context, it should just ignore the attribute list and add an appropriate error.

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

You cannot add attribute lists inside headers:

# Chapter Foo{id: foo}

foo

<h1 class="chapter">Chapter Foo</h1>
<p>foo</p>

3.2.2Attribute 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 output itself.

To be clear, the keys of attributes have nothing to do with HTML attributes, even though HTML is one of the output formats of Markua. Markua does not have any particular knowledge of HTML attributes; Markua understands Markua attributes. Some Markua attributes, like class, happen to have the same name as some attributes in HTML. This is just coincidence, and many others do not.

3.2.3Attribute Values

All attributes are text. Markua Processors should interpret text values of “true” and “false” as representing true and false. Quotes, by which I mean double quotes (") not single 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. {title: "\"Fresh\" Fish"}

3.2.4id Attributes

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

3.2.5title 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 behavior of using the heading text (or the title attribute for a resource) is not appropriate, say if it’s too long.

3.2.6class Attributes

One of the attributes which is supported in every attribute list is the class attribute. This allows a Markua Processor to do smart things about formatting. However, this attribute is kind of an escape hatch, and should not be overused since it allows for nonstandard formatting.

3.2.7Conditional Inclusion Attributes on Headings

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.

cascade : true or false. The default is true. If true, the values of sample and full cascade to the children of the given part, chapter, section, sub-section, etc. If false, they do not. Typically you will want cascade to be true in all cases except for parts. Since cascade is so coupled with full and sample, this is discussed below.

full : true or false. The default is true. If true, include this heading and its content (including nested sections, subsections, etc.) in the full book or course, including the PDF and EPUB versions and the web version that is being generated. If false, omit it. Setting this to false is an easy way to “comment out” a section of your book or course.

sample : true or false. The default is false. If true, include the content under this heading (including nested sections, subsections, etc.) in the sample of the book or course that is being generated. If false, omit it. Since the default is false, by default a sample book or course is empty. Note that this attribute just governs the inclusion of the content, not the heading itself. A Markua Processor may choose to omit all headings with sample: false (either explicitly set or defaulted to false) or it 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 and EPUB) and the web version of the sample book or course.

Note that specifying either 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.

This example shows the use of sample and full:

{sample: true}
# Chapter One

This is included in the sample.

## Section One

This is included in the sample since it is contained in a chapter which is.

{sample: false}
## Section Two

This is *not* included in the sample since it is explicitly excluded, despite
the fact that the chapter is in the sample.

{sample: true}
## Section Three

This is included in the sample. This is redundant since it's in a chapter which
is.

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

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

# Chapter Two

This has the default values, so it is included in the book or course, but is
excluded from the sample.

The next example shows the behaviour of sample, with and without cascade:

{class: part, sample: true}
# Part One

This introductory text will be included in the sample.

# Chapter One

This chapter is also included in the sample since it is contained in a part
which is in the sample, and since cascade is true by default.

## Section One

This is included in the sample since it is contained in a chapter which is.

{class: part, sample: true, cascade: true}
# Part Two

This introductory text will be included in the sample.

# Chapter One

This chapter is also included in the sample since it is contained in a part
which is in the sample, and since cascade is explicitly set to true.

## Section One

This is included in the sample since it is contained in a chapter which is.

{class: part, sample: true, cascade: false}
# Part Three

This introductory text will also be included in the sample.

# Chapter One

This chapter is NOT included in the sample since the default is false and since
the part which contains it has cascade: false.

## Section One

This section is NOT included in the sample since it is not contained in a
chapter which is.

To be clear: ALL conditional inclusion attributes ONLY have meaning when used as an attribute list on headings. 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.).

Finally, as discussed later, Markua supports “extension attributes”, to allow implementations to add attributes for purposes which are not in the scope of the Markua spec. One such attribute added by Leanpub is the {community: true} attribute, which functions like a {sample: true} attribute to produce a sample book. However, the {community: true} attribute results in Leanpub producing a sample book which is only available if the reader provides an email address for the download. This type of feature obviously does not belong in the Markua spec; the point, however, is that extension attributes make it so easy to add these types of features that it is almost as though they were in the spec.

3.2.8Span attribute lists

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 id attributes or index entries. (Index entries are discussed later.)

Some text [then a span]{foo: lorem, bar: ipsum} and more text.

This [span has an id]{#hello}, so hooray!

This span [also has an id]{id: world}. 

This span contains [古池や蛙飛び込む水の音]{lang: jpn} Japanese text.

<p>Some text <span foo="lorem" bar="ipsum">then a span</span> and more text.</p>
<p>This <span id="hello">span has an id</span>, so hooray!</p>
<p>This span <span id="world">also has an id</span>.</p>
<p>This span contains <span lang="jp">古池や蛙飛び込む水の音</span> Japanese text.</p>

Note, however, that you cannot start a normal span with a caret (^): this creates a [^footnote] instead. (Footnotes are discussed below.)

3.2.9Extension attributes

Markua Processors may encounter attributes which they do not understand.

Whenever this happens, these attributes must be filtered from the output. A Markua Processor should function as though there is a whitelist of attributes which it permits for each element, and filter everything else.

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 is true whether the attributes are inserted in an attribute list attached to a span, block or even in free-floating directives.

Because of the fact that all unrecognized attributes are filtered, it is possible for a Markua Processor to add extension attributes that only it understands. This encourages competition in the Markua ecosystem, while ensuring that Markua implementations do not choke on Markua input which goes beyond their capabilities.

For example, Leanpub supports an icon attribute on blurbs. If a different Markua processor does not support this attribute, there is no harm done: the attribute just has no effect.

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

3.3Directives (M)

Directives are switches which affect the behavior of a Markua Processor.

The syntax for directives is {simple}. A directive is surrounded in curly braces, and should have a blank line above and below it.

Directives do not have a value. Instead, their presence is all that is required. Here’s the syntax for an imaginary directive foo:

some content

{foo}

some content

To be clear: a directive does NOT contain {key: value} pairs. That is an attribute list, not a directive.

The absence of key-value pairs is what makes a directive a directive. It is a keyword by itself, enclosed in curly braces on a line by itself. So, the following is also a directive, albeit a poorly-formatted one:

some content
{foo}
some content

The specific directives are discussed next.

3.3.1The pagebreak directive

Although authors are encouraged to not think about page breaks, this directive is a nod to reality: sometimes an author will really, really want to insert a page break.

This is done with the {pagebreak} directive:

lorem ipsum dolor

{pagebreak}

foo bar baz

Again, the use of this directive is discouraged. Authors should spend their time writing, not formatting.

3.3.2The mainmatter and backmatter directives

Most published books have three types of material in them: the front matter, the text (or “main matter”) and the back matter. (Yes, this applies to courses as well as books, since many Markua Processors like Leanpub can generate a book out of the course material.)

What authors write, the manuscript, is typically what goes into the text, or main matter, of the book. In style guidelines this is often called the text; in formats such as TeX and LaTeX it is called main matter. It’s what is typically numbered with Arabic numerals starting from 1. In Markua, the first page of the mainmatter will be numbered page 1, regardless of whether or not the page number will be shown on that page.

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. The stuff before the main matter is called “front matter”. The special pages that can be created by insertion directives are not numbered. The rest of the frontmatter follows the same page numbering rules as the main matter, except that numbering uses Roman numerals. The first page of the frontmatter will be numbered page i, regardless of whether or not the page number will show on that page.

There’s also a bunch of other stuff (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.)

So, this is where the mainmatter and backmatter directives come in. With this approach, your book is essentially the following:

any frontmatter content, like a dedication, preface or introduction

{mainmatter}

the body of your book (the text or main matter)

{backmatter}

any back matter content, such as appendices

Note that there is no need for a {frontmatter} directive, so it does not exist. A Markua Processor should ignore it if it is encountered, but a warning can be provided.

• Everything before the {mainmatter} directive is in the front matter.
• Everything after the {mainmatter} directive and before a {backmatter} directive is in the main matter
• Everything after the {backmatter} directive is in the back matter

The {mainmatter} and {backmatter} directives act as dividers, separating a book or course into logical groups of content.

While these mainmatter and backmatter directives are merely optional hints, there is a very strict rule about their use: each of them ({mainmatter}, {backmatter}) can only appear once in a document.

Now, note that the most minimal way to write a book is to use no section directives at all. With this approach, everything is in the text (main matter) of the book. Page numbering is in Arabic numerals, etc.

For authors who do not know about the section directive, this is what they are doing. Nothing bad or unexpected will happen: they can write their book, and it will look correct. Only when they go to add things like a preface or an appendix, and feel the need for different numbering, will they need to discover the section directives. Then, they can add them to their Markua document as appropriate.

3.3.3The insertion directives (dedication, toc, etc.)

With a book or course, certain types of content gets created by the Markua Processor, or in metadata provided by the author. This content then needs to be positioned in the book or course.

While a Markua Processor can adopt sensible defaults, sometimes an author wants more fine-grained control over where this automatically-generated content or user-provided metadata content is inserted. That’s what the various insertion directives are for: to specify the positioning of where this content is inserted.

Here’s an example book:

some front matter content

{dedication}

more front matter content

{toc}

{figures}

even more front matter content

{mainmatter}

the main matter content

{backmatter}

some back matter content

{index}

more back matter content

{quiz-answers}

The following the insertion directives which can only occur in the front matter, which is everything before the {mainmatter} directive:

• {half-title}
• {series-title}
• {title-page}
• {copyright}
• {dedication}
• {epigraph}
• {toc} (for the Table of Contents)
• {figures} (for the List of Figures)
• {tables} (for the List of Tables)

To be clear, these directives will not work if they are inserted after the {mainmatter} directive.

Also, note that there is no more {frontmatter} directive in Markua. It existed in Markua 0.10, but it is redundant: front matter is just the stuff which is comes before a {mainmatter} directive. (You should remove it when migrating a Markua 0.10 document to the version of Markua specified here, but if you forget, don’t worry: Leanpub will ignore the {frontmatter} directive, and other Markua processors should do so as well.)

Note that a Markua Processor can be smart about certain things, if it wants to. For example, it can choose to not number the pages before the Table of Contents, but to number the pages after the Table of Contents. Then, the author can use the {toc} directive to choose where in the front matter the Table of Contents is positioned. This will not only affect its position, it will also affect the numbering of content before and after it.

The following are the insertion directives which can occur in the back matter, which is everything after the {backmatter} directive:

• {index}
• {exercise-answers}
• {quiz-answers}

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

3.3.4The lang-* directives

There is one more set of directives, the lang-* directives. These all start with lang-.

The lang-* directives are important enough that they are discussed in the next section, which also discusses the lang attributie and document setting.

3.3.5The hanging indent directives

Scholarly works sometimes need bibliographical entries to be formatted with hanging indents. So, this is part of the Markua spec. It makes sense for this to be done with directives, since this way there is a standard, portable way that they are defined.

To use it, you use the directives {begin-hanging-paragraphs} to start using hanging paragraphs, and {end-hanging-paragraphs} to end it. Like all directives, these must be on lines by themselves, with blank lines above and below them. Here’s a quick example:

This is a normal paragraph.

{begin-hanging-paragraphs}

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec hendrerit tempor tel\
lus. Donec pretium posuere tellus.

Aliquam erat volutpat. Nunc eleifend leo vitae magna.

Pellentesque dapibus suscipit ligula. Donec posuere augue in quam. Etiam vel tortor \
sodales tellus ultricies commodo. Suspendisse potenti. Aenean in sem ac leo mollis b\
landit. Donec neque quam, dignissim in, mollis nec, sagittis eu, wisi. Phasellus lac\
us.

Pellentesque dapibus suscipit ligula. Donec posuere augue in quam. Etiam vel tortor \
sodales tellus ultricies commodo. Suspendisse potenti. Aenean in sem ac leo mollis b\
landit. Donec neque quam, dignissim in, mollis nec, sagittis eu, wisi. Phasellus lac\
us.

{end-hanging-paragraphs}

This is a normal paragraph again.

This is a normal paragraph.

3.4The lang document setting, lang attribute and lang directives (M)

When generating books, knowing the language being used is very important. This enables a Markua Processor to do two things:

1. Know which fonts to use (since the fonts to use should take into account the language of the text).
2. Know the direction of the text (left-to-right or right-to-left).

Note that the way which default fonts are specified for each language in a Markua document is not defined in this specification. At a bare minimum, a Markua Processor should allow users to specify the font to use for each language.

For example, Leanpub defines standard themes for each supported language, which specify default fonts to use for titles, body text and code samples. Leanpub authors can also create custom themes, with their own font choices for each language, of course. Leanpub authors can even make these custom themes reusable, so that they can use one theme for all their books.

Anyway, there are three ways for an author to indicate what language is being used at any given time:

1. The lang document setting, which sets the default language.
2. The lang attribute, which temporarily overrides the default language for a particular span or block.
3. The lang-* directives, which set a new default language. This will be the default language until another lang-* directive is encountered. (There is no directive called lang-* itself; what this refers to is a family of directives like lang-eng, lang-jpn, lang-zh-Hant, etc.)

In all three cases, the value being set is the language code of the language that the Markua document is written in. This language code is found in IS0 639-3, with two exceptions:

1. Traditional Chinese is zh-Hant.
2. Simplified Chinese is zh-Hans.

Since English is the default language of a Markua document, all Markua Processors must support the eng value. Support for all other language codes (or lang-* directives) 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.

3.4.1The lang document setting

A Markua document has a global lang document setting, which sets the default language. All document settings have default values; the default value of the lang document setting is eng.

Document settings are discussed here.

For a example of the lang document setting in action, see the section “A detailed example” below.

3.4.2The lang attribute

A lang attribute can be applied to a particular block or span.

After that block or span concludes, the lang immediately reverts to the default language.

Here is some English text.

{lang: jpn}
古池や蛙飛び込む水の音

{lang: jpn}
春過ぎて夏来にけらし白妙の衣干すてふ天の香具山

This is some paragraph text which defaults to English, and it
contains [古池や蛙飛び込む水の音]{lang: jpn} a span which is in Japanese.

This is some paragraph text which still defaults to English.

This example used attribute lists on two paragraphs and on a span.

The default language of the document stayed as eng throughout, even though two paragraphs and one span had their language set to Japanese.

Having to specify the lang attribute list on every single paragraph which did not use the default language would get annoying very quickly! This is why the lang-* directives exist.

3.4.3The lang-* directives

NOTE FOR LEANPUB AUTHORS: The lang-* directives are not yet supported on Leanpub. We will add support for them sometime in Q1 2024, and remove this note (TODO) when this is done.

The lang-* directives set a new default language. This will be the default language until another lang-* directive is encountered.

This example shows how to use the lang-* directives to temporarily switch the default language of a Markua document:

Here is some English text.

The Markua Processor knows it is in English since there is no document settings
block, so the default document setting for `lang` is `eng`.

{lang-jpn}

古池や蛙飛び込む水の音

春過ぎて夏来にけらし白妙の衣干すてふ天の香具山

{lang-eng}

Here is some more English text.

For another example of the lang-* directives, see the section “A detailed example” below.

3.4.4A detailed example

The following example shows a number of uses of the lang document setting, the lang attribute, and the lang-* directives.

{
  lang: eng
}

# Chapter One

Note that there was a document settings block at the beginning of this Markua
document. It set the default language to `eng`. Since that is the default of
the `lang` document setting, that was redundant.

This is still in English. Now we will use the `lang-jpn` directive to switch
the default language to Japanese, so that we can output some Haiku
by 松尾芭蕉{lang: jpn} (Matsuo Bashō). (Note that this was a use of the `lang`
attribute on a span).

{lang-jpn}

古池や蛙飛び込む水の音

春過ぎて夏来にけらし白妙の衣干すてふ天の香具山

{lang-eng}

Now we are back in English, since we used the `lang-eng` directive again to
switch the default back to English.

Directives are the correct way to switch the default language for an extended
period of time, but sometimes you may want to just switch the language for a
particular block or span. We already saw how to use the `lang` attribute on a
span; here's how to use it on a block:

{lang: jpn}
夏草や兵どもが夢の跡

Now we are still in English, since the above was a `lang` attribute, not a
`lang-*` directive.

Finally, we'll use the `lang-*` directives again, to switch to Traditional
Chinese and then to Arabic for some more poetry.

{lang-zh-Hant}

花間一壺酒，獨酌無相親。
舉杯邀明月，對影成三人。

{lang-ara}

أَلا كُلُّ شَيْءٍ ما خَلا اللهَ باطِلُ
وَكُلُّ نَعِيمٍ لا مَحالَةَ زائِلُ

{lang-eng}

And with those poems by 李白{lang: zh-Hant} (Li Bai) and
by الْمُتَنَبِّي {lang: ara} (Al-Mutanabbi), we can get back to the spec!

Implementors of Markua Processers should strongly consider using this example as a test case!

3.5Paragraph continuations (M)

In books, you can insert things like lists in the middle of paragraphs.

Ideally, this would be one paragraph. However, it’s not:

foo
  * lorem
  * ipsum
bar

<p>foo</p>
<ul>
<li>lorem</li>
<li>ipsum
bar</li>
</ul>

Here, you lose hard, because “bar” is considered to be part of the same list item as ipsum. I think this is a mistake, but it is more important to preserve Markdown compatibility than to fix this mistake.

Ideally, it would also be possible to insert a list inside a paragraph. However, it’s not:

foo

  * lorem
  * ipsum

bar

<p>foo</p>
<ul>
<li>lorem</li>
<li>ipsum</li>
</ul>
<p>bar</p>

The reason here is that HTML does not support inserting lists in paragraphs. Lists are always siblings to paragraphs, not contained within them.

There is no way to fix this at the HTML tag level, since this is just how HTML works. It would be possible to just construct a fake list with a bunch of CSS and break tags inside a paragraph, but that would be far worse.

From an HTML perspective, you cannot insert lists inside paragraphs. But if you are writing in Markua, you’re not just writing HTML. You can also be generating a book in PDF and other non-HTML formats, which do support lists inside paragraphs just fine.

So, there needs to be some way to indicate that the beginning of a paragraph after something like a list is actually a continuation of the previous paragraph.

Now, this could have been done by just not adding blank lines, only single newlines, but that would involve fighting against existing Markdown behavior. Worse, it would introduce an incompatibility just to fix something that many people don’t consider broken.

For authors who want a list to appear to be inside a paragraph, Markua does have two solutions. First, you can just add a continued-para class to the subsequent paragraph, via an attribute list:

foo

  * lorem
  * ipsum

{class: continued-para}
bar

<p>foo</p>
<ul>
<li>lorem</li>
<li>ipsum</li>
</ul>
<p class="continued-para">bar</p>

It would then be up to the Markua Processor to use the appropriate CSS to make the paragraph with the continued-para class look like a continuation of the previous paragraph, such as by removing indentation or decreasing leading space.

(Attribute lists, discussed later, are one of the main contributions of Markua.)

However, if you are an author who cares about this feature, typing an attribute list whenever you want to continue a paragraph is really obnoxious. So, there needs to be some syntactic sugar, and there is, with the ^ symbol.

A caret (^) on a line by itself above a paragraph functions as a {class: continued-para} attribute list for the following paragraph:

foo

  * lorem
  * ipsum

^
bar

<p>foo</p>
<ul>
<li>lorem</li>
<li>ipsum</li>
</ul>
<p class="continued-para">bar</p>

Note that this works for more than just lists. In fact, it has nothing to do with lists, or even with images or other resources. It’s all about the indentation behavior of a paragraph, typically following some other block. So, you can use this whenever you want:

foo

> a block quote

^
bar

<p>foo</p>
<blockquote>
<p>a block quote</p>
</blockquote>
<p class="continued-para">bar</p>

3.6Concatenating manuscript files inserts blank lines between them (M)

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.

The way that the list of files that should be included in the book or course being generated from a Markua manuscript is defined is implementation-specific, and is not formally specified.

For example, Leanpub enables authors to write books and courses either in a web browser or in local files on an author’s computer. In the browser mode, the author chooses a file to edit via a web UI, which also allows the files to be reordered, etc. In the local files mode, the author creates a file called Book.txt which just lists the files in order. The reason that this is worth mentioning is that in both cases, what results is a simple list of files, and nothing more. All semantics about which content is included in, say, the full book or the sample book is determined by attribute lists, which are specified in the Markua specification.

Now, even though the way that the list of files is defined is not part of the Markua spec, the way that the files are concatenated together to produce the full manuscript is part of the Markua spec.

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 by adding two newlines (i.e. one blank line) between the end of each file and the beginning of the next file.

So, after this process, exactly one blank line separates the contents of each manuscript file. Note that because of this rule, a paragraph (or any other block element) cannot span multiple manuscript files.

To see why this approach is so important, consider the following single-file Markua document:

# Chapter One

Lorem ipsum dolor.

# Chapter Two

Yada yada yada.

<h1 class="chapter">Chapter One</h1>
<p>Lorem ipsum dolor.</p>
<h1 class="chapter">Chapter Two</h1>
<p>Yada yada yada.</p>

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

ch1.txt:

# Chapter One

Lorem ipsum dolor.

<h1 class="chapter">Chapter One</h1>
<p>Lorem ipsum dolor.</p>

ch2.txt:

# Chapter Two

Yada yada yada.

<h1 class="chapter">Chapter Two</h1>
<p>Yada yada yada.</p>

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

# Chapter One

Lorem ipsum dolor.# Chapter Two

Yada yada yada.

<h1 class="chapter">Chapter One</h1>
<p>Lorem ipsum dolor.#Chapter Two</p>
<p>Yada yada yada.</p>

If Markua only added one newline when concatenating, this would produce a correct manuscript (since headings end paragraphs), but one with possible bugs:

# Chapter One

Lorem ipsum dolor.
# Chapter Two

Yada yada yada.

<h1 class="chapter">Chapter One</h1>
<p>Lorem ipsum dolor.</p>
<h1 class="chapter">Chapter Two</h1>
<p>Yada yada yada.</p>

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:

# Chapter One

Lorem ipsum dolor.

# Chapter Two

Yada yada yada.

<h1 class="chapter">Chapter One</h1>
<p>Lorem ipsum dolor.</p>
<h1 class="chapter">Chapter Two</h1>
<p>Yada yada yada.</p>

4Document settings (M)

Markua’s philosophy is that non-semantic formatting is procrastination. Because of this, almost all formatting is done by global switches. These switches are called document settings, and they are defined once, at the beginning of the document. Document settings affect the formatting of the entire book or course.

Document settings are defined in one or more document settings hashes. The document settings hash or hashes must be at the start of a Markua document. Once something other than a document settings hash or a blank line is encountered, no more document settings hashes can be defined. (Document settings hashes can be separated with single or multiple newlines, but once something other than a document settings hash or blank line is encountered, no more document settings hashes can be defined.)

4.1Document settings are specified in simple key-value pairs or in JSON (M)

There are two ways to specify a document settings hash:

1. As a newline-separated flat list of key-value pairs (key: value). With this format, every non-blank line in the document settings hash must contain a key, a colon :, and a value. Any whitespace at the beginning or end of the keys and values will be stripped.
2. As JSON.

The Markua Spec only defines a short list of the standard document settings which all Markua Processors must support. In the spec, these settings are defined in a flat list of key: value pairs, but they can also be specified using JSON.

4.2The standard document settings (M)

The Markua Spec only defines the settings which all Markua Processors MUST support. It is expected that Markua Processors will define their own implementation-specific settings somehow, either as document settings which are in a flat list, as JSON, or both.

Since Markua defines a number of document settings, it is helpful to see what the defaults are in one list. These defaults are listed below.

{
  alt-title: all
  chapter-number-format: name
  default-code-language: guess
  default-table-column-spacing: 6pt
  figure-classes: all
  include-page-numbers-in-references: true
  italicize-underlines: true
  lang: eng
  list-figures: combined
  number-figures: sequential
  part-number-format: name
  restart-endnote-numbering: true
  restart-footnote-numbering: true
  section-number-format: name
  soft-breaks: space
  toc-chapter-number-format: name
  toc-part-number-format: name
  toc-section-number-format: name
  two-space-hack: true
}

What these settings all mean is explained in the rest of this section.

Note that the behavior of resources which are treated as figures is controlled by four related settings: alt-title, figure-classes, list-figures and number-figures. These need to be considered together: the behavior of these settings are tightly coupled.

alt-title : all, text or none. The default is all, for compatibility with Markua 0.10 and Leanpub Flavoured Markdown by default. This setting controls whether, in the cases where there is no figure title explicitly set, the alt text on a resource is removed and used as the figure title instead. This setting is so important it is discussed in its own section below.

chapter-number-format : category_number_name (e.g. Chapter 1: The Chapter Name), category_number (e.g. Chapter 1), number_name (e.g. 1 The Chapter Name), number (e.g. 1) or name (e.g. The Chapter Name). The default is name. This determines the format of the chapter heading in the body of the book. The format of the chapter heading in the table of contents is set by the related toc-chapter-number-format setting.

default-code-language : The default language that code which is a local resource, web resource or inline resource inserted as a block with three 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 as a block with three backticks–it has no effect on code spans, or on inline resources inserted with tildes. The default language for inline resources delimited by three tildes is always text, but you can override the default on individual resources of course. Finally, code spans do not support syntax highlighting, so there is no equivalent setting for the default language of code spans.

default-table-column-spacing : The default amount of space between table columns. The default is 6 pt. This can be overridden by the column-spacing attribute on individual table resources.

figure-classes : this is a comma-separated list of the figure classes which are included in the list(s) of figures near the beginning of the book or course. The default is all, which means that all figures are included, regardless of the value of their class attribute. An example of this setting is: figure-classes: equation, figure, image, listing. Note that whether the figures are listed, either grouped by their class or together in one big list, is controlled by the list-figures setting. Note that the numbering of figures is controlled by the number-figures setting.

include-page-numbers-in-references : true or false. The default value is true. When a smart crosslink to a figure reference is inserted with #f, this setting determines how the reference is displayed. If true (the default), the text includes the page number (e.g. “Figure 8.2: Anatomy of a Squirrel on page 42”) when inserted in a PDF; if false, it does not (e.g. “Figure 8.2: Anatomy of a Squirrel”. This setting has no effect on EPUB, which never includes page numbers in references (since the text is resizable).

italicize-underlines : true or false. The default value is true. If italicize-underlines is true, then _this_ and *this* are both italic. If italicize-underlines is false, then _this_ is underlined while *this* is italic. This is discussed here.

lang : The IS0 639-3 three character language code of the language that the Markua document is written in. The default is eng.

list-figures : combined, groups or none. The default value is combined. This setting controls whether figures are listed in one or more lists near the beginning of the book. Note that whether these figures are numbered is controlled by the number-figures setting. The list-figures setting respects the numbering decision specified there. This is what the values mean:

• none: No lists of figures are produced.
• combined: One combined list of figures is produced for all figures in the manuscript, ordered by their appearance in the manuscript. This list is called List of Figures for English books, and localized into the language of the book or course. This produces figures named Figure, and (by default) numbered sequentially: Figure 1, Figure 2, Figure 3, etc. The numbering is defined by the number-figures document setting, specified below.
• groups: The Markua Processor should group figures by their classes or types. Here’s how the grouping works:
  1. If there is no class attribute, the figure is grouped in a list with other resources of its type. This is a nice default, since it results in a List of Tables, List of Code Samples, List of Images, etc. The type of a resource can be specified by the type attribute, or inferred from the format of the resource.
  2. If there is a class attribute, this overrides the type. For example, it is almost never a good idea to have a List of Verbatim, so if you add a class of poem you will get a List of Poems. (There is nothing special about poem, by the way: if you add a class of sonnet, you will get a List of Sonnets. This is not just useful to differentiate types of poetry, by the way: this approach can be used to automatically produce a List of Lemmas, List of Theorems, etc.

The combination of list-figures: groups and number-figures: chapter produces figures like Listing 1.1, Listing 1.2, Listing 4.1 and Image 1.1, Image 1.2, Image 2.1, Image 2.2, Image 4.1, etc. This is a good combination of document settings for books like computer programming books.

number-figures : chapter, none, or sequential. The default is sequential. If the value is chapter or sequential, then resources are numbered when they are inserted as figures. If the value is sequential, you get numbering like Figure 1, Figure 2, Figure 3, etc. If the value is chapter, you get numbering like Figure 1.1, Figure 1.2, Figure 4.1, etc. If the value is none, figures are not numbered.

part-number-format : category_number_name (e.g. Part 1: The Part Name), category_number (e.g. Part 1), number_name (e.g. 1 The Part Name), number (e.g. 1) or name (e.g. The Part Name). The default is name. This determines the format of the part heading in the body of the book. The format of the part heading in the table of contents is set by the related toc-part-number-format setting.

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.

section-number-format : number_name (e.g. 1.1 The Section Name), number (e.g. 1.1) or name (e.g. The Section Name). The default is name. This determines the format of the section heading in the body of the book. The format of the section heading in the table of contents is set by the related toc-section-number-format setting.

soft-breaks : break or space. The default is space, for compatibility with Markdown. This setting determines the behavior of single newlines (i.e. a newline which is not followed by another newline) in the output. With space, single newlines in the source essentially produce a single space in the output (like Markdown and Leanpub Flavoured Markdown). With break, single newlines inside paragraphs in the Markua document essentially produce newlines in the output (like Markua 0.10). This setting is so important it is discussed in its own section below.

toc-chapter-number-format : category_number_name (e.g. Chapter 1: The Chapter Name), category_number (e.g. Chapter 1), number_name (e.g. 1. The Chapter Name), number (e.g. 1) or name (e.g. The Chapter Name). The default is name. This determines the format of the chapter heading in the table of contents of the book. The format of the chapter heading in the body is set by the related chapter-number-format setting.

toc-part-number-format : category_number_name (e.g. Part I: The Part Name), category_number (e.g. Part 1), number_name (e.g. I. The Part Name), number (e.g. I) or name (e.g. The Part Name). The default is name. This determines the format of the part heading in the body of the book. The format of the part heading in the table of contents is set by the related toc-part-number-format setting.

toc-section-number-format : number_name (e.g. 1.1 The Section Name), number (e.g. 1.1) or name (e.g. The Section Name). The default is name. This determines the format of the section heading in the body of the book. The format of the section heading in the table of contents is set by the related toc-section-number-format setting.

two-space-hack : true or false. The default is true, for compatibility with Markdown. If true, adding two spaces at the end of a line forces a hard line break. If you use this setting, ensure that your text editor does not strip trailing whitespace! This is probably the best choice if soft-breaks is set to space, or if you want maximum compatibility with Markdown. If false, spaces at the end of a line are ignored, and the single newline is treated as a single newline would be without those spaces, which is determined by the value of the soft-breaks setting. Since Markua allows the behavior of soft line breaks to be configured with the soft-breaks setting, the two-space-hack is not needed if the soft-breaks setting is break. However, even in this case, authors may wish for the two space hack to still function as it does in Markdown, in order to support existing Markdown text or in cases where there are multiple authors of a manuscript.

4.3The soft-breaks document setting (M)

As discussed above, the soft-breaks is one of the document settings that a Markua document can have. (Document settings are set at the beginning of a Markua document, or via a user interface such as a web page.)

The soft-breaks document setting can be break or space. The default is space, for compatibility with Markdown.

If you want the behavior of Leanpub Flavoured Markdown, you need to choose space.

If you want the behavior of Markua 0.10, you need to choose break.

This setting determines the behavior of single newlines (i.e. a newline which is not followed by another newline) in the output. This is what the values mean:

space : Single newlines inside paragraphs in the Markua source produce output which functions like a single space. In output such as PDF, a single space must be what is output. In output such as HTML, a single newline is output, since in HTML output, a single newline is equivalent to a single space in terms of the effect on presentation. So, this type of line break only is a line break in the HTML source, and in all output presentation it functions like a space–hence the name space. The space option is the default for compatibility with Markdown by default. If you want the behavior of Markua 0.10, choose break.

break : Single newlines inside paragraphs in the Markua document produce break tags in the HTML output and line breaks in non-HTML output like LaTeX or PDF. The reason this value is called break is to indicate that when you hit a newline to get a line break, you get a real line break. To be clear: the break attribute means to insert a forced linebreak whenever a single newline is encountered in the manuscript, regardless of whether there are two spaces at the end of the line. While this makes some intuitive sense, it is very much against the default behavior of Markdown. The break option gives you the behavior of Markua 0.10, in which all single newlines function as though they were using the “two space hack” to produce a hard line break in normal Markdown. (Whether the “two space hack” is enabled in a Markua document is determined by the value of the two-space-hack setting, discussed below.)

4.4The alt-title document setting (M)

As discussed above, the alt-title is one of the document settings that a Markua document can have. (Document settings are set at the beginning of a Markua document, or via a user interface such as a web page.)

The alt-title document setting controls whether, in the cases where there is no figure title explicitly set, the alt text on a resource is used as the figure title instead of as alt text.

The alt-title document setting can have the value of all, text or none. The default is all, for compatibility with Markua 0.10 and Leanpub Flavoured Markdown by default. These are the three choices, and what their values mean:

• all: if no title is provided for a given resource, regardless of the resource type, remove the alt text and use it as the figure title instead. (This choice is the default, since it is the closest to the behavior of LFM and of Markua version 0.10. So, regardless of whether you like the choice, there are 12 years worth of books on Leanpub which would be broken by a different default.)
• text: if no title is provided for a given text-based resource (such as an external code sample), remove the alt text and use it as the figure title instead. However, if the resource is not purely text-based, such as an image or a video, do not remove the alt text to use it as the figure title, even if no figure title is provided. This is arguably the most sensible choice, as it strikes a balance between preserving compatibility with Markdown for non-text-based resources like images, while still providing a sensible default for text-based resources like code samples. Since Markdown does not define support for external text-based resources, there is no conflict here.
• none: never remove the alt text to use it as the figure title, even for a text-based resource where no figure title is provided. (This is how Markdown behaves.)

Using the alt text as the figure title is the most terse syntax, and may make sense if no alt text is needed. For example, valid use cases include:

• Code samples and other text-based resources. Since these resources are themselves text, it makes no sense to have different alt text.
• Images, if the only output target is a format like print-ready PDF where no alt text is needed.

If alt text is used as the figure title, it is NOT also provided as alt text, since it would be very annoying to hear the same text spoken twice (once as the alt text and once as the figure title) when using a screen reader.

Now, it is a debatable point whether using alt text as figure captions is a good idea. The main argument in favour of it is terseness: it is the most terse syntax, and the easiest to remember.

A second argument is that in some cases such as external code samples and other text-based resources, there is no conceivable use for alt text, so the way to add a title with the least syntax is to use the spot for the alt text.

A third argument in favour of it is aesthetics, since the alternative syntax in which a title is provided without any alt text looks like this:

![](someimage.png "A Figure Caption")

With this syntax, you have the [] for what looks like no real reason.

Now, the main argument against using alt text as figure captions is very straightforward: you are supposed to actually provide alt text, and the alt text should be different from the figure caption.

Alt text is supposed to be supposed to be descriptive (say to provide a literal description of an image for people with visual disabilities, or who are listening to the book as an audiobook), whereas good figure captions are terse (and often witty). These are different requirements, so they should have different text.

With this argument in mind, if it looks like a bit of an error to have empty square brackets, that’s a good thing: according to this argument, you should always provide alt text, and it should be different from the figure caption. Having missing alt text look like a bit of a mistake is actually correct.

Now, this is a very good argument, but as shown above, there are good counterarguments as well. So, the behavior of the alt text is determined by the alt-title document setting, and the default value is all (not text or none). The reason why the default is all is simple: there are over a decade of Leanpub books which do this, since they were written in Leanpub Flavoured Markdown or Markua 0.10:

![A Figure Caption](someimage.png)

Despite what one’s opinion of what the correct value of alt-title should be, the default value of alt-title is an acknowledgment of Markua’s history.

So, even though the default value of alt-title is all, the conclusion I’ve come to is that the default behavior of Markdown is best for image resources, and alt text should be used for descriptions, not figure captions, in the case of images. If you’re in this camp, the way to use alt text, and the best syntax when inserting an image, is to do the following:

![some descriptive alt text](someimage.png "A Figure Caption")

Note that you can use that syntax even with the default alt-title: all, since the explictly-defined title will take precedence over the alt text. The alt-title document setting only defines what to do when there is no title set.

To be clear, the alt-title document setting never makes a figure caption be used as the alt text, and it makes alt text be used as a figure caption if and only if no title attribute is provided, either in quotes or in the attribute list.

In these examples, the value of the alt-title document setting does not matter:

![This is always alt text, since a title is provided](someimage.png "A Figure Caption")

{title: "A Figure Caption"}
![This is always alt text, if a caption is provided](someimage.png)

{title: "This is ALWAYS a Figure Caption, Regardless of alt-title"}
![](someimage.png)

![](someimage.png "This is ALWAYS a Figure Caption, Regardless of alt-title")

Again, to be clear, the only thing that the alt-title document setting affects is whether the alt text is used as the figure caption instead of as alt text if there is no title attribute provided as the figure caption.

In these examples, the value of the alt-title document setting does matter:

![No title, so this will be the figure caption if alt-title is all](someimage.png)

![This will NOT be the figure caption if alt-title is text or none](someimage.png)

4.5Multiple document settings hashes are permitted (M)

A Markua document can define multiple document settings hashes.

There must be at least one blank line between the end of the settings block and the start of any other document content other than another document settings hash.

The reason that more than one document settings hash is permitted is that a Markua Processor may also get settings from elsewhere, like a web interface. The most straightforward thing to do in such a case is to just add another document settings hash at the beginning of the file, and then let the Markua Processor sort out any conflicts.

In the case of a conflict between settings defined in a document and settings defined, say, in a web interface, the last setting definition must win. However, a Markua Processor may override settings whose values are unsupported or illegal.

Here’s an example of a Markua document which could be generated if there is a settings block produced by a web interface, and then a settings block manually added at the start of a book:

{
  alt-title: all
  figure-classes: equation, figure, image, listing
  list-figures: groups
  number-figures: chapter
  soft-breaks: space
  two-space-hack: false
}

{
  italicize-underlines: true
}

# Chapter One

Lorem ipsum dolor...

Now, most tools will not output their settings as key-value pairs, but will instead output them as JSON. JSON is easy to output and to parse, since there are good JSON libraries for almost all popular programming languages.

So, here’s the same example, but with the automatically-generated set of document settings specified as JSON:

{
  "alt-title": "all",
  "figure-classes": [
    "equation",
    "figure",
    "image",
    "listing"
  ],
  "list-figures": "groups",
  "number-figures": chapter,
  "soft-breaks": "space",
  "two-space-hack": false
}

{
  italicize-underlines: true
}

# Chapter One

Lorem ipsum dolor...

Regardless of how the automatically-generated document settings are output, the author will typically only see the manually-defined document settings block. So, the formatting of the automatically-generated document settings doesn’t really matter, and JSON is the pragmatic choice.

4.6Custom document settings are encouraged (M)

Finally, Markua Processors can also add their own document settings, just as Markua Processors can understand their own extension attributes.

For these custom document settings, JSON is ideal, since JSON supports nested objects, arrays, and all the data types which are needed.

It is expected that Markua Processors such as Leanpub will add a bunch of their own custom document settings, typically in JSON, in order to control the formatting of all parts of a Markua document. This is encouraged.

It is deliberate that these document settings are not being formally-specified: doing so would actually serve to limit innovation. There are many ways to format a document, and Markua should not seek to define the one true way to do so.

5Resources (M)

Markua documents are written in plain text, either in one text file or multiple text files. However, modern books and courses sometimes contain more than text. Books and courses may embed many kinds of resources.

Resources vary in four different ways:

1. Type
2. Format
3. Class
4. Location

While resources are a very important addition that Markua makes to Markdown, they are exactly that: an addition. Resources provide an important conceptual framework, while remaining purely additive to standard Markdown. Specifically, all images, fenced code blocks and tables supported by CommonMark or GFM work in Markua unchanged.

What resources do is provide consistency, both in the conceptual understanding, in adding support for attribute lists, and specifying standard type, format and class attributes for all resources, including the resources such as images, fenced code blocks and tables which are also found in other Markdown dialects.

We have already discussed attribute lists earlier for things like part headings and conditional inclusion attributes, but by far the most important use of attribute lists in Markua is with resources. For resources, attribute lists can be used to specify a figure title and alt text, set an id, specify the format, and do other useful things.

While resources are an important addition that Markua makes to Markdown, they were not created in a vacuum. As you’ll see, the syntax for local and web resources is similar to Markdown’s inline image insertion syntax, and the syntax for inline resources is just the fenced code blocks syntax from CommonMark with the addition of format specifiers and attribute lists. Furthermore, the standard Markdown image syntax is the inspiration for the syntax of all local and web resources.

Before we consider how resources vary by type, format, class and location, we will consider what they have in common. Specifically, resources share the following things:

1. Attributes and attribute list support
2. Behavior as a figure or a span based on the presence of title
3. Support for a title to be provided, either in the attribute list, in quotes or from alt text based on the alt-title document setting.

5.1Resource attributes (M)

Resources have attributes. Attributes can be specified in two ways:

1. In attribute lists.
2. In the syntax for the resource insertion.

As you will see soon, resources can be local, web or inline.

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

{key: value, comma: separated, optional: attribute_list}
![optional alt text](resource_path_or_url "Optional Figure Title")

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

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

You can also insert an inline resource using three or more tildes (~) as the delimiter, instead of the more typical backticks (`):

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

To be clear, the number of backticks or tildes can be three or more. This is just the fenced code blocks syntax, which is discussed later.

Finally, a local or web resource can also have attributes specified after the resource itself. This is a lot less common, and is discouraged, but it is documented for completeness:

![optional alt text](resource_path_or_url "Optional Figure Title"){key: value, comma: separated, optional: attribute_list}

This is gross, but the reason it is supported is since resources can be inserted in a sentence, and attribute lists (e.g. for index entries) can be added this way.

5.1.1The attribute list takes precedence

It is always an error to specify an attribute both in the attribute list for a resource 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, and the Markua Processor should report the error to the author in a list of errors and warnings. (Errors and warnings must never be output by a Markua Processor in the book or course itself, but must always presented in a separate list for the author’s use only.)

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

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

In the following figure, the alt text would be “foo” not “bar”:

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

In the following figure, the title text would be “foo” not “bar”:

{title: foo}
![](foo.png "bar")

Again, the Markua Processor should treat all of these as errors, and output them in a list of errors and warnings.

5.2Common resource attributes (M)

The supported attributes vary based on the type of resource, but all resources support the class, format, title and type attributes.

As you recall, resources vary in four ways:

1. Type
2. Format
3. Class
4. Location

The first three of these ways that resources vary are specified via the type, format and class attributes. These attributes are discussed briefly here, and in the sections below. The fourth way, location, is discussed in a later section below.

These are the attributes that resources all share:

class : All attribute lists, including those for resources, support a class attribute. When used on a resource, this is the class of the resource. This can be used for styling, and it can also be used by Markua Processors which group figures by classes. Note that there is no need to set a class of figure on a resource. That would be too verbose and error-prone. Instead, all resources with titles are treated as figures. This is discussed extensively later.

format : This is the resource format. Different resource types have different legal values for format. Specific resource types and formats are discussed throughout the rest of the spec.

title : If a resource has a title, it is a figure. This is discussed in the next section.

type : This is the resource type. This is usually inferred from the format instead of being specified.

5.3Resource titles make figures (M)

All resources with title attributes are figures.

This is true regardless of whether the title is specified in quotes, in an attribute list, or in the alt text (with the appropriate value of the alt-title document setting). In all cases, the resource is a figure.

To be clear, if alt-title is all (the default), the following three image resources are all figures, and should look identical:

![](mac.jpg "The Original Mac")

![The Original Mac](mac.jpg)

{title: "The Original Mac"}
![](mac.jpg)

The title is text which is shown near the figure, typically above or below it. A Markua Processor can choose where to position titles based on any criteria it chooses. For example, a Markua Processor can position all titles above or below figures, or use a different behavior based on the resource format (e.g. table titles above, image titles below).

Note that the figure title itself may contain Markua text formatting (e.g. bold, italic). This text is also displayed for the figure wherever the figure is listed (e.g. List of Illustrations, Table of Tables, etc.).

The title of a resource 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 title inserted near the figure itself.

The title of a resource used as a figure can be specified in three ways:

1. In an attribute list:

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

2. In quotes after the filename or URL of a local or web resource: ![](resource_path_or_url "Optional Figure Title")
3. In the alt text, assuming an appropriate value of the alt-title document setting. The alt-title document setting is discussed in great detail here.

Since inline resources do not use the bracket syntax, any titles must be added in the attribute list:

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

Note that an attribute list can also be provided after the resource, but this is discouraged since it is less readable:

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

If a resource has a title (provided by any of the above approaches), it is a figure.

If a resource does not have a title, it is inserted as a span. This is useful for images being added like an emoji, for example:

Here's a ![poop](poop.png) emoji.

Note that in this case, there is already a poop emoji, so this is wasteful as the emoji syntax can just be used instead. However, if you wanted to use an image of your favourite politician as a poop emoji, you wouldn’t have an emoji for that person built in, so this syntax would work in its stead.

Again, if a title was added, things would be different:

Here's a ![poop](poop.png "The Year 2022 So Far") emoji.

In this case, the resource would be a figure, and it would flow in the text as a figure.

But what if we wanted to specify image alignment for this resource? This could be done with an attribute list like this:

Here's a ![poop](poop.png "The Year 2022 So Far"){align: left} emoji.

Since the image resource has a title, it is being inserted as a figure, and it would flow in the layout like any other figure.

Specifically, this would be equivalent to the following:

Here's a
![poop](poop.png "The Year 2022 So Far"){align: left}
emoji.

This would also be equivalent to the following:

Here's a

![poop](poop.png "The Year 2022 So Far"){align: left}

{class: continued-para}
emoji.

This would also be equivalent to the following:

Here's a

![poop](poop.png "The Year 2022 So Far"){align: left}

^
emoji.

To be clear: inserting a figure inline in a sentence is equivalent to adding a single line break before and after it, which is also equivalent to adding a blank line before and after it with a class of continued-para on the paragraph after it, which is also equivalent to the syntactic sugar equivalent with a caret ^ on the paragraph after it.

However, this example is both contrived and terrible.

A much better way to write something like this is as follows, using the attribute list in its typical place above the resource:

Here's an emoji.

{align: left}
![poop](poop.png "The Year 2022 So Far")

Let's hope the year improves.

This is why almost all figures are added this way.

But just because that’s the convention, it does not make it the rule. That is semantically identical to the following:

Here's an emoji.

![poop](poop.png "The Year 2022 So Far"){align: left}

Let's hope the year improves.

Finally, if you are implementing a Markua Processor and are trying to determine the class of a resource, the following pseudocode algorithm can help:

What's the `class`?

if the class was explicitly set to something
  that's the class
elsif there is a title
  the class is `figure`
else
  the class is undefined
end

A resource with an undefined class has no title and is not a figure.

5.4Resource figure numbering (M)

NOTE FOR LEANPUB AUTHORS: The numbered attribute is not implemented in Leanpub yet. We plan to add this in 2024, after which point this note will be removed.

When a resource has a title, it is a figure.

By default, figures are numbered. This numbering is controlled by the number-figures document setting.

number-figures : chapter, none, or sequential. The default is sequential. If the value is chapter or sequential, then resources are numbered when they are inserted as figures. If the value is sequential, you get numbering like Figure 1, Figure 2, Figure 3, etc. If the value is chapter, you get numbering like Figure 1.1, Figure 1.2, Figure 4.1, etc. If the value is none, figures are not numbered.

If a resource does not have a title, it is not a figure, and it is not numbered.

If you do not want to number any of your figures, you can use the none setting of the number-figures document setting to have none of them numbered.

However, sometimes you may wish to number most of your figures, but not all of them. In other words, you may wish to give a resource a title (making it a figure), but not have that resource be numbered like a figure.

To do this, you can use the numbered: false attribute.

numbered : true or false. The default is true. This controls whether a particular resource is numbered. Note that if number-figures is none then no resources are numbered. The numbered attribute does not override this setting.

In other words, the numbered: false can force a figure to not be numbered (if figures are being numbered), but numbered: true cannot force a figure to be numbered if figures are not being numbered.

There is no reason to ever explicitly set numbered: true, since this is the default. The numbered attribute only exists so that it can be overridden to false, to explicitly turn off figure numbering for a particular figure.

Finally, if numbered is false on a figure, then there are the following consequences:

1. The figure will not show up in any list of figures, if there is one.
2. You cannot make certain kinds of smart crosslinks to it, since it has no number.

A resource without a number but with a title exists in a kind of limbo: it is not a full-fledged figure which is listed in a list of figures and can be easily referred to with smart crosslinks, but it’s also not not-a-figure: it is laid out like a figure, and can have a caption, etc.

5.5Resource alt text (M)

A resource can have alt text. The resource location does not matter: local, web and inline resources all support alt text.

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, and which may have a hard time displaying math.

Here’s an example of good alt text:

![a red apple, possibly a McIntosh or Spartan](fruit.jpg)

You can also use an attribute list:

{alt: "a red apple, possibly a McIntosh or Spartan"}
![](fruit.jpg)

The alt text should not have the same content as the resource figure title, if the resource title is present. (Imagine the annoyance for someone with a visual disability having their screen reader read identical alt text and figure titles to them throughout an entire book!)

Instead, the alt text should be descriptive of the image content, while the resource figure title can be more creative. For example, a figure title may be “Washington Crossing the Delaware” and the alt text could be “Denzel Washington on a boat in a river.” Having good alt text would enable readers who cannot see the image to still get the joke which the figure title makes.

Figure titles and alt text can, and should, be both added to resources. These are some examples of resources with both alt text and a figure title:

![a red apple](mac.jpg "The Original Mac")

{alt: "a red apple", title: "The Original Mac"}
![](mac.jpg)

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

5.6Resource types (M)

The type of a resource can be specified by the type attribute, or inferred from the format of the resource.

There are eight types of resources:

1. audio
2. code
3. iframe
4. image
5. math
6. table
7. verbatim
8. video

Each type of resource has a number of supported formats. Any of the 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.

The code, image and table resource types are an extension and a generalization of what is already supported in Markdown; the audio, iframe, math, verbatim and video resource types are new.

Either way, each type of resource has a number of supported formats. Any of the 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.

Resources are not parsed as plain textual content; instead, they are parsed according to the rules that govern the parsing of resources.

All of these types of resources are discussed later.

5.7Resource formats (M)

The Format is the format of the resource. It can be specified with the type attribute, or inferred from the file extension (discussed below). This is important information to help the Markua Processor handle the resource correctly.

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.

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

As an author, all you typically do is provide the correct file extension for a local resource 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. The file extensions just set the default type and format that are inferred.

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.

5.8Resource classes (M)

As shown above, when a resource is inserted with a title, it is treated as a figure. Figures can show up in one of the lists of figures which can be generated near the start of the book or course.

If a resource has a title and thus is a figure, and if figures are listed in groups (if the list-figures document setting is groups), the default is to group by the type of the resource. However, the class attribute can be used to override which list the resource appears in.

5.9Resource locations (M)

The Location is the location of the resource, when encountered by the Markua Processor. There is no attribute for this; it is inferred from the location.

• An inline resource is included directly in a Markua manuscript file.
• A local resource is located in the resources directory which accompanies the Markua manuscript (or in a similar conceptual location for a web-based Markua Processor).
• A web resource is on the web, accessed via http:// or https://.

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.

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

Here’s how the paths to local resources work:

1. An image called foo.jpg in the resources directory should be referred to as ![](foo.jpg), but can also be referred to as ![](resources/foo.jpg).
2. An image called bar.png in a subdirectory images of the resources directory should be referred to as ![](images/bar.png), but can also be referred to as ![](resources/images/foo.jpg).
3. For security reasons, leading slashes / and navigating upward (../) are not allowed: ![](/foo.jpg), ![](/images/bar.png) and ![](../foo.jpg) are all illegal.

The reason that paths can either include or omit the resources directory is simple: including it makes it a simple relative path, which means that Markdown-aware tools that support, say, external images will just work. However, omitting it is nice to type, so this is something which should be supported as well. And the reason the resources directory exists is to keep the Markua manuscript file(s) separate from the resources, to reduce clutter.

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) or as ![](resources/ch1/examples/ruby/foo.rb).

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, authors can do whatever they want. For example, you can create subdirectories of the resources directory for different types of resource, such as audio, code, images, etc., but you can also just put them all in the resources directory together. To be clear: the names of the directories have no meaning, and do not restrict the formats of what can go inside them.

If you are using a hosted service to write in Markua, this service can store resources wherever it wants. However, 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 containing an export should contain a resources directory which contains an images subdirectory with the images.

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

5.9.3Inline resources

Certain types of resources can be inserted inline in a Markua document:

• code
• image (of SVG format only, discussed later)
• list
• math (of latexmath or asciimath format, discussed later)
• table
• verbatim

7.6Code resources (M)

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.

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.

This way, the decision about the language recognized does not need to be done by the Markua Processor, but can instead be delegated to the syntax highlighter, such as Pygments.

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.

7.6.1Supported Attributes for Code

The following are the supported attributes for code resources, in addition to the class, format, title and type 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.

7.6.1.1Default 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, and whether the code is inserted as a span or as a block.

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

The default value of block code resources inserted with three backticks can be overridden from guess to some other value by setting by the default-code-language attribute on the entire Markua document. (This attribute has no effect on resources inserted with three tildes, or on code spans.)

7.6.2Local Code Resources

Local code resources can be inserted as a figure.

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

Here's a paragraph before the figure.

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

Here's a paragraph after the figure.

That is equivalent to:

Here's a paragraph before the figure.

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

Here's a paragraph after the figure.

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

Here's a paragraph before the figure.

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

Here's a paragraph after the figure.

Note that the title is optional in all figures:

Here's a paragraph before the figure.

![](hello.rb)

Here's a paragraph after the figure.

7.6.3Web 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:

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

That is equivalent to:

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

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

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

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

The great thing about inline code resources, either as spans or figures, is that they work the same way as they do in CommonMark and GFM, with small additions by Markua.

7.6.4.1No Attribute Lists or Format Specifiers on Indented Code Blocks

Indented code blocks are supported for compatibility with CommonMark and GFM. However, no attribute lists or format specifiers can be used. If you want to use them, use a fenced code block.

7.6.4.2Attribute Lists and Format Specifiers on Fenced Code Blocks

Fenced code blocks, discussed earlier, are how to insert inline code resources as figures. These can have attribute lists or format specifiers.

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

Some paragraph.

```
puts "hello"
```

Some paragraph.

That is equivalent to:

Some paragraph.

```guess
puts "hello"
```

Some paragraph.

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

Some paragraph.

```ruby
puts "hello"
```

Some paragraph.

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:

Some paragraph.

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

Some paragraph.

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

Some paragraph.

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

Some paragraph.

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

First, you can set it explicitly:

Some paragraph.

```text
puts "hello"
```

Some paragraph.

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

Some paragraph.

~~~
puts "hello"
~~~

Some paragraph.

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

```console
$ git init
Initialized empty Git repository in /path/to/repo
```

Finally, it’s important to note that when you are writing about other inline formats, such as SVG or AsciiMath, what you are really doing is creating a code resource. This is shown in the sections below, which discuss SVG and AsciiMath, but this applies more broadly.

7.6.4.3No Attribute Lists on Code Spans

Code spans (like puts foo) are discussed later in the spec. Code spans work just as in CommonMark and GFM. Since Markua adds attribute lists to code blocks, you may wonder whether Markua adds attribute lists to code spans.

So, to be clear: Markua does NOT support attribute lists on code spans.

So, in an example like the following, the attribute list is simply ignored:

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

The reason for this is simple: it does not make sense to run a syntax highlighter to format two or three words of code. If you want syntax highlighting, use a code block.

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

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

7.7Verbatim resources (M)

The verbatim resource type is used to preserve leading and internal whitespace while still supporting Markua text formatting (things like **bold** and *italic*).

While Markua text formatting IS supported inside a verbatim resource, Markua resources (including images) ARE NOT supported inside a verbatim resource. While this may seem arbitrary and overly restrictive, we need to prevent a slippery slope of expanded scope.

The following are the verbatim resource formats and the file extensions which choose them by default:

verbatim : verbatim text - .text

The primary use case is poetry, and the secondary use case is boilerplate legal text. If you don’t care about leading or internal whitespace, or about poetry or legalese, you can safely skip this section.

For a verbatim resource, leading whitespace, internal whitespace, and newlines must all be preserved verbatim as typed. This can be useful for certain types of poetry, such as indenting the last two lines of a sonnet.

To be clear:

• Trailing whitespace before a newline does not need to be preserved.
• This includes all leading and internal spaces and newlines regardless of the number of consecutive leading, internal or trailing spaces or the number of newlines.
• Again, to repeat, Markua text formatting is supported, but Markua resources are NOT supported inside a verbatim resource.

Now, while the whitespace is preserved, it is rendered using either a proportional font or a monospaced one based on the value of the monospaced attribute.

The verbatim resource 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 the text 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.

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

There are three main use cases for a Markua resource:

1. Inserting a specific class of resource, such as a poem.
2. Inserting boilerplate, such as a legal disclaimer, which may be needed to be used in many places and/or sourced from a third party.
3. Controlling the behavior of fonts or whitespace for specific types of text, such as poetry.

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

monospaced : true or false. The default is false. If true, the Markua Processor must use a monospaced font to output the text in the resource. If false, the Markua Processor may use whatever font (proportional or monospaced) it is configured to use to output Markua text. The value of true can be useful for certain types of poetry, for example.

Note that the standard class attribute should be used with a verbatim type resource to define a specific class of resource on verbatim resources which have titles, such as a poem. A List of Poems is a lot more poetic than a List of Verbatims.

Also note that the standard resource format attribute for a verbatim type resource must always be overridden to verbatim by a Markua Processor. Similarly, if a format of verbatim is specified, this must set the type to verbatim.

7.7.1Local Verbatim resources

Local and web resources with a .text extension default to being treated as a verbatim type of resource.

Here's a Shakespearean sonnet, which has a type of `verbatim` and a class of
`poem`:

{type: verbatim, class: poem}
![](sonnet130.txt "Sonnet 130")

Here's a Shakespearean sonnet, which has a class of `poem` and will default to
the `{type: verbatim}` because of the `.text` extension:

{class: poem}
![](sonnet130.text "Sonnet 130")

Here's a Shakespearean sonnet, which has no class specified and which will
default to the `{type: verbatim}` because of the `.text` extension:

![](sonnet130.text "Sonnet 130")

Here's some legal boilerplate, which has no class specified and which will
default to the `{type: verbatim}` because of the `.text` extension:

![](tos.text "Terms and Conditions")

Here's an E. E. Cummings poem:

{type: verbatim, class: poem, monospaced: true}
![](iwillbe.txt "I Will Be")

Here's an E. E. Cummings poem which has no class specified and which will
default to the `{type: verbatim}` because of the `.text` extension:

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

7.7.2Web Verbatim resources

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

Here's a Shakespearean sonnet, which has a type of `verbatim` and a class of
`poem`:

{type: verbatim, class: poem}
![](https://markua.com/sonnet130.txt "Sonnet 130")

Here's a Shakespearean sonnet, which has a class of `poem` and will default to
the `{type: verbatim}` because of the `.text` extension:

{class: poem}
![](https://markua.com/sonnet130.text "Sonnet 130")

Here's a Shakespearean sonnet, which has no class specified and which will
default to the `{type: verbatim}` because of the `.text` extension:

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

Here's some legal boilerplate, which has no class specified and which will
default to the `{type: verbatim}` because of the `.text` extension:

![](https://markua.com/tos.text "Terms and Conditions")

Here's an E. E. Cummings poem:

{type: verbatim, class: poem, monospaced: true}
![](https://markua.com/iwillbe.txt "I Will Be")

Here's an E. E. Cummings poem which has no class specified and which will
default to the `{type: verbatim}` because of the `.text` extension:

{monospaced: true}
![](https://markua.com/iwillbe.text "I Will Be")

7.7.3Inline Verbatim resources

Inline verbatim resources are the easiest way to insert verbatim resources.

These work just like fenced code blocks, discussed earlier, but with a verbatim format. (Recall from above that a verbatim format causes the type to also be verbatim.)

Here’s what this looks like with backticks:

Some paragraph.

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

Some paragraph.

You can also use tildes:

Some paragraph.

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

Some paragraph.

You can also use an attribute list:

Some paragraph.

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

Some paragraph.

But the best choice is to use the & syntactic sugar, which means {type: verbatim}:

Some paragraph.

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

Some paragraph.

To summarize, what a verbatim resource type means is…

1. whitespace is preserved verbatim
2. no automatic indenting is done
3. basic Markua text formatting (bold, italic, etc.) is applied
4. Markua resources (e.g. tables, images, etc.) CANNOT be nested inside it
5. you can add {monospaced: true | false} (default false)
6. it can be local, web, or inline resource
7. the format is verbatim, which can be inferred from a .text extension
8. the normal rules apply for the class attribute

7.7.4But what if I want every character taken literally?

If you want to type poetry where every character is taken exactly literally, instead of being potentially interpreted as Markua formatting, you need to use a code block with a format of text for that:

```text
*this* isn't italic
and **this** is not bold
* * * cherry blossoms * * *
```

<pre><code>*this* isn't italic
and **this** is not bold
* * * cherry blossoms * * *
</code></pre>

I’m no poet, but at least I know it.

7.8No HTML blocks (M)

As discussed, Markua does not support raw HTML. All raw HTML is removed. As a side-effect, this means HTML comments can still be used, since they (like all HTML) will be removed from the output.

7.12Tables (GFM)

GFM enables the table extension, where an additional leaf block type is available.

A table is an arrangement of data with rows and columns, consisting of a single header row, a delimiter row separating the header from the data, and zero or more data rows.

Each row consists of cells containing arbitrary text, in which inlines are parsed, separated by pipes (|). A leading and trailing pipe is also recommended for clarity of reading, and if there’s otherwise parsing ambiguity. Spaces between pipes and cell content are trimmed. Block-level elements cannot be inserted in a table.

The delimiter row consists of cells whose only content are hyphens (-), and optionally, a leading or trailing colon (:), or both, to indicate left, right, or center alignment respectively.

| foo | bar |
| --- | --- |
| baz | bim |

<table>
<thead>
<tr>
<th>foo</th>
<th>bar</th>
</tr>
</thead>
<tbody>
<tr>
<td>baz</td>
<td>bim</td>
</tr>
</tbody>
</table>

Cells in one column don’t need to match length, though it’s easier to read if they are. Likewise, use of leading and trailing pipes may be inconsistent:

| abc | defghi |
:-: | -----------:
bar | baz

<table>
<thead>
<tr>
<th align="center">abc</th>
<th align="right">defghi</th>
</tr>
</thead>
<tbody>
<tr>
<td align="center">bar</td>
<td align="right">baz</td>
</tr>
</tbody>
</table>

Include a pipe in a cell’s content by escaping it, including inside other inline spans:

| f\|oo  |
| ------ |
| b `\|` az |
| b **\|** im |

<table>
<thead>
<tr>
<th>f|oo</th>
</tr>
</thead>
<tbody>
<tr>
<td>b <code>|</code> az</td>
</tr>
<tr>
<td>b <strong>|</strong> im</td>
</tr>
</tbody>
</table>

The table is broken at the first empty line, or beginning of another block-level structure:

| abc | def |
| --- | --- |
| bar | baz |
> bar

<table>
<thead>
<tr>
<th>abc</th>
<th>def</th>
</tr>
</thead>
<tbody>
<tr>
<td>bar</td>
<td>baz</td>
</tr>
</tbody>
</table>
<blockquote>
<p>bar</p>
</blockquote>

| abc | def |
| --- | --- |
| bar | baz |
bar

bar

<table>
<thead>
<tr>
<th>abc</th>
<th>def</th>
</tr>
</thead>
<tbody>
<tr>
<td>bar</td>
<td>baz</td>
</tr>
<tr>
<td>bar</td>
<td></td>
</tr>
</tbody>
</table>
<p>bar</p>

The header row must match the delimiter row in the number of cells. If not, a table will not be recognized:

| abc | def |
| --- |
| bar |

<p>| abc | def |
| --- |
| bar |</p>

The remainder of the table’s rows may vary in the number of cells. If there are a number of cells fewer than the number of cells in the header row, empty cells are inserted. If there are greater, the excess is ignored:

| abc | def |
| --- | --- |
| bar |
| bar | baz | boo |

<table>
<thead>
<tr>
<th>abc</th>
<th>def</th>
</tr>
</thead>
<tbody>
<tr>
<td>bar</td>
<td></td>
</tr>
<tr>
<td>bar</td>
<td>baz</td>
</tr>
</tbody>
</table>

If there are no rows in the body, no <tbody> is generated in HTML output:

| abc | def |
| --- | --- |

<table>
<thead>
<tr>
<th>abc</th>
<th>def</th>
</tr>
</thead>
</table>

7.13Table resources and CSV-format tables (M)

Tables can be formatted either as Markua tables or, for tables which are local or web resources, as CSV-format tables. (CSV-format tables are not supported as inline resources, since they would result in too many false-positives.)

The type and format of a table can be specified in an attribute list as follows:

{type: table, format: markua}
![](some_markua_table.txt)

{type: table, format: csv}
![](some_markua_table.txt)

The default type of a csv format resource is table, so the second example could also be written like this:

{format: csv}
![](some_markua_table.txt)

However, the .csv file extension can also be used to provide the default format of csv, so this can also be written like this:

![](some_markua_table.csv)

Also, if no format is specified but the type is specified to table, the default is to assume a format of markua. So, the first example from above could also be written like this:

{type: table}
![](some_markua_table.txt)

As shown in the Tables section, the syntax to insert a table in Markua is the identical syntax to that used by GFM. (That section is unchanged from the GFM spec, which is built on top of the CommonMark spec.)

Just as Markua reinterprets Markdown concepts like images as being resources, Markua also reinterprets GFM tables as being a resource. This is important for two reasons, in the case of tables:

1. Resources can have attribute lists.
2. Resources can be inline, local or web resources.

So, Markua supports attribute list on tables, and tables which are inline, local or web resources:

• Inline means “in the document”; all tables in GFM are inline.
• Local means in the resources folder in a separate file, which can be helpful for keeping large tables from cluttering up your manuscript.
• Web means at some http or https URL.

Both local and web resources can be very useful for including data sourced from an external data source, as well as making them easier to keep correct.

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

align : The align can be left, right or middle. The default is middle. This works the same way it does for images. Note that it applies to the position of the entire table, not to the cells within it. 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, and that a Markua Processor may interpret center and/or centre as aliases for middle. (The value of middle was chosen because of the center vs. centre spelling issue.)

columns : Sometimes it’s desirable to only show part of a table resource defined in an external file. The rows and columns attributes let you accomplish this. The columns attribute can take a comma-separated list of values or ranges, such as 2, 4, 7..9, which would ensure that columns 2, 4, 7, 8 and 9 were shown.

column-spacing : The amount of space between table columns. The default is set by the default-table-column-spacing document setting, which defaults to 6pt. Some tables may need to have wider or narrower spacing than the document setting, so this attribute is provided to override that value.

column-widths : The column widths are a whitespace-separated list of numbers (integers and/or floats) and/or * symbols, 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. Some examples are: {column-widths: "10% 30% * 10%"}, {column-widths: "10% * 40% *"}, {column-widths: "10% 30% * 12.5%"}, {column-widths: "95% * *"}. The numbers used for the column-widths percentages must sum to exactly 100 (if only numbers are used), or to less than 100 (if there are any *s used). Every specified value must be at least 1, and every * must compute to at least 1. The number of values (numbers or *s) must match the number of columns. Like with the width attribute, the percentage sign (%) is required, to make it absolutely clear that these are not measurements in pixels or points.

footer : true, false or dynamic. The default is dynamic for markua format tables, and false for csv format tables. If dynamic, the existence of a footer is determined by whether the content of the table contains a footer. For a csv format table, true means that the last row is treated as a footer row, and false means that the last row is not treated as a footer row.

format : The format can be either markua (the default) or csv. The csv format can ony be used with local or web resources, to reduce false positives. CSV-format table resources are discussed in the next section.

header : true, false or dynamic. The default is dynamic for markua format tables, and true for csv format tables. If dynamic, the existence of a header is determined by whether the content of the table contains a header. For a csv format table, true means that the first row is treated as a header row, and false means that the first row is not treated as a header row.

rows : Sometimes it’s desirable to only show part of a table resource defined in an external file. The rows and columns attributes let you accomplish this. The rows attribute can take a comma-separated list of values or ranges, such as 1, 5, 13..18, 22, which would ensure that rows 1, 5, 13, 14, 15, 16, 17, 18 and 22 were shown.

width : The width of the table, in percentage of page content area width (respecting margins). This is specified as an number (integer or float) between 1 and 100 followed by a percentage sign (%). The quotes are optional. So, you can say {width: "70%"}, {width: 70%}, {width: "70.5%"} or {width: 70.5%}.

The examples below assume that a table which looks like the following (from the GFM table example above) is defined in a file called census.tbl (real census data would be too long for a good example):

| foo | bar |
| --- | --- |
| baz | bim |

<table>
<thead>
<tr>
<th>foo</th>
<th>bar</th>
</tr>
</thead>
<tbody>
<tr>
<td>baz</td>
<td>bim</td>
</tr>
</tbody>
</table>

With this table above defined in a file which is available at a local resource location, the following example results:

![](census.tbl "Canadian Census Data")

<figure>
  <table>
  <thead>
  <tr>
  <th>foo</th>
  <th>bar</th>
  </tr>
  </thead>
  <tbody>
  <tr>
  <td>baz</td>
  <td>bim</td>
  </tr>
  </tbody>
  </table>
  <figcaption>Canadian Census Data</figcaption>
</figure>

With this table above defined in a file which is available at a given web resource location, the identical example results:

![](https://markua.com/census.tbl "Canadian Census Data")

<figure>
  <table>
  <thead>
  <tr>
  <th>foo</th>
  <th>bar</th>
  </tr>
  </thead>
  <tbody>
  <tr>
  <td>baz</td>
  <td>bim</td>
  </tr>
  </tbody>
  </table>
  <figcaption>Canadian Census Data</figcaption>
</figure>

Table resources should be defined in a file with a .tbl extension. If the extension is different, then there must be a type: table attribute in the attribute list.

In the interest of brevity, some other examples of usage are below.

With the .tbl extension, the table type is inferred:

{title: "Canadian Census Data"}
![](census.tbl)

![](census.tbl "Canadian Census Data")

![Canadian Census Data](census.tbl)

{title: "Canadian Census Data", column-widths: "30% *"}
![](census.tbl)

{column-widths: "30% *"}
![](census.tbl "Canadian Census Data")

{column-widths: "30% *"}
![Canadian Census Data](census.tbl)

With a non-.tbl extension, the table type must be specified:

{type: table}
![](census.txt "Canadian Census Data")

{type: table, title: "Canadian Census Data"}
![](census.txt)

{type: table, title: "Canadian Census Data", column-widths: "30% *"}
![](census.txt)

Recall that the resource syntax is as follows:

{key: value, comma: separated, optional: attribute_list}
![optional alt text](resource_path_or_url "Optional Figure Title")

Note that there is some flexibility in the title attribute. If the alt-title document setting is text or all (the default) , then the alt text can be used as the title as well. If the alt-title is none, then it cannot. The alt-title document setting is discussed in great detail here.

So, assuming a value of text or all for a document setting, this also works:

![Canadian Census Data](census.tbl)

(This is arguably the nicest looking version, and since tables are a text resource there are no accessibility concerns about there being no alt text.)

This syntax can be used with an attribute list, of course:

{type: table}
![Canadian Census Data](census.txt)

Finally, if there is both alt text and a title attribute, the alt text is clobbered by the title:

{align: middle, width: 80%, title: "Canadian Census Data"}
![some alt text which gets clobbered by the title](census.tbl)

As discussed above, tables (i.e. resources of type table) which are local or web resources can have a csv format, instead of the default markua format.

For a csv-format table, the existence of a header and/or footer row cannot be inferred from the data, and must be specified in an attribute list. The default value of header is true, and the default value of footer is false.

Also, as discussed, a csv table can have rows and columns attributes, for easily presenting a subset of a larger CSV. If rows and columns are used with header of true, the header should be displayed by the Markua Processor.

Examples:

{type: table, format: csv}
![Canadian Census Data](census.csv)

{type: table, format: csv, title: "Canadian Census Data"}
![](census.csv)

{type: table, format: csv}
![](census.csv "Canadian Census Data")

{type: table, format: csv, header: true}
![Canadian Census Data](census.csv)

{type: table, format: csv, header: true, footer: true}
![Canadian Census Data](census.csv)

{type: table, format: csv, header: true, footer: true, rows: 1..5, columns: 2,3}
![Canadian Census Data](census.csv)

8.2Block quotes with curly braces (M)

Block quotes in Markua are created in one of two ways:

1. By prefacing lines with > , i.e. a greater than character followed by a space. This was shown above.
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 are the two ways to make block quotes in Markua:

This is the first paragraph.

> This is a blockquote.
>
> You saw this above.

This is the second paragraph.

{blockquote}
This is also a blockquote.

It is good for longer quotes.
{/blockquote}

This is the third paragraph.

<p>This is the first paragraph.</p>
<blockquote>
<p>This is a blockquote.</p>
<p>You saw this above.</p>
</blockquote>
<p>This is the second paragraph.</p>
<blockquote>
<p>This is also a blockquote.</p>
<p>It is good for longer quotes.</p>
</blockquote>
<p>This is the third paragraph.</p>

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