Writing a Novel Using Markdown: Part One

This story begins with a person like me. When I publish ebooks, I want them to turn out exactly as I intend. That means taking the text of the story, sandwiching it with front matter (like copyright) and more text at the end (like acknowledgments).

Until recently, I wrote my books using the word processor Apple Pages. I would export this to a Microsoft Word document for my editors and proofreaders. Then, when the book was ready to be converted into an ebook, I would do a lot of the work by hand.

And therein lies the problem. There’s a lot of manual effort involved when you take a Word document and produce something that Amazon or iBooks will accept as an ebook.

In this post I’m going to talk about using plain text files to consistently and painlessly produce ebooks. I won’t assume much knowledge.

Styling Text

There should be a separation between style and content. Style is font size, paragraph spacing, and all that jazz. The content is the text itself. Word processors like Pages or Microsoft Word combine style and content into a single file. These files are complex, contain ambiguities, and are difficult to read without a working copy of the program that produced them.

When you separate style and content, many advantages result. The content file doesn’t need to be in a proprietary format. It can be plain text. The content file will be easily read by a computer, which means the computer can automate certain things for you: create an ebook, a nice-looking PDF, a PowerPoint presentation, a web page…all from the same content file.

But how do you make the content file?

Use Markdown

Markdown was created by John Gruber as a way of writing for the web without including the distraction of mark-up tags (more below). It has been extended by subsequent programmers.

The best way to describe Markdown is to show you an example. Here is the opening of my novella, Red Star Falling:

## Red Star Falling

In the moment before Saskia Brandt awoke, she had a vision of red chrysanthemums falling. The flowers looked unreal. Their stems were too straight and their falls too slow. Their *Gestalt* was artful sadness.

What you’re looking at above is a plain text snippet. The # character means that the text Red Star Falling should be treated as a heading (just like a heading in Word). Two ## characters means that this is a heading level two. Immediately, you can see that this is a foolproof way of telling a computer that the text is heading level two; at the same time, it’s easy for a human to read.

After

## Red Star Falling

there is a blank line. This tells the computer to treat the next text it encounters as the beginning of a new paragraph. Notice that, in this new paragraph, I’ve used a

*

character to enclose the German word Gestalt. This tells the computer to emphasise the word. In this case, it makes it italic.

OK. So I’ve written the first paragraph of my glorious story. What do I do with it?

Well, the Amazon Kindle format is based on HTML, which is the simple tagging format that most webpages use. So I want to produce HTML from the Markdown. There are many tools that will help you do this. I’ll talk about some of them later. When I convert the above text to HTML I get the following:

Red Star Falling

In the moment before Saskia Brandt awoke, she had a vision of red chrysanthemums falling. The flowers looked unreal. Their stems were too straight and their falls too slow. Their Gestalt was artful sadness.

If you’re not familiar with HTML, this will look a bit weird. The important thing to note is that the original Markdown format text will reliably produce the HTML.

Why this is exciting

How much do I love Markdown? Let me count the ways.

  1. The thing that I, as a writer, look at, is a plain text file written in Markdown. It doesn’t get much simpler. I don’t need to worry about smart quotes and dash sizes–all this is done when creating the HTML.

  2. Because it’s a plain text file, I can work on it from a computer of virtually any type (desktop, laptop, mobile), any age (even ancient PCs can read text files) and any platform (plain text files are very portable).

  3. Helper programs can take this Markdown put it into any form I like: PDF, .mobi, epub, and so on. It can take some time to set up these helper programs, but you only have to do it once.

  4. In ten years’ time, the file will be super easy to open. It’s plain text, not a proprietary word-processing format.

My Workflow

Most of my writing takes place on two devices: A MacBook Air and an iPad. My workflow is therefore Mac-centric. However, the approach should work on any system.

Here is the point where I realise that my own workflow files are hopelessly hard-coded to my own system, and providing you with a working example of Red Star Falling that you can download and play with is impossible without editing my files. So, instead of giving you these files, I’ll explain the process in plain English.

  • My book is a series of plain text files, all of which are in Markdown format. Each file represents a section of the book that I’ve isolated for convenience. (Note that file number six is actually an alias to a file held in a more central central location, which is the same across all my books.)

image

I’ve now written a follow-up to this post that includes a detailed example.

Useful resources

A Markdown cheatsheet.

My Writer as a Stranger CSS (Cascading Style Sheet). Use this in combination with a Markdown document to produce a book with the same final formatting as Red Star Falling.

Markdown tools from Brett Terpstra.

Published by Ian Hocking

Writer and psychologist.

Join the Conversation

34 Comments

  1. If people are comfortable using markdown and want to skip a step or two, it is also worth checking out leanpub.com – they use markdown files to directly create PDF, MOBI and ePub files that they can host (for a small cut, of course), but that you are free to also use at Smashwords, Amazon, etc. They also have some nice website widget code to display the book on your website.
    I used them to publish my new novella and found the whole process very slick.

  2. Thanks for the comment, Mick. I did come across LeanPub in my travels, but I thought it was a command line tool. Maybe that was a different ‘leanpub’. The site you mention looks pretty awesome. If it could be used to produce a well-formatted PDF via Latex I’d definitely be interested. Right now, the PDF I can generate from my Markdown files needs tweaking and I’m not entirely sure how to go about it (since Latex seems to be a realm unto itself). Thanks for the heads-up.

  3. I love the idea of using Markdown, but the thing I can’t figure out is the spaces between paragraphs. Since you aren’t indenting, you need to double-space between paragraphs. That works great for blog posts, but wouldn’t work for prose format. When you finally compile the book, are those extra spaces taken out?

  4. Hi Jesse

    The indenting (or block style, depending on what you want in the final book) is all handled by the style sheet, which specifies what to do with paragraph presentation. All the Markdown does is convert plaintext blocks of text into HTML-compliant blocks that are marked by

    tags. Does that make sense?

    Cheers
    Ian

  5. Thanks for the reply, Ian. My experience with HTML is a limited, but I think that makes sense. So if in the final book I wanted no spaces between paragraphs, is there a way to remove them and indent? Would that be a software option in something like Scrivener? I guess I’m mainly wondering if there is an automated way to change the block style, instead of manually deleting each space and indenting each first line.

    And don’t feel like you have to go into detail. I’m just wondering if it’s possible. If it is, I can do the research to figure out how.

  6. You might be interested in this tool: http://johnmacfarlane.net/pandoc/ it can convert markdown to a myriad of other formats. Useful if you deal with publishers that can’t deal with html files.

    I’ve had good luck using it to convert directly into epub.

    I’ve also been using StackEdit to give me a live preview of what I am writing – it also syncs with google docs (and a bunch of other services) so that I don’t need to worry about where I am writing anymore.

  7. Thanks, er, ‘Ape’, I did indeed come across pandoc. In fact, I’ve tried using it to produce PDFs from Markdown (unfortunately, it’s limited to one standard Latex template and it crashes out of the PDFLatex command when passed certain images, which is, of course, quite irritating; I’ll try to chase down the problem when I have the time). Stackedit looks sweet. I don’t really need to see a preview alongside, but I do like the idea of having the document accessible via any computer. Right now I’m doing some similar by using vim to edit on a server over SSH, with the file itself in a DropBox folder.

  8. Hi, we need more and more experience on using lightweight markup languages as markdown in non-tecnical writing (there’s btw fountain (http://fountain.io/), a “markdown for screenwriting”, but totally incompatible and not really popular).
    I have just a question: how do you threat dialogues format?
    “- ” is a bulleted list element,
    “” is al free html link in most dialects (github)
    “>” is for quotes
    and there’s no “<>”.

  9. Hi Netalix

    Thanks for your comment. I don’t actually mark dialogue. I keep the quotes as-is, then put it through a ‘smarty pants’ filter of some kind that tweaks them for the final document. I use > for blockquotes, though… What’s <>?

    Cheers

    Ian

  10. Hi Annie

    I have only limited experience with Pandoc, I’m afraid. The best thing to do would be check out their support forums, if you haven’t done so already.

    With best wishes

    Ian

  11. Hi Ian,

    Great article. I’m currently trying to get a workflow together for using md for my essay and report writing.

    Another fantastic advantage of using plain text md files is that you can incorporate a version control system (such as `git`) with it.

    There is a bit of a learning curve with implementing a VCS, but it means you’ll never lose any of your work. It also can help a lot with your revisions and edits.

    Cheers, Ian

  12. Thanks, Ian! Yes, I had a go with version control myself a little while back, but couldn’t get to grips with it. The other issue is that this all goes out the window once a publisher needs to more on it; all drafts after that are funnelled through Word, worst luck.

  13. Hmm, that’s not something that seems obvious to me from the WordPress back end. When you come to the site, do you see the ‘notify’ box at the end of the post checked? If so, unchecking that should solve it. If not, let me know and I’ll try to change settings…

  14. Hi Ian,

    Thanks for posting. What process do you use when converting from .md to .docx? I love writing in markdown, but converting to Word and then formatting into manuscript format is a bit of a pain.

    My process today is a rather convoluted .md -> .rtf using Pandoc, followed by Save As to .docx in Word.

  15. Hi Jeff

    Thanks for your comment. I haven’t actually gone the .docx route, and wouldn’t know what to recommend… I have a feeling that Scrivener might do the trick, however…

    With best wishes

    Ian

  16. Hi Sashan

    Thanks for your comment. You’re right that a good manuscript-style production tool would be a good idea. My preferred option at the moment is to drop the Markdown into an app like Scrivener, and then use the compile options to produce a manuscript format. Staying to a more pure approach, you could use an app like Marked, which has a manuscript CSS output option. Otherwise, you could create your own manuscript CSS.

    Cheers

    Ian

  17. Thanks, Aaron. Leanpub is something I looked at a few years ago and it didn’t offer quite the control I was looking for. Things might be a little different now, of course.

  18. Hi, I’m using markdown with leanpub to publish a 100,000 word thriller and the split screen (how the book should look) has crashed and will not restore. Can you suggest anything?
    Many thanks.

  19. Not a cry for help – just a belated (I realize this comment is for a post that is two+ years old now) thanks for writing both these posts. I found them handy references while setting up my own workflow (though I still haven’t quite figured out the magic of getting my css file to be read for formatting, but I’ll get there). Anywho, thanks for taking the time to write these up!

  20. Hi Ian,
    I realize I’m late to this party, but if you are still checking comments on this, I have a question for you.
    I’m a big fan of using markdown for everything. I hate writing in Scrivener; much prefer various text editors on both tablet and PC. But here’s the issue I run into:
    I write, as you seem to, each chapter in separate text files. How do you keep them in order? For example, if I write “Chapter1.txt” and “Chapter2.txt”, and then I decide to add another chapter in between, how do I add it without having to manually re-number everything that comes after? In Scrivener it’s as easy as moving index cards around. With text files… I just don’t know how to manage it. It gets messy very quickly.

    Any suggestions?

  21. Hi Doug

    Thanks for your comment. It’s a tricky one because I don’t actually use this method any more (I’ll write up my new method just as soon as it’s polished!); but I think the only way to go about it is assign a ‘draft order’ using numbers and then renumber at a later stage. Not ideal, I know.

    Cheers

    Ian

  22. After I originally left a commesnt I appear to have clicked on the -Notify me
    when new comments are added- chefkbox and now each time a comment is added I recieve four emails with the same comment.
    Is there a means you cann remove mme from that service?
    Kudos!

  23. Just tried to send you an email but it bounced… I don’t seem to have a central list of people subscribed to comments on my blog. Is there any option for turning off notifications when you go back to the page?

  24. It sees to me that Markdown is very useful when your words are going to go into some kind of html. Otherwise in the case of, say, a traditional publisher, or, say, a personal diary, or a screenplay which has its own format… it’s of no use? In fact in a situation like that the markdown syntax would possibly just be a nuisance. Would you say that’s true. Even in digital publishing, do all formats accept markdown? Thanks.

Leave a comment

Your email address will not be published. Required fields are marked *