Markdown
John Gruber has produced another text-to-HTML filter, called Markdown. I use Textile extensively when writing this weblog, and find it very useful. I do know how to write HTML, and I donât find it particularly hard, but using a filter like this just makes it a bit quicker to writeâand perhaps more importantlyâeasier to read and edit. If thereâs too much âcode furnitureâ on a page, it can be hard to pick up spelling or grammatical errors. Sometimes itâs hard to motivate yourself to write, and then any kind of barrier between you and the words on the screen becomes more significant.
Markdown has a smaller syntax set than Textile, but it seems that this is deliberate. It only allows you to encode the kind of HTML formatting that can be represented with plain text. As John Gruber explains:
Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdownâs formatting syntax only addresses issues that can be conveyed in plain text.
This produces very clean markup, which is extremely readable. I particularly like the ability to form reference style links. To keep the main text as uncluttered as possible, you can refer to a URL as follows:
[Google][1]
and have all the referenced URLs listed anywhere else in the document like so:
[Google]: http://www.google.com "Optional title"
It works very neatly and makes it much easier to accumulate links at the bottom of the document as you are researching and writing, and then mark up the links in the text (the references at the bottom are converted to proper inline URLs).
I also like the fact that you can use Markdown to filter text files at the command line, or as a Unix filter in BBEdit, so that you can easily convert any piece of text intended for the web. Iâm going to use the filter for a while and see if I get on with itâif I do, Iâll set up the preferences so that you can also use Markdown in the comments.
Update: For those of you not reading the comments, John Gruber pointed out an error in my examples. With the URL given in the text as:
[Google][1]
you need a reference like this:
[1]: http://www.google.com "Optional title"
1
Thanks for the very nice write-up. Much appreciated.
One quick correction, however. If you write a link like this:
Google</pre>
then the link name you're referring to is "1", and you'll need to define the link like so:
What I would do is write the link like this:
[Google][]</pre>
with an empty set of brackets. Then you can define the link with the name "Google".
Hope this helps.
-J.G.----- John Gruber: Gah! Yes, the latter (lazier) method was the one I actually used in the entry (behind the scenes), but I forgot that I was mixing the two styles with the examples. Thanks for picking it up. And congratulations on a very nice piece of code
by bsag @ 16/03/2004 10:03 pm • Permalink •
2
I found Markdown a couple of days ago myself. Having gotten a bit tired of being without my site, I decided to look at new tools (primarily Blosxom.) As always from using Movable Type, I went to implement both SmartyPants and the Textile plugins. It was when I got SmartyPants that I found out about Markdown.
I tend to do a lot of documentation for work, and my documentation style has carried on at home for quick little text files. My docs almost exactly match the format for Markdown, making implementation wonderfully easy (with the exception of the reference-style URL's, which I quickly adopted.)
I've always hated having to have two (or more) sets of documentation: one in plain text, one in HTML. Markdown eliminates that for me.
by Nathan Ladd @ 17/03/2004 12:03 am • Permalink •
3
Markdown Recently I talked about systems of tagging my blog entries so that specifically I could create lists without needing to write as many tags as words. Since then I've been using Textile quite happily. However, But She's A Girl has...
by The Electric Press @ 17/03/2004 8:04 am • Permalink •
4
Thanks for pointing this out. I've been looking for something exactly like this to minimise the tagging overhead.
btw, sorry for all the repeat trackback pings - Movable Type seems to be going on a pinging frenzy - not sure quite what happened there.
by Dave @ 17/03/2004 9:03 am • Permalink •
5
Nathan Ladd: Thatâs a good idea. I like the fact that itâs pretty similar to the kind of pseudo-formatting I use in emailâvery painless to adopt.
Dave: Donât worryâthat happens to me sometimes, too. Iâve deleted two of the pings.
by bsag @ 17/03/2004 7:03 pm • Permalink •
Page 1 of 1 pages