How I write using Markdown

As I hinted in my last post I really like Markdown. So much so that when I am writing documentation, letters resumes or anything else, usually I will do anything to avoid having to write them up in Word or any of the many alternatives.

Write up the document

Byword 2 is great when working on large documents as you can put it in full screen and just see what it is that you are working on. It also has a Markdown preview so can instantly see what you are working on.

I then usually move to Vim for the last little updates (things like spacing can be a bit tricky in Byword as you can't turn on visible whitespace which is helpful for doing line breaks. The vim-markdown plugin is great for

Convert the markdown

Although you can then export either a PDF or HTML file from the formatted Markdown I prefer to use another application called Pandoc.

Pandoc is a library written in Haskell which can convert files from one markup language to another. It does this in a nice way in that it converts the input file into it's own internal format first so that the output filter then only has to know how to convert from one type of file - Pandoc's internal format, making writing new filter's easier.

I use it to convert my files into PDF (Using Latex) and DOCX formats usually but you can also convert your files to:

• HTML and HTML5
• OpenDocument XML
• ODT
• DocBook
• MediaWiki markup
• RTF

and many others. You can even convert them back into Markdown (if you wanted to).

It is a simple matter of calling running it at the command line to generate your files but I have created the following bash script to make creating the PDF and DOCX files even quicker.

#! /bin/bash

# Check for 1 argument
if [ "$#" != "1" ]
	then
		echo "You must include the name of the markdown file to process. Don't include the .md extension"
		exit 100
fi

# Check the filename argument
extension="${1##*.}"
filename="${1%.*}"
if [ "$extension" == "md" ]
	then
		filename="${1%.*}" 
elif [ -r "$1.md" ]
	then
		filename="$1" 
else 
		echo "File not found."
		exit 200
fi

# Generate Word document
if [ -f "$filename.docx" ]
	then
		rm "$filename.docx"
fi
echo Generating docx file
pandoc "$filename.md" -o "$filename.docx" -t docx

# Generate PDF document
if [ -f "$filename.pdf" ]
	then
		rm "$filename.pdf"
fi
echo Generating pdf file
pandoc "$filename.md" -V geometry:margin=1in -o "$filename.pdf" -t latex

# Done
echo Done.

process-md.sh

for this to work, make sure that the file has execute access and call it with the name of the .md file that you want to convert (it does expect that the files have an extension of md but that could be easily changed).

Thanks for reading.