ArticlesI have just decommissioned PHP Markdown. It is no longer running at OddThinking.
Why MarkDown is Great
MarkDown is a cool plug-in to WordPress which allows you to markup your text with a different set of “tags” to HTML. It automatically turns the text into HTML as it generates the page.
MarkDown’s philosophy is to make it easier to indicate the desired fonts by making the plain-text look like the formatted text. For example, if you want to emphasize some text, you *write like this!* Want to make it stronger? **Write like this!**
This technique is fairly successful at allowing natural entry of markup (especially for bullet points, which are so much easier to get right in MarkDown than HTML).
Why MarkDown is Not So Great
There are a number of small reasons why I didn’t like MarkDown. None of them are show-stoppers by themselves, but as a group they led me to back away from it.
Basic Premise Not Required
If you need to be able to read a page in both plain-text and in formatted text, MarkDown is great. It is a far more human-readable markup language than HTML, LaTeX, etc.
However, I simply don’t have that need on a blog. I don’t care if the plain text version is ugly; no-one but me needs to read it, and I am technically adept enough to sift through HTML tags (or else I want to see the final formatted version.)
So I don’t value the premise behind the key design decision for MarkDown.
At the Wrong Architectural Level
WordPress has a repository of posts and comment content. This content is used by a number of different components. They have an implicit assumption that the encoding of the content is in HTML.
One of the components is the WordPress comment editor. Another is the engine that renders the page when it sees a the_content() tag. These two components are modified by the MarkDown plugin to handle the new markup language.
However, there are several other components using the same repository. Those components are still expecting the format of the content to be HTML. When MarkDown breaks that assumption, these other components appear to be faulty. MarkDown does not play well with others.
Some examples include:
- WordPress’s
allowed_tags()tag. (Comment authors are not informed that MarkDown is available.) - Live Comment Preview (Comment authors do not see the results of the MarkDown tags until they hit submit.)
- Semagic (Can’t preview MarkDown tags.)
- Textile (Another markup language which has similar issues)
- EmailShroud 1.0.0 (Issue was fixed in EmailShroud 1.0.1)
To correct these issues, I think that MarkDown belongs a layer above where it sits now. It should generate XHTML output, and store that (with additional XML tags as required) in the database (rather than doing it just-in-time generation of XHTML). That way other tools can manipulate the text appropriately. There may be other architectural reasons why this approach may not work.
Coming Down from MarkDown
Moving from HTML blog entries to MarkDown entries is easy. All HTML is legal MarkDown. However, once you start using MarkDown, it is very hard to stop. You can’t just turn off the MarkDown plugin, because all of your old posts will no longer be displayed correctly.
I was forced to write some database scripts to migrate all of my MarkDown text to HTML.
To be fair, I knew this was one of the consequences when I started, and I decided to accept the risk.
Conclusion
I am going to try blogging in pure HTML for a while, and see if I can remember how to do bullet points by hand. Wish me luck!
Comment by Richard on November 21, 2005
<ul> be sorry 🙂
Comment by Richard on November 21, 2005
And that’s no <li>!
Comment by Julian on November 21, 2005
Ah, I know what you’re thinking. ‘Did he use six bullet points, or only five?’ Well, to tell you the truth, in all this excitement, I’ve kinda lost track myself…
Comment by Alastair on November 22, 2005
Julian,
I totally agree that wordpress’ integration of markdown is flawed, and said as much in a previous comment. As you say, it’s an architectural issue. If Markdown to be a first-class citizen in wordpress, instead of merely a plugin, then maybe it might play well with others?
Whether they are directed at the Markdown plugin, or the WordPress architecture as a whole, I’m not sure your ‘plays well with others’ criticisms are entirely valid. Does it matter that you can’t use Live Comment preview with Markdown? Surely it matters more whether you can solve the general problem of comment previews? (eg AJAX Comment Preview, which does AFAICT work with Markdown). Put another way, the incompatability here could be equally seen to be a criticism of Live Comment Preview.
Also complaining that it doesn’t work with Textile is a bit much! Exactly how would you expect these two to work together (assuming the current wordpress architecture) ?
Disagree also with your analysis about which layer Markdown belongs in. The justification here seems to be to allow other tools to work with the generated HTML instead of the Markdown source. Again, this seems to be architecting with a specific technological solution in mind (eg Semagic, which I presume is a blog editor), rather than to best solve the given problem. My blog editor MarsEdit parses Markdown quite nicely, so I for one want Markdown source stored in the blog database and NOT generated HTML.
Bear in mind that blog tools that assume the source text is HTML formatted are already broken, because the “basic” markup provided by WordPress is neither HTML, nor a subset.
Comment by Julian on November 23, 2005
Alastair,
Addressing your points slightly out of order…
I see your point. Yes.
No, I don’t really expect these to work together. They are competing for the same niche. I should have pulled Textile out of this list and addressed it separately. Sorry for the confusion.
My real point is that both Textile and MarkDown are similar in that they each expect all of the other plugins to bend to their will.
Yes, that’s true. As I play some more, with MarkDown turned off, this fact is becoming more relevant and visible to me, which is unfortunate.
I think that our positions here are actually very close.
I think that there is an implicit architecture design decision in WordPress that the database stores HTML-ish formatting, and that MarkDown is bad in failing to conform.
I think that your position is that there could be a range of formats that could be used, including MarkDown, and that if there is a sufficient plugin soup to choose between, you should be able to find a set of plugins that provide a solution to your requirements.
I want to propose a new architecture based on what I got from your message.
There should be sufficient meta-information stored by WordPress, to allow (i) a plug-in to decide whether or not it can read a format and, preferably, (ii) conversions between the formats.
Let Live Comment Preview either say “Hey, I don’t recognise this format” or, even better, “please get me the HTML version of this comment”.
Let Textile and MarkDown co-exist, with each post saying “I’m in MarkDown encoding” or “I’m in Textile encoding” (or I’m HTML-ish, or pure HTML)
Hmmm… sounds like a job for XML. I’m scaring myself.
So, I am kind of agreeing with you. If the WordPress architecture assumes HTML-ish format, MarkDown doesn’t play well. But, if we agree that tools like MarkDown and Textile are key parts of a blog, then the WordPress architecture should be enhanced to provide explicit mechanisms for different plugins to communicate in a common (set of?) encoding.
Comment by Eric on December 7, 2005
You could always use Textile instead.