Converting to Markdown
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.
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.
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.
Phone: (813) 421-4338