Even More Markdown Fun

In the past I've given an example of Markdown and talked about why you should use it, but you might wonder how to use it. After all, there can be a complex workflow involved with publishing a book. It's not a matter of just writing something, converting it, and publishing it. So, in this blog post I will explain how you can take your manuscript that you write and edit in Markdown and accomplish tasks that you will need to complete in the publishing process. I won't go into detail about Markdown syntax since there are other good resources online, such as the original Markdown specification, the pandoc user guide (see the "Pandoc's markdown" section), and the reference for PHP Markdown Extra.


Photo credit: jppi from morguefile.com

As I've said before, you can write your manuscript in Markdown using any text editor. There are many to choose from, some of which depend on which operating system you use. Some to consider are Notepad++ (Windows), emacs (multiple platforms), Smultron (OS X), and gedit (Linux). Beyond the basic aspect of composing the text, you'll want to know how to...

Keep regular backups in "the cloud"
This is an easy one! Use Dropbox or SpiderOak to automatically store your work to the cloud without even thinking about backups. Both services allow you to "go back in time" to an earlier version of a file if you do something bad (like delete it, make bad edits, etc.) or if something bad happens (file corruption, etc.).
Split your manuscript into chapters
This is also pretty easy -- just use a file naming convention that makes it easy to see what each file is. For example, if I'd heard of Markdown before I wrote Lesson One: Revolution! and wrote it this way, I could have named my files L1R_Chapter_01.txt, L1R_Chapter_02.txt, etc., on up to L1R_Chapter_12.txt.
Track multiple versions
Another easy one. Modify your naming convention to include a number for the overall draft. Using the above example, my chapter files for the first draft of Lesson One: Revolution! could have been: L1R_01_Chapter_01.txt, L1R_01_Chapter_02.txt, L1R_01_Chapter_03.txt, etc. When I was ready to start my second draft, I could have archived copies of all of those files into a "draft 1" folder, then switched to L1R_02_Chapter_01.txt, L1R_02_Chapter_02.txt, L1R_02_Chapter_03.txt., and so on.
Send your manuscript to an editor for revision
Most likely your editor doesn't know anything about Markdown, and the format itself isn't very useful for their work. To send them your manuscript, you simply convert it to a format they are prepared to handle, such as OpenDocument (.odt) or Word (.docx). This can be done with pandoc. To continue the above example, I would have sent my third draft of Lesson One: Revolution! to my editor after converting it to an .odt file with the following command:
pandoc -f markdown L1R_03_Chapter_01.txt L1R_03_Chapter_02.txt L1R_03_Chapter_03.txt L1R_03_Chapter_04.txt L1R_03_Chapter_05.txt L1R_03_Chapter_06.txt L1R_03_Chapter_07.txt L1R_03_Chapter_08.txt L1R_03_Chapter_09.txt L1R_03_Chapter_10.txt L1R_03_Chapter_11.txt L1R_03_Chapter_12.txt -o LessonOneRevolution.odt
Post a sample to your blog
This depends on your blog, but if your blog can use HTML-formatted content (which is pretty likely), you can convert a chapter of your manuscript to a snippet of HTML ready for insertion into your blog with this command and then edit the result to cut it to the length you want:
pandoc -f markdown MyNovel_03_Chapter_06.txt -o MyNovelSample.html
Create a print edition
While in Markdown format, your novel is not ready for print. Once all of your revisions are done, convert it to a word processing file the same way you did for sending it to an editor. Then open the file, adjust your page size, and proceed with formatting the manuscript for print. The basic text formats (italics, etc.) will already be in place, but you'll want to choose a font, decide on paragraph styles, etc. if you did not set all that up using a stylesheet for your Markdown content. So far I've found it easier to do that in the style settings in the word processing document, but maybe later I will “graduate” to setting up a stylesheet for the Markdown content so it can be used automatically across different formats.
Create an e-book edition
You can create an ePUB file directly from your Markdown files, and then open it in Sigil, calibre, or a similar tool to finish formatting. Once done, you can open the ePUB file in the Kindle Previewer to convert it to a .MOBI file ready for a Kindle. If you want to keep the chapters split up in the ePUB, you should start each chapter file with the same level of heading and then use the --epub-chapter-level option to tell pandoc where to split the input. For example, if you used level 2 headers to start each chapter (e.g.: ## Chapter 1: Mary Discovers Magic), you would convert your manuscript into an ePUB e-book, use pandoc like this:
pandoc -S -f markdown --epub-chapter-level=2 MyNovel_04_Chapter_01.txt MyNovel_04_Chapter_02.txt MyNovel_04_Chapter_03.txt MyNovel_04_Chapter_04.txt MyNovel_04_Chapter_05.txt -o MyNovel.epub
Send review copies before the release date
A useful digital format for advance copies (ARCs) is PDF, since it is compatible with virtually any computing platform and it is easy for people to use. One easy way to do this is to take the word processing document you created for the print edition and simply "save as" or "export to" or "print to" PDF from your word processing software. You can use pandoc to create a PDF directly from your Markdown files, but it relies on pdflatex support, which requires having LaTeX installed (e.g., TeX Live).

Hopefully those explanations will help you connect the dots between authoring your manuscript in Markdown and completing various tasks associated with publishing your work.

Tip: With a bit of command shell scripting, you can automate or semi-automate processes that use pandoc. It's worth learning how to do rudimentary shell scripting anyway, so if you're not familiar with it, you now have a useful homework assignment!

In case you're wondering, I did write this blog post in Markdown. (Look at the image used to illustrate this post — it's a shot of my screen while I was drafting it!) I then converted it using pandoc into HTML for posting on my site. This is not my normal workflow, I usually just write my blog posts in HTML to begin with, but I wanted to demonstrate that it's not necessary to learn HTML to create HTML content. I also wanted to learn more Markdown, such as the definition list syntax supported by pandoc. Why not use Markdown for all of my blog posts? Well, I want to, but (as with most things in life) I need the process to be efficient and right now a software problem is interfering with that goal. In a nutshell, I didn't like the results I got when I tried the Markdown input filter for Drupal and I didn't have time to fiddle with it. After I upgrade my site, I plan to try the newer version of that module for Drupal and hopefully it will allow me to efficiently write blog posts in Markdown.

If you have any questions about any of this, feel free to contact me!


About the Author
Stuart J. Whitmore is an author of fiction and nonfiction, as well as a photographer, technology developer, and more. If you enjoy reading his blog posts, you might also enjoy reading his books. Take a look at the books by Stuart J. Whitmore today, and download your copy of one that looks interesting to you!