And that’s ok!

LeanPub

First and foremost: LeanPub is both an online shop and a writing plus publication platform.
It’s based on the idea of Lean Publishing according to which books are published ‘unfinished’ using agile tools and iterated over considering the reader’s feedback, updating the publication whenever the topic at hand requires it.

If any of this sounds familiar it’s probably because it stems from the Agile philosophy, which makes it very enticing to publishers and/or authors related to the IT space.

Format

Knowing the kind of people that use this service the most, it shouldn’t surprise you that the author is expected to write in Markdown, which is then used behind the scenes to generate the files that are offered to the public (PDF, EPUB and MOBI).

Specifically they use ‘Lean Flavored Markdown’ and more recently Markua (not quite the same, but not too different), they even have a manual for this last one.

Problems… or not

It’s always useful to understand the tool being used.
If you are facing issues and getting frustrated with LeanPub as an author, you might want to reconsider what’s the aim of this service.

With that out of the way, there are some valid criticisms floating around the web:

• In some cases it might be excessively slow, especially given that you might have to render the book over and over to ensure adequate formatting.
• There are some bugs (as all software has) that can get somewhat tiresome.
• It’s a remote process. This means that the authors (often developers) can’t modify the behavior nor solve issues on their own.
• They have an API, but it’s exclusive for Pro accounts.
• As you might have guessed, it ain’t FOSS.

So, what alternatives do we have?

All roads lead to Pandoc

A quick web search will return tons of services and apps that offer to convert your markdown to PDF, HTML, DOCX, EPUB, etc.

After not much research, it’s clear that Pandoc is the center of all file conversion to and from all sorts of formats.

It has quite a few wrappers for converting between all kinds of file types simply by running a well-thought-out command:

pandoc -f INPUT-FORMAT -t OUTPUT-FORMAT INPUT-FILE -o OUTPUT-FILE

It’s a very well known, trusted and fundamental tool for workflows that rely heavily on document management, formatting and/or conversion.

Not only that, the vast majority of tools and services that offer file conversion capabilities are simply Pandoc with a fresh coat of paint: At a low level they rely on this software to offer their services.

Markdown

It might seem a little weird at first, but it’s hard to think of a more comfortable language to compose text with.

The issue is, everyone seems to implement Markdown however they please and unfortunately the implementations we are concerned with (Markua) aren’t exactly widely used, so we can’t count on Pandoc coming to the rescue.
At least not directly.

Luckily it turns out that the variations used by LeanPub are direct supersets of Commonmark, a much more widely used format with its own Pandoc wrappers. With any luck this command will get you close to what you’re after.

1

pandoc -f commonmark_x -t pdf yourBook.md -o yourBook.pdf

If it doesn’t, you might have to resort to sed (or some similar tool) to parse the given markdown to a more comprehensible format for Pandoc to process.
Although even this might not be enough.

Keep in mind that Markua was created specifically with book drafting in mind and to avoid the need for further processing.
You might not find another Markdown flavor that’s good enough for your use case.

Where’s my standard?

If you made it down here you might be wondering why there’s no actual Markdown standard.

The closest thin we have is Commonmark, and it’s actually been widely adopted.
However, Markdown is a language born to make life easier for whoever is using it (not for a machine) and not everyone using it will necessarily have the same needs.

The purpose of the language is to be lax enough to adapt to the requirements of any given circumstance.

A rigid syntax would, at the same time, be of little use for a majority of cases, and defeat the purpose of Markdown all together.

Digging deeper

If you can’t quite find a formatting solution that fits your need, there’s a chance you are looking at this issue the wrong way around.

You can evaluate using LaTeX macros directly in your source files.
Pandoc should understand them and this opens up endless possibilities.
Be prepared to have this kind of syntax in your files:

1
2
3
4
5
6
7
8
9

\renewcommand{\vec}[1]{\mathbf{#1}}
The gravitational force 
$$\vec{g}$$
The gravitational force 
$$\mathbf{g}$$
And with some code:
~~~{.cpp .numberLines startFrom="1"}
class A {}; 
~~~ 

Some find this method to be a bit much, and prefer a more bare-bones approach.
If that sounds like you, try your luck with typesetters (groff, troff, roff, etc.).

This is a very different approach to writing but will give you absolute control over the look and feel of the document.

Whichever one of these you chose, be prepared to learn some arcane spells if you decide to go down this rabbit hole!