I recently converted coteyr.net over to markdown. This article is a few notes and details about that experience. Both other developers and clients may find is useful. I am not going to go into how to use markdown (which you can find here) or details on how to implement it. Instead this is going to be a general overview. Don’t worry I will touch on some top level implementation info.

What is markdown?

Markdown is a type of annotation for text that basically applies styling to the text. It’s main goal is to be totally readable as plain text and HTML. This is a particularly good fit for dynamic content sites like blogs and CMSes. HTML was always meant to display textual information and carry some details about the importance of the data being carried. For example bold text is more important the normal text. But HTML is complicated. It’s not about just text anymore. All of that extra stuff gets in the way of writing, plain old text. For example, bold text needs at a minimum an open and close tag. Most sites will require a span tag, and accompanying CSS. There could be 10 lines or more of code just to make a word bold and make it look right. No one wants to deal with all that if there just trying to make a quick blog entry.

This is where markdown comes in. By focusing on just text, and on keeping the text editable, many improvements are achieved. First it’s faster. You don’t write HTML you just write. Second, it is editable by anything, any text editor, any text field. You don’t need a javascript editor, or something like front page. Third, because your not focusing on styles it’s easier to write better structured text. Who cares what a h1 looks like, your not even using it. Let the site take care of that, you as an author get to focus on “this is an important heading”.

Editing Markdown in Byword for Mac
Editing Markdown in Byword for Mac

There are some drawbacks. It’s a different language, for starters. It’s not hard to learn or use, but it’s different. You also have to “give up control” of the formatting of the text, and let the render (the site) take care of that. It’s also certainly not for non-text based things. You can include images, but only in the context of a text block. You would have to go way out of you way to do anything like a background image.

Others using Markdown

Wikipedia and media-wiki are the most prevalent examples. Byword (screenshot above), and several other editors are available (though you can use nearly anything that can save .txt files). There are CMS plugins for Wordpress, drupal and the usuals. I have used it in my project tracker for years. Several forum platforms use it. In all likely hood you have already used it several times without even noticing.

Implementing Markdown

Well first things first. Markdown needs to be rendered. Browsers understand HTML, your site needs to render HTML and markdown is only a tool to help you enter text. There is no rails ActionView renderer for markdown, nor would one really make sense ( as renders are meant to be tied to what they are rendering not what they render from). So in rails (same thing for PHP et. al.) you need to implement a helper to take your database housed markdown and convert it to html. rpeg-multimarkdown is a good start. I am not going to go into the details of doing this by hand, because that would take a long time, but basically you use the render to inject HTML into your view.

Next up is speed. Because your rendering to html instead of just dumping html from the database, it take a little longer. This isn’t a big deal if you have low traffic or simple pages, but complex pages, or lots of traffic can cause a problem. To solve this just use either page caching or action caching. I am a big fan of action caching over page caching. Page caching is nice but almost never usable (what is the last site you went to that didn’t need cookies).

Of important note is that markdown allows for HTML in the markdown. So if you have a lot of content that already exists in HTML and you don’t want to (or can’t) convert it all to markdown that is absolutely fine. It won’t hurt a thing.

What does it all mean

Basically it is another option for clients to enter text into a website with out having to know HTML. If you already know HTML it can speed up adding content by removing the need to write HTML. It’s not for everyone but if your site (or section of your site) is mostly text based, then you should strongly consider using markdown. It’s also important to note that markdown is not just for websites, but any text based editing including authoring books.

Coteyr.net Programming LLC. is about one thing. Getting your project done the way you like it. Using Agile development and management techniques, we are able to get even the most complex projects done in a short time frame and on a modest budget.

Feel free to contact me via any of the methods below. My normal hours are 10am to 10pm Eastern Standard Time. In case of emergency I am available 24/7.

Email: coteyr@coteyr.net
Phone: (813) 421-4338
GTalk: coteyr@coteyr.net
Skype: coteyr
Guru: Profile