Markdown formatting
markdown unix osx python writing

Update: Due to the amount of interest this project has generated, I moved the official formd documentation to here. This post serves as a helpful resource to explain why I initially wrote formd and some of formd’s original features. formd is under active development and the source code for the project can be found on GitHub.

Introduction:

I’ve never been a fan of markup languages like Markdown. Markdown has always seemed like an unnecessary intermediary to generating HTML. Learning yet another tool in addition to CSS, Javascript, and HTML has never been appealing to me.

Lately, my opinions about Markdown have started to change. I recently converted this blog to a static site generated with Jekyll. Jekyll uses the Ruby markdown interpreter, Maruku, to create HTML from Markdown. While switching to Jekyll, I’ve grown to really like Markdown. Markdown eliminates much of the superfluous syntax of HTML, resulting in much cleaner and more readable text.

Despite my new found appreciation for Markdown, I still find the linking syntax cumbersome. Referenced links are disruptive because they require first writing linked text inline then jumping below to the reference section to create individual references. Writing inline compromises readability and is no better than raw HTML; especially in densely linked text.

I’ve found that the optimal way to work with Markdown is to create inline references while writing and editing, but use referenced links while reading. Here is an example of inline versus referenced Markdown syntax:

Inline link:

There were a king with a large jaw and a queen with a plain face, on the [throne of England](http://en.wikipedia.org/wiki/Throne_of_England); there were a king with a large jaw and a queen with a fair face, on the throne of France. In both countries it was clearer than crystal to the lords of the State preserves of loaves and fishes, that things in general were settled for ever.


Referenced link:

There were a king with a large jaw and a queen with a plain face, on the [throne of England][1]; there were a king with a large jaw and a queen with a fair face, on the throne of France. In both countries it was clearer than crystal to the lords of the State preserves of loaves and fishes, that things in general were settled for ever.
[1]:http://en.wikipedia.org/wiki/Throne_of_England


Last week I created a simple tool called formd, which stands for (for)mat (m)ark(d)own. You can find it here on GitHub. formd enables rapid conversion between inline and referenced Markdown formats. formd converts inline Markdown to referenced Markdown and vice versa allowing links to be optimally positioned for writing/editing or for reading.

The program uses standard streams to read from stdin() and write to stout(), so the script can easily be adapted to a wide-range of Markdown work flows. I typically use formd in one of three ways:

  1. from the command line
  2. from within Vim
  3. with TextExpander

Here is what formd looks like in action:
Here are some simple examples of how to use formd. These examples assume formd is executable and somewhere in your path. Issuing formd -r will generate referenced Markdown, while using formd -i generates inline Markdown.

Using formd from the command line:

cat ugly_markdown_file.md | formd -r > reference_formatted_file.md

Using formd with Vim:

In Vim, external commands can be run on the current Vim buffer by issuing the :%! command. For example, to convert text to referenced Markdown, run:

:%! formd -r

Better yet, remap formd -r and formd -i in your .vimrc:

" formd Markdown shortcuts
nmap <leader>fr :%! formd -r<CR>
nmap <leader>fi :%! formd -i<CR>

Even better, create a function that automatically returns your cursor to previous position:

" a function to execute formd and return the cursor back
" to it's original position within the buffer. 

" This script assumes formd is in your path at:
" ~/bin/formd/formd

function! Formd(option)
    :let save_view = winsaveview()
    :let flag = a:option
    :if flag == "-r"
        :%! ~/bin/formd/formd -r
    :elseif flag == "-i"
        :%! ~/bin/formd/formd -i
    :else
        :%! ~/bin/formd/formd -f
    :endif
    :call winrestview(save_view)
endfunction

" formd mappings

nmap <leader>fr :call Formd("-r")<CR>
nmap <leader>fi :call Formd("-i")<CR>
nmap <leader>f :call Formd("-f")<CR>

Using formd with TextExpander:
I like to compose email messages in Markdown and use Markdown within by browser on a few sites like Stack Overflow. For these applications, using formd with TextExpander is useful. formd can be setup to be used as a TextExpander shell script snippet. Here’s what my TextExpander snippet looks like: Using formd with TextExpander To run formd with TextExpander, simply place the Markdown text to convert onto the clipboard and issue the appropriate TextExpander shortcut (I use fr or fi for referenced or inline, respectively).