A Markdown formatter

View the Project on GitHub drbunsen/formd

Have questions, comments, or suggestions about formd? Ask me @drbunsen.

formd—A Markdown formatting tool:

formd is a tool for (for)matting (M)ark(d)own that allows rapid conversion between the two styles of Markdown links and images—inline and referenced.

Why is formd useful?

Inline Markdown is difficult to read, but useful for writing and editing because the linked text and URLs are adjacent to the words you are writing. For example:

The quick brown [fox](http://en.wikipedia.org/wiki/Fox) jumped over 
the lazy [dog](http://en.wikipedia.org/wiki/Dog).

Referenced Markdown is awkward while writing because it requires jumping between links within the text and the reference section at the bottom of a document. However, referenced Markdown is the superior syntax for reading because URLs do not breakup the flow of words or sentences. For example:

The quick brown [fox][] jumped over the lazy [dog][].  

formd provides the best of both worlds by allowing users to quickly toggle Markdown formats between inline while writing and referenced while reading. formd reads and writes to standard streams, so it can be adapted to a wide-range of user workflows. See this blog post for further details and workflow examples for using formd on the command line, with Vim, or with TextExpander.


Python 2.7+


Clone formd and place it somewhere in your path:

$ git clone https://github.com/drbunsen/formd.git ~/bin/


There are three command line options for formd:

To generate referenced Markdown use the -r flag:

$ formd -r

To generate inline Markdown use the -i flag:

$ formd -i 

To flip Markdown style to the opposite format call formd with the -f flag:

$ formd -f

formd is designed to work with a wide variety of workflows. Here are a few examples:

Use from the command line:

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

Use with Vim

formd can be integrated with Vim on several levels. The easiest option is to call it directly from within a Vim buffer. For example:

:%! formd -r

A better option is to append the following function and mappings to your .vimrc. As an example, running <leader>fi will now call formd and switch all markdown in the current buffer to inline markdown then return the cursor back to the original position that it was in when formd was executed.

Use as a stand alone shell script on with TextExpanderTextExpander on OS X:

pbpaste | ~/bin/formd -r

For more information on formd see this blog post for additional usage examples and a video demonstration.