Helping you leverage today's tech and wisdom for tomorrow's success.


Worlds Easiest Twitter For Business Software - Pluggio

Why You Should Learn a Markdown Language

Textiles de Otavalo

Some Background

I get this call often: I was editing my site, and I messed it up! I can't see anything anymore! the site is broken!

Looking at their site, I generally find that they have left a ">" off one of their html tags, throwing anything that follows into oblivion. Usually, the page will render up until that point, and then it will stop. That is usually my first clue.

The other situation I find is that a client has spent a good deal of money on a web designer, and ended up with a nice looking site. When it comes time to add content to the site, the well meaning client will override (unknowingly) all of the styles they paid the designer to develop, and end up with a site that resembles a ransom note.

In both cases, the biggest rule that has been violated is that directly editing HTML and CSS as a content developer. There are a few problems with this:

  • HTML is not trivial to learn. As a programmer, it's trivial, but even programmers don't write HTML. We write programs that write HTML.
  • Making a mistake in HTML or CSS has unpredictable effects. Depending on the OS, browser, and the what you had for lunch, the page could render completely differently.
  • Directly editing HTML or CSS overrides the consistency of the design that your designer worked hard to build into your site.

There is a solution

The solution to the problem is to use a sort of shorthand for HTML generally referred to as markdown. Markdown takes normal looking text, and transforms it into compliant HTML. This means that you can develop your content as simply as typing it out, without getting any markup in your way.

There are a few different markdown languages you can work with. I won't go into too much detail on each, but the ones I am familiar with are:

  • Textile - This is built directly in to alot of web frameworks. You might find that you have this already installed on your system. If you are using wordpress, you can find a plugin here, that will allow you to start working in textile right away.
  • Markdown - I haven't use this one much, but I do know that it is compatible with just about everything.
  • Pier Sytnax - This is the language I am using now. Pier Markdown is used by the Pier CMS, and includes many other markups to add functionality to your site.

Ask your IT guy, or your webmaster to see if you can use markdown on your site.

So Show me Already!

Okay, here is what markdown will do for you:


One of the problems I see is that someone will build a header like so:

<h1>This is it!</h2>

This will not close out the h1 headers, so anything goes when it comes to rendering that headers, it's anyone's guess as to what might happen when this tries to render.

in textile, you would simply type:

h1. This is it!

and your text would render just fine.

Centering Text

I only include this for completeness sake. If you are haphazardly centering text, I would examine why you are doing this before you start doing it everywhere. You might either need to adjust your CSS, or forsake centering text. But here's how it's done:


<p style="text-align:center;">Centered Text</p>

in Textile:

 p= Centered Text


In HTML, a list looks like:

<li>Item 1</li>
<li>Sub Item 1</li>
<li>Item 2</li>

Not only is this prone to accidents, it's hard to read. It's also alot of fumbling around to do when you're typing. Adding all this markup and making sure it's correct adds far too much complexity to just getting your thoughts out.

In textile, it would look like this:

* Item 1
** Sub Item 1
* Item 2

As you can see, it's much easier to read (and type!) the above. It's also less error prone.


In HTML, a link to another site looks like:

<a href="http://www.codingforhire.com">Coding for Hire</a>

While in Textile, it looks like:

 "Coding for Hire":http://www.codingforhire.com"

Going Further

These are only very short examples, and this article is only meant to introduce you to the idea of markdown. From here, I will point you to a few other sites where you can see how to do more advanced (and far more efficient) things like tables, images, and links.

  • Textile Reference - From here, you can learn the whole of textile in just a few minutes.
  • Pier Syntax - If you are using PierCMS, this will allow you to get up to speed with their markdown.
  • Markdown - A full reference for the markdown system.

I guarantee that learning the one of the above systems (it should take no longer than an hour to learn one), will boost your productivity in HTML content development by at least 100%.

If you have done any of this, I would love to hear from you.

Posted by Sergio T. Ruiz at 26 January 2011, 2:50 pm with tags markdown, html, content, development, design link
blog comments powered by Disqus