The Markua Specification
The Markua Specification
Minimum price
Suggested price
The Markua Specification

This book is 98% complete

Last updated on 2019-04-16

About the Book

Imagine you owned a magical typewriter.

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

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

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

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

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

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

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

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

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

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

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

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

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

This simple format is called Markua.

This is its specification.

About the Author

Peter Armstrong
Peter Armstrong

Peter Armstrong is the co-founder and CEO of Leanpub. He has almost two decades of experience in software, half of it as a developer at Silicon Valley startups. He founded Ruboss in 2008, and created Leanpub with Scott Patten in 2010.

Peter is also the author of 7 books: Yoshidaguchi, Your First Trip to Japan, The Markua Specification, Programming for KidsLean Publishing, Flexible Rails and Hello! Flex 4. He has a BSc in Computer Science and Psychology from the University of Victoria.

Peter coined the term "lean publishing" to describe the act of self-publishing an in-progress ebook. Leanpub was created based on the principles of lean publishing. He lives in Victoria, BC with his wife and son.

Bundles that include this book

The Markua Specification
Suggested Price
Bundle Price
The Markua Specification
Suggested Price
Bundle Price

Table of Contents

  • The Magical Typewriter
  • Overview
    • Note for Leanpub Authors
    • What is Markua?
    • How to Write a Novel in Markua
    • Minimal Formatting
    • Markua: Markdown for Books
  • Text Formatting
  • Headings
    • Design Goals of Markua Headings
    • Differences with Markdown Headings
      • Setext Headings in Markdown
      • atx Headings in Markdown
  • Paragraphs and Blank Lines
  • Resources
    • Resource Insertion Methods
      • Figures
      • Spans
      • Inserting Resources Into a Span Context
    • Resource Locations
      • Local Resources
      • Web Resources
      • Inline Resources
    • Resource Types and Formats
      • Images
      • Video
      • Audio
      • Code
      • Poetry
      • Math
      • Tables
  • Whitespace: Spaces, Tabs and Newlines
    • Newlines
      • Single Newline = Forced Line Break
      • Three or More Newlines = Two Newlines = One Blank Line
      • One Blank Line Is Added When Concatenating Manuscript Files
      • All Blank Lines at the Beginning and End of a File are Removed
    • Spaces and Tabs
      • Spaces and Tabs at the Beginning of a Line are Only to Determine List Containment, and Extra Spaces are Removed
      • Spaces and Tabs at the End of a Line are Removed
      • Internal Spaces are Collapsed to One Space, Except At the End of Sentences
  • Lists
    • Bulleted Lists
    • Numbered Lists
      • In Markua, There Are No Single-Element Numbered Lists
      • Numbered List Numbering Rules
    • Simple Lists
    • Flat Lists
    • Complex Lists
      • Blank Lines in Complex Lists
      • Parsing of Inline Code Resources Inside List Items
  • Definition Lists
  • Block Elements
    • Scene Breaks (* * *)
    • Page Breaks (===)
    • Blockquotes (>)
    • Asides (A> or {aside})
    • Blurbs (B> or {blurb})
      • Supported Attributes for Blurbs
      • Syntactic Sugar for Specific Blurb Classes: D>, E>, I>, Q, T, W>, X>
      • Using Blurbs to Center Text with C>
      • Using Extension Attributes on Blurbs to add icon Support
    • Inserting Block Elements Inside Paragraphs
  • Quizzes and Exercises
    • Quiz and Exercise Headings and Other Content
    • An Empty Quiz or Exercise is Not an Error
    • A Malformed Quiz or Exercise is an Error
    • Supported Attributes on Quizzes and/or Exercises
    • Question Types: Multiple Choice, Multiple Selection, Fill In The Blank, Written
      • Multiple Choice Questions
      • Multiple Selection Questions
      • Fill In The Blank Questions
      • Written Questions
      • Hints on Questions
    • Markua Processor Behaviour
    • Creating a Course or MOOC from a Markua Document
    • Question Alternates
  • Span Elements
    • Links
      • Inline Links
      • Automatic Links
    • Explicitly Creating Spans with []
      • Sometimes a Square Bracket is Just a Square Bracket
    • Footnotes and Endnotes
      • Footnotes
      • Endnotes
      • Single Reference to Footnotes and Endnotes
      • Footnotes and Endnotes Support Required for Paragraphs Only
    • Crosslinks and ids
      • Defining an id
      • Referencing an id With a Crosslink
      • Rules for ids and Crosslinks
      • Referencing Chapter, Section and Figure Heading Names and Numbers in Crosslinks
    • Character Substitution (X-- for X—, X -- for X –, ... for …)
      • Optional Automatic Curly Quotes Outside of Code Blocks and Spans
    • Placeholders
      • Placeholder Identifiers
      • Span Placeholders
      • Block Placeholders
    • Soft Hyphen
    • Escaping Special Characters with Backslash (\)
    • Code Spans and Backticks (`)
    • Unicode Entities with \u
    • Emoji
    • CriticMarkup
  • Metadata
    • Attributes
      • Attribute List Format
      • Attribute Keys
      • Attribute Values
      • id Attributes
      • title Attributes
      • Conditional Inclusion Attributes on Headings: book, sample, etc.
      • Extension Attributes
    • Index Entries
    • Directives
      • The lang Directive
      • Book Section Directives
    • Settings
      • Markua-Defined Settings
      • Settings for Courses
  • Appendices
    • Origins of Markua
    • Why the Name “Markua”?
    • Plain Text Encoding in UTF-8
    • No Inline HTML
    • Markua Specification Scope
    • No Canonical HTML Mapping
    • Differences with Markdown
      • Differences with Inserting Block Elements Inside Paragraphs
    • Differences with Leanpub Flavoured Markdown
    • Example of Why One Blank Line Is Added When Concatenating Manuscript Files
    • Markua Specification Status
    • A Note For Leanpub Authors
  • Acknowledgments

The Leanpub 45-day 100% Happiness Guarantee

Within 45 days of purchase you can get a 100% refund on any Leanpub purchase, in two clicks.

See full terms...

Write and Publish on Leanpub

Authors, publishers and universities use Leanpub to publish amazing in-progress and completed books and courses, just like this one. You can use Leanpub to write, publish and sell your book or course as well! Leanpub is a powerful platform for serious authors, combining a simple, elegant writing and publishing workflow with a store focused on selling in-progress ebooks. Leanpub is a magical typewriter for authors: just write in plain text, and to publish your ebook, just click a button. It really is that easy.

Learn more about writing on Leanpub