Writing a Novel Using Markdown: Part Two

In my pre­vi­ous post, I spoke a little about my Markdown work­flow. I ended it pre­ma­turely because I didn’t have a pre­pared ver­sion of my book, Red Star Falling, that I could share with you.

Now I do.

You can down­load Multimarkdown / Markdown1 source of the com­plete book here. This ZIP archive con­tains the text of the book (cheekily, I’ve redac­ted most of the story), the Writer as a Stranger Cascading Style Sheet, the cov­er image, and a little Möbius vec­tor graph­ic I’m using as a sec­tion break.

As I men­tioned in my pre­vi­ous post, once you have your book in Markdown (i.e. a plain text file), you can use whatever tools you wish to pro­duce your ebook–in whatever format(s) that might be.

I use a Mac OS X fea­ture called a ser­vice. This does noth­ing more than run a bash script, which is a series of com­mands telling the com­puter what to do with the Markdown files. You can down­load the ser­vice here. It works on OS X Mountain Lion, but it will prob­ably work on earli­er ver­sions of the Mac. The raw source for the bash script (i.e. just the series of com­mands) is avail­able here, but I’ve also appen­ded it to this post. All com­puters, includ­ing those run­ning Windows, can execute bash scripts–but they might need some tweak­ing.

Here are the files that make up the text of the book (i.e. those in the ZIP):

Screen Shot 2013 06 23 at 20 33 23

Note that the files are numbered to pre­serve their order. Each Markdown file ends with a few blank lines to pad them out when they’re com­bined into a single file 2.

All the import­ant inform­a­tion about the book–who the author is, the title, revi­sion num­ber, where the cov­er file is located–all of that is declared in the file ‘1_meta_data.mmd’. This means that, if you wish to use this meth­od to pro­duce your own book, the script will work as long as you’ve updated the metadata in this file.

What extra stuff you need

It would be nice if OS X came with ebook-pub­lic­a­tion tools built-in. Alas, it doesn’t. My script uses two power­ful pro­grams: ebook-con­vert and mul­ti­mark­down. You need to install these loc­ally first. Note that my script tells the com­puter exactly where the mul­ti­mark­down com­mand lives (it’s in /usr/local/bin/multimarkdown). I don’t know why I had to give this path to make the script work, but I did.

Using the OS X Service

This is really straight­for­ward. On your Mac, put the ser­vice into Home > Library > Services. If your Library folder is hid­den, you’ll need to Option-click the ‘Go’ menu in Finder and select it. Logout, login, and then you should see ser­vice (called • [Toy] Create MOBI-EPUB-PDF from mul­tiple MMD, using Metadata copy) in the con­tex­tu­al menu when any Finder items are high­lighted.

Download my example archive, high­light all the Markdown files, then right-click and select the ser­vice. It will then cre­ate .mobi, .epub and .pdf ver­sions of Red Star Falling.

These files will be placed in the sub-folder called Publication_ready. A log file in that folder, called Log.txt, will be updated with each new con­ver­sion; look there if you want to find out why things have gone wrong. Intermediate .html files will be deleted.

Because I pub­lish (for now) only to the Kindle, I’ve made sure that the .mobi file works per­fectly on the Kindle for long-form prose3. The .epub is ser­vice­able but not pretty. The .pdf like­wise. One advant­age of script­ing the pro­cess is that you can tweak the set­tings for .epub out­put until you’re happy and then apply those to all your books using the same script.

Cool things you can now do

  • Because this is a script, you can tweak it to:

    • Pass the .epub file to a val­id­a­tion tool. I’d recom­mend epubcheck. Once this is in the script, it’ll hap­pen every time.

    • Push the final­ised files to a cent­ral folder where you keep all your ‘pub­lic­a­tion ready’ books.

  • You can use a single style sheet for all your books. The format–.epub, .mobi, or whatever–should not change the look and feel of your final books. Once set, you don’t need to worry about this again.

  • Creating a new book is as simple as duplic­at­ing the dir­ect­ory and chan­ging the metadata. The main text of your story is simply a Markdown file: human-read­able, port­able, and small.

  • Use ali­ases. In this book, I have a section–i.e. a Markdown file–that tells the read­er about my oth­er books. I don’t want to rep­lic­ate this for every new book, and I want any future books to com­pile with an update list of my works. So I use an ali­as to point to a cent­ral Markdown file that con­tains this inform­a­tion. When I update that file, any book will com­pile with an updated list of my works.

  • Set a watch on the folder. Perhaps trig­ger the script to run (suit­ably mod­i­fied) when the main story file is updated. That way, all the pub­lic­a­tion-ready files will self-update.

What are the implications of this workflow for the writing process?

None. The act of writ­ing itself should be com­pletely inde­pend­ent of all the com­plex­it­ies that hap­pen to the Markdown file later, when it’s pro­cessed. It’s more con­veni­ent in sev­er­al ways. You’ll not have to worry about smart quotes, or font sizes, or any­thing like that. All you have to con­cen­trate on is writ­ing the story in this format:

## 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.

Then the sky beyond them wintered and the dream faded.

For that, I’d recom­mend any num­ber of cool pro­grams, includ­ing ByWord and iAWriter.

Coda: The script itself

In case you’re here just for this script and want to have a look at it, here it is.

[code language=“bash”]## MULTIMARKDOWN FILES > MOBI, PDF AND EPUB

## IH, 23 JUNE 2013

## This script takes a group of files in Multimarkdown,
## com­bines them into a single file, and then pro­duces
## MOBI, EPUB and PDF. Also runs an epub check pro­gram.

## Expects metadata in a file called 1_meta_data.md

## Expects to have a dir­ect­ory called Publication_Ready.
## Will pipe com­mand out­put to Publication_Ready/Log.txt

## Unusual com­mands used (i.e. you’ll need to install these):
## ebook-con­vert [<http://manual.calibre-ebook.com/cli/ebook-convert.html>]
## mul­ti­mark­down [<http://fletcherpenney.net/multimarkdown/use/>]

###########################################

# Find out the dir­ect­ory that this script is work­ing with­in
DIR=‘dirname “$1”‘

# Go there
cd “$DIR”

# Extract meta data from the file called ‘1_meta_data.mmd’
title=‘/usr/local/bin/multimarkdown 1_meta_data.mmd –extract=“Title“‘
revision=‘/usr/local/bin/multimarkdown 1_meta_data.mmd –extract=“Revision“‘
short_title=‘/usr/local/bin/multimarkdown 1_meta_data.mmd –extract=“ShortTitle“‘
author=‘/usr/local/bin/multimarkdown 1_meta_data.mmd –extract=“Author“‘
series=‘/usr/local/bin/multimarkdown 1_meta_data.mmd –extract=“Series“‘
series_index=‘/usr/local/bin/multimarkdown 1_meta_data.mmd –extract=“SeriesIndex“‘
tags=‘/usr/local/bin/multimarkdown 1_meta_data.mmd –extract=“Tags“‘
cover=‘/usr/local/bin/multimarkdown 1_meta_data.mmd –extract=“Cover“‘

# LOG Date
echo “” » Publication_Ready/Log.txt
echo “” » Publication_Ready/Log.txt
echo “” » Publication_Ready/Log.txt
echo ‘date‘ $revi­sion » Publication_Ready/Log.txt
echo “” » Publication_Ready/Log.txt

# Concatenate all the files passed to this script
cat “$@” > $short_title.mmd

# LOG
echo “” » Publication_Ready/Log.txt
echo “” » Publication_Ready/Log.txt
echo ******* Compiling HTML from Multimarkdown… » Publication_Ready/Log.txt

# Run ‘mul­ti­mark­down’ to pro­duce HTML, smart mode, append­ing res­ult to log
/usr/local/bin/multimarkdown $short_title.mmd –output=$short_title.html –smart » Publication_Ready/Log.txt

# LOG
echo “” » Publication_Ready/Log.txt
echo “” » Publication_Ready/Log.txt
echo ******* Compiling MOBI… » Publication_Ready/Log.txt

# Make MOBI
ebook-con­vert $short_title.html Publication_Ready/$short_title[$revision].mobi –authors=”$author” –series=”$series” –series-index=$series_index –title=”$title” –tags=”$tags” –output-profile=kindle » Publication_Ready/Log.txt

# LOG
echo “” » Publication_Ready/Log.txt
echo “” » Publication_Ready/Log.txt
echo ******* Compiling PDF… » Publication_Ready/Log.txt

# Make PDF
ebook-con­vert $short_title.html Publication_Ready/$short_title[$revision].pdf –authors=”$author” –series=”$series” –series-index=$series_index –title=”$title” –tags=”$tags” » Publication_Ready/Log.txt

# LOG
echo “” » Publication_Ready/Log.txt
echo “” » Publication_Ready/Log.txt
echo ******* Compiling EPUB… » Publication_Ready/Log.txt

# Make EPUB
ebook-con­vert $short_title.html Publication_Ready/$short_title[$revision].epub –remove-first-image –authors=”$author” –series=”$series” –series-index=$series_index –title=”$title” –tags=”$tags” –output-profile=ipad » Publication_Ready/Log.txt

# LOG
echo “” » Publication_Ready/Log.txt
echo “” » Publication_Ready/Log.txt
echo Cleaning up tem­por­ary files… » Publication_Ready/Log.txt

# Clean up the tem­por­ary HTML and mmd files
rm $short_title.html $short_title.mmd » Publication_Ready/Log.txt

# LOG
echo “” » Publication_Ready/Log.txt
echo “” » Publication_Ready/Log.txt
echo Job done bish bash ‘date‘ » Publication_Ready/Log.txt

[/code]


  1. Feel free to use this CSS with your own books. Think of it as the Writer as a Stranger ‘house style’. It will do things like indent all para­graphs unless they fol­low a chapter head­ing or sec­tion break and deal with block­quotes appro­pri­ately. I’ve iter­ated it a few times over the past few weeks to get it look­ing how I like it. ↩

  2. I’m aware that I can do this pro­gram­mat­ic­ally. (And, inter­est­ingly, the Multimarkdown com­mand line tool has an option to con­cat­en­ate mul­tiple input files; how­ever, it didn’t work for me and I couldn’t fig­ure out why. Hence the old-school solu­tion.) ↩

  3. You should always check your .mobi file using the Kindle Previewer applic­a­tion. ↩

Author: Ian Hocking

Writer and psychologist.

19 thoughts on “Writing a Novel Using Markdown: Part Two”

  1. Wonderful art­icles — nice to know I’m not the only crazy out here who has been seduced by Markdown. Your work­flow seems to add the much-needed flex­ib­il­ity that basic Gruber Markdown does lack — I’ll shame­lessly steal some of your ideas ;o)

    My own work­flow is an attempt at the oth­er extreme — Gruber Markdown only, although I’m then get­ting what flex­ib­il­ity I can from Calibre con­ver­sion (Calibre will take raw Markdown as input).

    Briefly, I do this :

    - Write in pure Gruber Markdown
    — Convert w/ Calibre to ePub
    — have Calibre remove blank lines between para­graphs and add indents
    — spe­cify page break for all h6’s under *Structure Detection*
    — add one line of “CSS” under “Look & Feel”
    (h1,h2,h3,h4,h5,h6{text-align:center;})
    — Use ePub as basis for con­vert­ing to any fur­ther formats needed — Mobi, PDF, you name it

    The res­ult­ing ePub will go fault-free through http://validator.idpf.org/ *unless* one has a num­ber first in the text fol­low­ing any of the Markdown # to ###### tags (causes an “id” in the ePub with num­ber as first char­ac­ter in name, and that’s a no-no).

    The ePub can be uploaded as-is to Amazon KDP, and the only errors I’ve ever got­ten are typos ;o)

    As always with Markdown, you can add any and all html you like (I do use the occa­sion­al ), but you can get a quite read­able lay­out without using any.

    Title page and start of first chapter of your example could be done as shown below. You might get a smile out of tak­ing it through Gruber’s online Dingus con­vert­er — just remem­ber that Calibre will take care of cen­ter­ing and indent­ing.

    Have fun — and thanks again for the art­icle and the encour­age­ment to keep using Markdown ;o)

    *************************** start of example *****************************

    ### IAN HOCKING

    # RED STAR FALLING

    ##### © Ian Hocking 2013

    ######

    ## One

    **I**n 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.

    Then the sky bey­ond them wintered and the dream faded.

    ####

    **S**he awoke to freez­ing dark­ness. Her throat was dry. She turned and coughed.

    *************************** end of example *****************************

  2. Ahem … your com­ment sys­tem does some con­ver­sion of its own, it seems. Anyway, in the above example, pls replace — with triple hyphens (- — -) and add an extra blank line after the “© Ian Hocking” line. Sorry about the fuss. Just shows no format­ting is fool­proof ;o)

  3. Great stuff, Thomas! Your meth­od looks inter­est­ing. I’ve actu­ally made my own work­flow a little dif­fi­cult since I wrote this art­icle, so it might well be time for me to update it… As you imply, the more min­im­al, the bet­ter…

  4. Hi ?an,

    Thanks for cool infos on your web­site. I am CPA and I’d like to write some ebooks for busi­ness­man. I decided to use mark­down but ? dont know so much thing.

    Could you please offer me some easy edit­or soft­ware for mark­down ? And where can ? buy mark­down book tem­plate ?

    Thanks in advance

    Yavuz Gurkan

  5. Hi, Ian.

    Thanks for the very detailed look at how you went about using mark­down. It got me writ­ing my own ver­sion, using mul­ti­mark­down, node.js, and grunt. Basic prin­ciple is the same as yours but not as advanced. I’m think­ing of extend­ing the idea by incor­por­at­ing some of the ideas in Scrivener into a programmer’s text edit­or (In my case, Sublime Text) to give some of the good­ies that make man­aging files and folders a bit easi­er.

    https://github.com/stevecooperorg/Subliviner

    Still very early days, but just wanted to say thanks for shar­ing.

    Steve

  6. Hi Yavuz

    I’m afraid I don’t know of too many places for tem­plates. The tem­plates I offer her are the only ones I know about. It’s pos­sible that LaTex might be a bet­ter fit for you. Meantime, in terms of soft­ware, I tend to use Textmate 2, Writer Pro, and Byword.

    With best wishes

    Ian

  7. Hi Steve

    Great work! Looks inter­est­ing. I’ll have a play with it at the week­end. I’m par­tic­u­larly pleased to see it on GitHub, which is the right place for this sort of thing (and bey­ond my expert­ise right now).

    Cheers

    Ian

  8. Cheers, Ian. At the mo, as I say, it’s really early days. I’ve not got round to the pub­lish­ing part par­tic­u­larly — it just con­cat­en­ates the mark­down into a single file and pro­duces the HTML ver­sion — but it’s a start.

    I’m still think­ing about restruc­tur­ing manu­scripts some­what, still. Maybe some­thing like this;

    manuscripts/
    Draft 0.Book name/
    A.Front matter/
    B.Chapters/
    01.Chapter Title/
    scene 1.mdd
    scene 2.mdd
    02.Chapter title
    C.End Matter/

    Do you ever deal with mul­tiple drafts? Unplaced frag­ments, plot sum­mar­ies, story bible? And how do you do backups or source con­trol? Interested to find out what you’ve learned while actu­ally *fin­ish­ing* books…

    Steve

  9. Yes, it looks like the dif­fer­ence might be that I don’t break my chapter files into scenes, but I can see that might be a good idea.

    As for pre­vi­ous ver­sions, I give all my drafts (which are of the entire book, incid­ent­ally) a ran­dom ver­sion num­ber, and when I make a big change the draft, I move the entire file to archive folder and then cre­ate an entirely new draft file with an incre­men­ted ver­sion num­ber.

    Would prefer to do this with some kind of subversion/version con­trol soft­ware…

    Cheers

    Ian

  10. Thanks for the thoughts, Ian. I’ve just moved all my notes into one loc­a­tion and I don’t quite know how to order it all yet — I’ll evolve some­thing soon, I think.

    Source con­trol is *the­or­et­ic­ally* straight­for­ward — just a mat­ter of stor­ing all your .mmd files — but mov­ing from ‘pos­sible’ to ‘easy and pain­less’ is a big old gap.

  11. Thanks for this! I’ve writ­ten a num­ber of ebooks and in my exper­i­ments with Markdown I’ve been able to get book files accep­ted without an issue in both Amazon and Smashwords but I couldn’t get the indents right. Your CSS file works won­der­fully for this. Thank you!

    I gen­er­ally write my drafts in iaWriter, but I am exper­i­ment­ing with Markdown Pro. I gen­er­ally code my ToC manu­ally using HTML. Your CSS file and tips are incred­ibly help­ful. Thank you again!

  12. Great, Annie! Glad it helped. I’ve been using a few apps recently for writ­ing (though most of what I’ve been doing is edit­ing, so I’ve used Scrivener). Otherwise, I’ve been using WriterPro.

  13. Thks much for post­ing all this — it con­vinced us to do all our blogs / news­let­ters / books in mark­down.

    Markdown text files make it simple to store our pub­lish­ing in our data­base as json (we use Postgresql).

    Since you like mark­down — you might try jekyll — a simple blog site engine based on mark­down. Takes about 30 secs to install (no kid­ding!).

    Git hub book has a free mark­down edit­or, which plugs into their ver­sion con­trol sys­tem.

    For those writers not on mac — all your scripts can all be run on linux as well — it’s really simple to dual boot a Windows machine with Ubuntu Linux.

    Since pan­doc is real simple to install on our linux sys­tems we will be try­ing that out but noted your prev com­ments on pan­doc

  14. I have a ques­tion … how do you handle char­ac­ter dialouge in Markdown? I ask, because a car­rige-return fol­lowed by an indent (I use three spaces) for a line of dialouge is not rendered like that when con­vert­ing it — the indent is ignored, and the dialouge is appen­ded to the pre­vi­ous line.

    Thanks.

  15. Thanks for your ques­tion, Brett. The three-char­ac­ter space is prob­ably being inter­preted as ‘format as-is’. For true Markdown, each new para­graph needs to be on a sep­ar­ate line. The quotes you use will not be smart quotes ini­tially; your Markdown ren­der­ing pro­gram will need to take care of that.

Leave a Reply

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