Using Scrivener with MultiMarkdown (MMD) files

This is a pretty specialized article for people who wrote, or plan to write, their novel using Scrivener and MultiMarkdown files (which end in .mmd) and who want to export them to .mobi format for Kindle. Expect this to get technical, right down to running programs from your computer’s command line. If this all sounds like gobbledegook, now’s a good time to read another section.

What follows is a tiny, inadequate overview of how MultiMarkdown works and why you might wish to use it. If you already know why you’re here, feel free to skip ahead to [Scrivener’s workflow is different with MultiMarkdown][ScrivenerMMDWorkflow].

MultiMarkdown files are nothing but plain, slightly ugly-looking text files that look something like this:

# Chapter 1

She was not where she expected to be. That much was clear.

When “compiled” (which is the way Scrivener converts your files to ebook form) the # character on its own line, followed by a space, followed by text, gets converted to an HTML <h1> header tag, two ## characters using the same convention get converted to an HTML <h2> header tag, and so on.

Why use MultiMarkdown?

If you’ve ever had the problem of pasting from your email program into your word processing document (or vice versa) and seeing how the formatting got screwed up, you’ve seen why a simple formatting style like MultiMarkdown helps with big projects.

MultiMarkdown is a plain text format. It uses simple formatting rules that are easy to view when typing in any text editor. It is stored in standard text files, which makes it easy for other programs to translate. This makes MultiMarkdown ideal for larger projects, say, more than 10 pages.

Large projects usually require a firm grip on formatting that’s consistent, predictable, and easy to change in bulk. MultiMarkdown was built for that purpose.

[ScrivenerMMDWorkflow]:

Scrivener’s Compile workflow is different with MultiMarkdown

When you create an eBook using Scrivener, you’re probably used to steps that look like this:

From the File menu, choose Compile.
From the Format as dropdown, choose E-book.
From the Compile for dropdown, choose Kindle eBook (.mobi)

Click the Compile button, and a few moments later you have a single eBook file ready to submit to Amazon (in this example).

Scrivener can’t compile eBooks from MultiMarkdown so there are extra requirements

Scrivener doesn’t yet create eBooks from MultiMarkdown files. You have to export to MultiMarkdown format. Then you need a third-party converter from the command line such as pandoc to translate from the MultiMarkdown files to ePub format, which is used by most eBook publishers other than Amazon. Finally, you use Amazon’s Kindlegen to convert from ePub format to .mobi, which is the finished version used by Amazon’s Kindle readers. The workflow then becomes something like this:

Install Fletcher Penny’s MultiMarkdown. This only needs to be done once. Details follow)
Install pandoc (details follow)
From the File menu, choose Compile
From the Format as dropdown, choose Custom
From the Compile for dropdown, choose MultiMarkdown. This option only exists if you’ve already installed MultiMarkdown. You may wish to give it a name ending with with .mmd, such as mynovel.mmd
Run the resultant MMD file through pandoc to create the the ePub file
Run the ePub file through KindleGen to convert from the ePub format to .mobi, which is what Kindle readers use.
Optionally, see how it will look when published using the Kindle Previewer. Kindle Previewer adds two additional steps:
Install Kindle Previewer, and if necessary,
Install the Java SE 6 runtime (required for some later versions of MacOS; see (https://www.amazon.com/gp/feature.html?docId=1000765261) if that’s still a requirement. The Java SE 6 runtime is a program the Kindle Previewer requires to run properly.

Using Scrivener with MultiMarkdown (MMD) files

Why use MultiMarkdown?

Scrivener’s Compile workflow is different with MultiMarkdown

Scrivener can’t compile eBooks from MultiMarkdown so there are extra requirements

Extra requirements for MultiMarkdown

Further reading