Introduction

The Magical Typewriter

Imagine you owned a magical typewriter.

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

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

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

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

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

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

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. Or, if you wanted to work with a designer or publisher, you could press a different key to generate InDesign. They could then use this as a starting point for producing a beautiful print book.

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 a massive open online course (MOOC) 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 source, 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 user manual.

How to Write a Novel in Markua

The Markua Manual is long. However, the amount you need to learn to get started 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* and **bold**.

* * *

That was a thematic break. "This is in quotes."

# Chapter Two

This is a paragraph in a new chapter.

Specifically, these are the rules:

Paragraphs are separated from other paragraphs by blank lines. (To add a blank line, add two consecutive newlines.)
To make a chapter heading, start a line with a pound sign (#), followed by a space and the name of the chapter.
To add a thematic break (also known as a scene break), put three asterisks (* * *) on a line with only whitespace.
Chapter headings and thematic breaks are separated from paragraphs by single newlines or blank lines. Blank lines are preferred for readability.
By default, single newlines in paragraphs turn into single spaces in the output, so you can manually wrap your paragraphs with newlines if you want. It’s optional, however, and typically a waste of time.
Use *one asterisk* for italic and **two asterisks** for bold.
All other text and punctuation is typed normally.

That’s it!

How to Write a Computer Programming Book in Markua

The following example shows basically everything you need to know to write a computer programming book in Markua:

# Chapter One

This is *italic* and **bold**.

Here's an image:

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

## Section One

You can have bulleted and numbered lists, including nested lists:

1. foo
   a) lorem
   b) ipsum
2. bar
   * stuff
   * more stuff
3. baz

### A Sub-Section

You can even have definition lists!

term 1
: definition 1a
: definition 1b

term 2
: definition 2

## Another Section

Tables work too:

| Header 1  | Header 2  |
| --------- | --------- |
| Content 1 | Content 2 |
| Content 3 | Content 4 |

You can have external code samples:

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

You can also inline code samples:

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

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

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

Finally, you can do that with math `d = v_i t + \frac{1}{2} a t^2`$ too.

As you can see, there is more syntax, including bulleted and numbered lists, definition lists, tables, block quotes, external and inline code samples, inline math, etc. However, even with all this, the Markua document remains readable. Exactly how all of this syntax works is explained later.

How to Write a Course (MOOC) in Markua

To write a course in Markua, you can start from scratch or from a book manuscript already formatted in Markua. Literally, all you need to do to turn a book written in Markua into a course is to add some quizzes.

The following is a complete course, written in Markua:

# Lesson One: Markua

## Section One

Lessons can have sections (and sub-sections, etc.) just like book chapters.
You can use the same headings as you do for book chapters and sections.

This exercise shows two multiple choice questions.

{exercise, id: exercise1}
? How many letters are in the word Markdown?

a) 6
b) 7
C) 8

? How many unique letters are in the word CommonMark?

a) 6
B) 7
c) 8
{/exercise}

## Section Two

This quiz shows a multiple choice question and a fill in the blank question.

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

a) 5
B) 6
c) 7

? How many unique letters are in the word Markua?

! 5
{/quiz}

# Lesson Two: Geography

This quiz shows two fill in the blank questions, with multiple answers and with a regex answer.

{quiz, id: quiz2}
? What's the global capital of investment banking?

! New York
! London

? Where's the Eiffel Tower?

! /(Paris|France)/i
{/quiz}

As this example shows, the syntax for writing normal content is the same as for books. All that’s different is the addition of quizzes and exercises.

Quizzes and exercises have the same type of content. However, with quizzes the marks count toward your mark in the course, and with exercises they don’t count. For MOOCs, Leanpub currently supports multiple choice and fill in the blank questions.

A multiple choice question has 2 or more answer choices, and 1 correct answer choice. The correct answer choice is in a capital letter; incorrect answer choices have lowercase letters.

A fill in the blank question consists of a question and a set of answers. You can even use regular expressions for the answers.

As explained later, there are more types of questions, and more options with these types of questions. However, what is shown above is enough to create a full MOOC out of a Markua book.

Markua: Markdown for Books and Courses

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

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

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

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

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

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

Markua is a plain text format. Markua is basically Markdown, minus all inline HTML except comments, plus a number of extensions to support everything you need to write a book or create a course.

Markua manuscripts, called Markua documents, can be written however you want. On a computer, you can use any text editor you want. Beginning authors can use simple programs like Notepad or TextEdit or “distraction-free” programs like iA Writer; authors who are programmers can use editors like Emacs, Vim, Atom or VSCode. Since Markua is very similar to Markdown, many programs which support Markdown should already do a decent job of supporting Markua by default.

Leanpub has 5 different writing modes:

GitHub
Bitbucket
Dropbox
In-Browser Text Editor
Bring Your Own Book

You can write in Markua in GitHub, Bitbucket, Dropbox and the In-Browser Text Editor writing modes. You can’t write in Markua in the Bring Your Own Book writing mode, since you are just uploading already-generated ebooks in PDF, EPUB and/or MOBI.

(Leanpub also has two deprecated writing modes, our Google Docs writing mode and our Visual Editor writing mode. Neither of these can be used to write in Markua: instead, they are WYSIWYG.)

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

Markua documents can be automatically transformed by Leanpub into every popular type of ebook format. Leanpub can output PDF, EPUB, MOBI 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 massive open online courses (MOOCs).

Markua’s three main contributions are the following:

The mapping of Markdown headings (h1, h2, h3, etc.) to book structures (parts, chapters, sections, sub-sections, etc.), which provides the ability for Leanpub to produce an ebook from a Markua manuscript with one click.
The unified resource and attribute list syntax, which lets Markua handle audio, code, math and video in the same way that it does images, and which supports inline, local and web resource locations.
The mapping of book structures to courses, and the creation of a plain-text based microformat for course quizzes and exercises, which supports automated marking and automated production of everything which is required for a MOOC.

If you have written something (say blog posts or lecture notes) in Markdown, you can use 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 Markdown somehow grew an understanding of book and course concepts.

Why the Name “Markua”?

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.

The Markua Manual vs. The Markua Spec

This is the Markua Manual. Its purpose is to explain how to write in Markua on Leanpub.

You will want to read this book if:

You are a Leanpub author.
You are writing in Markua, or are considering switching to Markua from Leanpub Flavoured Markdown.
You want to see how to write in Markua on Leanpub today.

This book explains how to use the parts of Markua which CURRENTLY work on Leanpub:

Everything you read about in this book should just work.
Everything in Markua which is not yet supported on Leanpub is just omitted, as though it does not exist.

The formal specification of Markua is contained in a separate document called The Markua Spec. It is available on the Markua website.

To be clear: the document you are currently reading describes the behaviour of the Markua Beta in Leanpub. This behaviour is occasionally DIFFERENT than what is specified in the latest version of The Markua Spec. When The Markua Spec is fully implemented in Leanpub, we plan to provide migration tools to update your books from the Markua Beta to the latest version of Markua.

The Markua Spec is based on the GitHub Flavored Markdown (GFM) Spec, which is based on the CommonMark Spec. The author of the CommonMark Spec is John MacFarlane. In the Markua Spec, Markua is specified as a set of modifications to CommonMark, for ease of comparison with CommonMark.

You may want to read The Markua Spec if:

You are a computer programmer.
You like reading specs.
You want to see a mapping of Markua to HTML.
You want to see every planned feature in Markua, not just what works in Leanpub today.
You want to see the planned differences with the previous and current versions of Markua on Leanpub, including any differences with what is explained here.

Markua 0.10 and Markua 0.29

Leanpub currently implements Markua 0.10, which is what is documented in this manual. So, whenever this manual says “Markua” without a version specified, Markua 0.10 is intended.

Leanpub will eventually support Markua 0.29, which is specified at http://markua.com/, but there is a lot of work to do first before even a beta of Markua 0.29 support can be launched.

Markua 0.10 will still be supported on Leanpub for years after the Markua 0.29 beta is launched.

Differences with Leanpub Flavoured Markdown (LFM)

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

Leanpub Flavoured Markdown (the predecessor of Markua on Leanpub) is basically Markdown plus some extensions minus inline HTML. So, Markua and Leanpub Flavoured Markdown are similar in that regard, in that neither supports inline HTML. To be clear, Leanpub does not support inline HTML, regardless of whether you use Markua or Leanpub Flavoured Markdown.

Leanpub Flavoured Markdown will still be supported on Leanpub for years after the Markua 0.29 beta is launched.

LFM supports the Setext style of Markdown headers (===== and -----) as well as the atx style of Markdown headers (# Chapter, ## Section, etc.) Leanpub’s implementation of Markua 0.10 only supports atx headers. Leanpub’s implementation of Markua 0.29 will support the Setext and the atx style of Markdown headers. So, if you have an existing Markdown document with a lot of Setext headers, you may be better off sticking with LFM for now. (If, on the other hand, you’ve never heard of Setext headers and/or you don’t use them, this will not be an issue for you.)
In Leanpub’s implementation of Markua 0.10, a single newline in a paragraph is always a forced line break. This was a mistake, and it should have been configurable. For the reasoning about why a single newline is a forced line break, see this. In LFM, a single newline is handled the way that it is done in Markdown: it is treated as a single space, and not as a forced line break, unless the “two space hack” at the end of the line is used. Leanpub’s implementation of Markua 0.29 will support configurable handling of single newlines, to be either treated as forced line breaks or as the way that they are treated in Markdown. So, if you have an existing Markdown document with a lot of single line breaks which you had added just to manually wrap paragraph text in your manuscript, you will DEFINITELY be better off sticking with LFM for now.
In LFM, parts are created with -#. In Markua, parts are created with # Part # now, and will be created with an attribute list on an atx or Setext heading in future.
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 with its own syntax for inserting from external files, and the LFM syntax is not supported.
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.
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.
In LFM, there are G> “generic boxes”. In Markua, these are replaced with blurbs (B>).
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.
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 is sufficient.
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.)

Besides these differences, there are a number of smaller ones, which you will discover if you compare the Markua Manual to the Leanpub Flavoured Markdown Manual.

Throughout the Markua manual, when I say “Markdown” I mean the format originally defined by John Gruber, best-specified by CommonMark and extended by formats such as GitHub Flavored Markdown. If I ever want to refer to Leanpub Flavoured Markdown, I will do so by saying “Leanpub Flavoured Markdown” or “LFM”, not just “Markdown”.

Acknowledgments

I (Peter Armstrong) am the creator of Markua. However, I’m standing on the shoulders of giants. Most important, Markua is built on Markdown. So, Markua literally would not exist without John Gruber and Aaron Swartz. Markua is now also using the CommonMark spec as its starting point, so I am really grateful to John MacFarlane (the author of the CommonMark spec) and the team behind CommonMark and cmark. I’m also really grateful to GitHub for adopting Markdown, for basing the GitHub Flavored Markdown spec on the CommonMark spec, and for their work on cmark-gfm.

Markua is also benefitting from years of feedback about Leanpub Flavoured Markdown and Markua, from many incredibly helpful and patient Leanpub authors. If it wasn’t for these authors, there would be no Leanpub, and no Markua.

I’d also like to thank my father, who read some of the very early manuscripts when this was a standalone spec and gave me feedback.

Finally, I would like to thank my wife Caroline and my son Evan: while this is not as long as my other books, a lot of thought and effort went into it, and a lot of sacrifice. Thanks very much.