Writing a Novel Using Markdown: Part One

This story begins with a per­son like me. When I pub­lish ebooks, I want them to turn out exactly as I intend. That means tak­ing the text of the story, sand­wich­ing it with front mat­ter (like copy­right) and more text at the end (like acknow­ledg­ments).

Until recently, I wrote my books using the word pro­cessor Apple Pages. I would export this to a Microsoft Word doc­u­ment for my edit­ors and proofread­ers. Then, when the book was ready to be con­ver­ted into an ebook, I would do a lot of the work by hand.

And therein lies the prob­lem. There’s a lot of manu­al effort involved when you take a Word doc­u­ment and pro­duce some­thing that Amazon or iBooks will accept as an ebook.

In this post I’m going to talk about using plain text files to con­sist­ently and pain­lessly pro­duce ebooks. I won’t assume much know­ledge.

Styling Text

There should be a sep­ar­a­tion between style and con­tent. Style is font size, para­graph spa­cing, and all that jazz. The con­tent is the text itself. Word pro­cessors like Pages or Microsoft Word com­bine style and con­tent into a single file. These files are com­plex, con­tain ambi­gu­ities, and are dif­fi­cult to read without a work­ing copy of the pro­gram that pro­duced them.

When you sep­ar­ate style and con­tent, many advant­ages res­ult. The con­tent file doesn’t need to be in a pro­pri­et­ary format. It can be plain text. The con­tent file will be eas­ily read by a com­puter, which means the com­puter can auto­mate cer­tain things for you: cre­ate an ebook, a nice-look­ing PDF, a PowerPoint present­a­tion, a web page…all from the same con­tent file.

But how do you make the con­tent file?

Use Markdown

Markdown was cre­ated by John Gruber as a way of writ­ing for the web without includ­ing the dis­trac­tion of mark-up tags (more below). It has been exten­ded by sub­sequent pro­gram­mers.

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

## Red Star Falling

In the moment before Saskia Brandt awoke, she had a vis­ion of red chrys­an­them­ums fall­ing. The flowers looked unreal. Their stems were too straight and their falls too slow. Their *Gestalt* was art­ful sad­ness.

What you’re look­ing at above is a plain text snip­pet. The # char­ac­ter means that the text Red Star Falling should be treated as a head­ing (just like a head­ing in Word). Two ## char­ac­ters means that this is a head­ing level two. Immediately, you can see that this is a fool­proof way of telling a com­puter that the text is head­ing level two; at the same time, it’s easy for a human to read.


## Red Star Falling

there is a blank line. This tells the com­puter to treat the next text it encoun­ters as the begin­ning of a new para­graph. Notice that, in this new para­graph, I’ve used a


char­ac­ter to enclose the German word Gestalt. This tells the com­puter to emphas­ise the word. In this case, it makes it ital­ic.

OK. So I’ve writ­ten the first para­graph of my glor­i­ous story. What do I do with it?

Well, the Amazon Kindle format is based on HTML, which is the simple tag­ging format that most webpages use. So I want to pro­duce HTML from the Markdown. There are many tools that will help you do this. I’ll talk about some of them later. When I con­vert the above text to HTML I get the fol­low­ing:

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 famil­i­ar with HTML, this will look a bit weird. The import­ant thing to note is that the ori­gin­al Markdown format text will reli­ably pro­duce 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 writ­ten in Markdown. It doesn’t get much sim­pler. I don’t need to worry about smart quotes and dash sizes–all this is done when cre­at­ing the HTML.

  2. Because it’s a plain text file, I can work on it from a com­puter of vir­tu­ally any type (desktop, laptop, mobile), any age (even ancient PCs can read text files) and any plat­form (plain text files are very port­able).

  3. Helper pro­grams 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 help­er pro­grams, 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 pro­pri­et­ary word-pro­cessing format.

My Workflow

Most of my writ­ing takes place on two devices: A MacBook Air and an iPad. My work­flow is there­fore Mac-cent­ric. However, the approach should work on any sys­tem.

Here is the point where I real­ise that my own work­flow files are hope­lessly hard-coded to my own sys­tem, and provid­ing you with a work­ing example of Red Star Falling that you can down­load and play with is impossible without edit­ing my files. So, instead of giv­ing you these files, I’ll explain the pro­cess in plain English.

  • My book is a series of plain text files, all of which are in Markdown format. Each file rep­res­ents a sec­tion of the book that I’ve isol­ated for con­veni­ence. (Note that file num­ber six is actu­ally an ali­as to a file held in a more cent­ral cent­ral loc­a­tion, which is the same across all my books.)


I’ve now writ­ten a fol­low-up to this post that includes a detailed example.

Useful resources

A Markdown cheat­sheet.

My Writer as a Stranger CSS (Cascading Style Sheet). Use this in com­bin­a­tion with a Markdown doc­u­ment to pro­duce a book with the same final format­ting as Red Star Falling.

Markdown tools from Brett Terpstra.

Author: Ian Hocking

Writer and psychologist.

33 thoughts on “Writing a Novel Using Markdown: Part One”

  1. If people are com­fort­able using mark­down and want to skip a step or two, it is also worth check­ing out leanpub.com — they use mark­down files to dir­ectly cre­ate 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 web­site wid­get code to dis­play the book on your web­site.
    I used them to pub­lish my new novella and found the whole pro­cess very slick.

  2. Thanks for the com­ment, Mick. I did come across LeanPub in my travels, but I thought it was a com­mand line tool. Maybe that was a dif­fer­ent ‘lean­pub’. The site you men­tion looks pretty awe­some. If it could be used to pro­duce a well-format­ted PDF via Latex I’d def­in­itely be inter­ested. Right now, the PDF I can gen­er­ate from my Markdown files needs tweak­ing 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 fig­ure out is the spaces between para­graphs. Since you aren’t indent­ing, you need to double-space between para­graphs. That works great for blog posts, but wouldn’t work for prose format. When you finally com­pile the book, are those extra spaces taken out?

  4. Hi Jesse

    The indent­ing (or block style, depend­ing on what you want in the final book) is all handled by the style sheet, which spe­cifies what to do with para­graph present­a­tion. All the Markdown does is con­vert plain­text blocks of text into HTML-com­pli­ant blocks that are marked by

    tags. Does that make sense?


  5. Thanks for the reply, Ian. My exper­i­ence with HTML is a lim­ited, but I think that makes sense. So if in the final book I wanted no spaces between para­graphs, is there a way to remove them and indent? Would that be a soft­ware option in some­thing like Scrivener? I guess I’m mainly won­der­ing if there is an auto­mated way to change the block style, instead of manu­ally delet­ing each space and indent­ing each first line.

    And don’t feel like you have to go into detail. I’m just won­der­ing if it’s pos­sible. If it is, I can do the research to fig­ure out how.

  6. You might be inter­ested in this tool: http://johnmacfarlane.net/pandoc/ it can con­vert mark­down to a myri­ad of oth­er formats. Useful if you deal with pub­lish­ers that can’t deal with html files.

    I’ve had good luck using it to con­vert dir­ectly into epub.

    I’ve also been using StackEdit to give me a live pre­view of what I am writ­ing — it also syncs with google docs (and a bunch of oth­er ser­vices) so that I don’t need to worry about where I am writ­ing any­more.

  7. Thanks, er, ‘Ape’, I did indeed come across pan­doc. In fact, I’ve tried using it to pro­duce PDFs from Markdown (unfor­tu­nately, it’s lim­ited to one stand­ard Latex tem­plate and it crashes out of the PDFLatex com­mand when passed cer­tain images, which is, of course, quite irrit­at­ing; I’ll try to chase down the prob­lem when I have the time). Stackedit looks sweet. I don’t really need to see a pre­view along­side, but I do like the idea of hav­ing the doc­u­ment access­ible via any com­puter. Right now I’m doing some sim­il­ar by using vim to edit on a serv­er over SSH, with the file itself in a DropBox folder.

  8. Hi, we need more and more exper­i­ence on using light­weight markup lan­guages as mark­down in non-tec­nic­al writ­ing (there’s btw foun­tain (http://fountain.io/), a “mark­down for screen­writ­ing”, but totally incom­pat­ible and not really pop­u­lar).
    I have just a ques­tion: how do you threat dia­logues format?
    “- ” is a bul­leted list ele­ment,
    “” is al free html link in most dia­lects (git­hub)
    “>” is for quotes
    and there’s no “<>”.

  9. Hi Netalix

    Thanks for your com­ment. I don’t actu­ally mark dia­logue. I keep the quotes as-is, then put it through a ‘smarty pants’ fil­ter of some kind that tweaks them for the final doc­u­ment. I use > for block­quotes, though… What’s >?



  10. Hi Annie

    I have only lim­ited exper­i­ence with Pandoc, I’m afraid. The best thing to do would be check out their sup­port for­ums, if you haven’t done so already.

    With best wishes


  11. Hi Ian,

    Great art­icle. I’m cur­rently try­ing to get a work­flow togeth­er for using md for my essay and report writ­ing.

    Another fant­ast­ic advant­age of using plain text md files is that you can incor­por­ate a ver­sion con­trol sys­tem (such as ‘git‘) with it.

    There is a bit of a learn­ing curve with imple­ment­ing a VCS, but it means you’ll nev­er lose any of your work. It also can help a lot with your revi­sions and edits.

    Cheers, Ian

  12. Thanks, Ian! Yes, I had a go with ver­sion con­trol myself a little while back, but couldn’t get to grips with it. The oth­er issue is that this all goes out the win­dow once a pub­lish­er needs to more on it; all drafts after that are fun­nelled through Word, worst luck.

  13. When I ini­tially com­men­ted I clicked the “Notify me when new com­ments are added” check­box and now each
    time a com­ment is added I get sev­er­al emails with the same com­ment.
    Is there any way you can remove people from
    that ser­vice? Thank you!

  14. Hmm, that’s not some­thing that seems obvi­ous to me from the WordPress back end. When you come to the site, do you see the ‘noti­fy’ box at the end of the post checked? If so, uncheck­ing that should solve it. If not, let me know and I’ll try to change set­tings…

  15. Hi Ian,

    Thanks for post­ing. What pro­cess do you use when con­vert­ing from .md to .docx? I love writ­ing in mark­down, but con­vert­ing to Word and then format­ting into manu­script format is a bit of a pain.

    My pro­cess today is a rather con­vo­luted .md -> .rtf using Pandoc, fol­lowed by Save As to .docx in Word.

  16. Hi Jeff

    Thanks for your com­ment. I haven’t actu­ally gone the .docx route, and wouldn’t know what to recom­mend… I have a feel­ing that Scrivener might do the trick, how­ever…

    With best wishes


  17. Hi Sashan

    Thanks for your com­ment. You’re right that a good manu­script-style pro­duc­tion tool would be a good idea. My pre­ferred option at the moment is to drop the Markdown into an app like Scrivener, and then use the com­pile options to pro­duce a manu­script format. Staying to a more pure approach, you could use an app like Marked, which has a manu­script CSS out­put option. Otherwise, you could cre­ate your own manu­script CSS.



  18. Thanks, Aaron. Leanpub is some­thing I looked at a few years ago and it didn’t offer quite the con­trol I was look­ing for. Things might be a little dif­fer­ent now, of course.

  19. Hi, I’m using mark­down with lean­pub to pub­lish a 100,000 word thrill­er and the split screen (how the book should look) has crashed and will not restore. Can you sug­gest any­thing?
    Many thanks.

  20. Not a cry for help — just a belated (I real­ize this com­ment is for a post that is two+ years old now) thanks for writ­ing both these posts. I found them handy ref­er­ences while set­ting up my own work­flow (though I still haven’t quite figured out the magic of get­ting my css file to be read for format­ting, but I’ll get there). Anywho, thanks for tak­ing the time to write these up!

  21. Hi Ian,
    I real­ize I’m late to this party, but if you are still check­ing com­ments on this, I have a ques­tion for you.
    I’m a big fan of using mark­down for everything. I hate writ­ing in Scrivener; much prefer vari­ous text edit­ors on both tab­let and PC. But here’s the issue I run into:
    I write, as you seem to, each chapter in sep­ar­ate 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 anoth­er chapter in between, how do I add it without hav­ing to manu­ally re-num­ber everything that comes after? In Scrivener it’s as easy as mov­ing index cards around. With text files… I just don’t know how to man­age it. It gets messy very quickly.

    Any sug­ges­tions?

  22. Hi Doug

    Thanks for your com­ment. It’s a tricky one because I don’t actu­ally use this meth­od any more (I’ll write up my new meth­od just as soon as it’s pol­ished!); but I think the only way to go about it is assign a ‘draft order’ using num­bers and then renum­ber at a later stage. Not ideal, I know.



  23. After I ori­gin­ally left a commes­nt I appear to have clicked on the -Notify me
    when new com­ments are added- chefk­box and now each time a com­ment is added I recieve four emails with the same com­ment.
    Is there a means you cann remove mme from that ser­vice?

  24. Just tried to send you an email but it bounced… I don’t seem to have a cent­ral list of people sub­scribed to com­ments on my blog. Is there any option for turn­ing off noti­fic­a­tions when you go back to the page?

Leave a Reply

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