My Kindle Authoring Setup Part 2 – now with Markdown!

May 13 2012 Published by under Kindle

Send to Kindle

As I was writing the previous post on my Kindle Authoring Setup, it occurred to me that markdown might be a solution to having to mark everything up with HTML tags. So I wrote a comment in there exactly as it hit my brain. After publishing that post, I went ahead and checked it out and it has worked beyond what I imagined.

First, I located the command line tool, pandoc (again, cross-platform, yay!) and installed that. Then I did some tests and was amazed how much it did. Read up on markdown syntax and was even further amazed. I’d say this writing/publishing flow is now as close to perfect as it can get.

First of all, I changed my concat target in the build.xml to use pandoc instead of ant’s concat.

    <target name="concat">
        <exec executable="pandoc">
            <arg value="-o"/>
            <arg value="${html_file}"/>
            <arg value="book/header.md"/>
            <arg value="book/pwc_ch01.md"/>
            <arg value="book/pwc_ch02.md"/>
            <arg value="book/footer.md"/>
        </exec>
    </target>

Here we specify the output file with -o plus the output file name, then the list of input files. It will concatenate them and convert them from markdown to HTML, using the file extensions to determine the format.

Some brilliant things about markdown that make it perfect for this format:

H1′s can be either:

# This is a header

or

This is a header
================

Since I’m using H1′s for chapter names, I like the underline format.

H3′s, which I’m using for sections, become:

### This is a section title

All other paragraphs are just plain text. p tags are added automatically.

It automatically does the smart quote replacements.

Surrounding underscores like _this_ become em tags (italicized in the book).

Surrounding asterisks like *this* become strong tags (bolded).

There is also markdown for images, but I’m fine with keeping the HTML image tags in there. Any inline HTML in a markdown doc is automatically preserved, with some caveats as mentioned in the above referenced syntax doc. I’ll switch over to markdown syntax for images though, just to keep everything in one format.

If that were all there was, I’d be thrilled. But it does even more.

Any blocks of text that are indented with at least 4 spaces or 1 tab are surrounded with pre and code tags! Furthermore, any angle brackets in that section are turned into their HTML entity equivalents. So basically I can copy and paste my code as is. All I need to do it tab it over 4 spaces.

Finally, inline code style, like this are accomplished with back quotes `like this`.

Couldn’t be happier with this setup right now. I’m basically writing straight up plain text with straight up plain copy and pasted code and it’s all formatting to a perfect ebook with one click of a button.

Send to Kindle

6 responses so far

  • [...] See my update on using markdown and pandoc here: http://www.bit-101.com/blog/?p=3502 [...]

  • That does sound like a great setup.

    If you want something similar for your blog, you should check out http://octopress.org/

  • Tom Morgan says:

    Wow! Typically you’re the person who provides a description/workflow for stuff that I can actually relate to. I’ve just set myself up in a similar way, tested it and it seems to work a treat. Unfortunately I have no book in the pipeline otherwise I’d be dangerous right now! ;-)

    • keith says:

      Nice. What platform are you on?

      • Tom Morgan says:

        I’m on Mac so I’m using TextMate for editing but Calibre (+ command line tools) and pandoc installed/worked fine. I notice the TOC seems to be appearing after the main content in the .mobi is that how they usually work? Or is that just where it puts them when they’re generated automatically? I’ve only got a single chapter, with just a few test pars, so it’s probably more noticeable than it would normally be.

        • keith says:

          Awesome. I’m glad to hear it works on Mac too.

          Yeah, the TOC at end is a MOBI format thing. There is a calibre command line option that’s supposed to force it to the front, but it doesn’t appear to do anything. The alternate is to make your own TOC which is just list with links to named anchors, and stick that at the start of the book. It seems like this is discouraged though. But it also seems like most books do have the TOC at the front, so I’m trying to figure out how that works. Not a deal breaker though.

Leave a Reply