What is Markdown and why use it?

The joys of markdown are many.

Markdown is a formatting “language” like HTML that you can use to specify the final appearance of text. When you use a “word processor” like Microsoft Word or Openoffice.org Writer, the text you generate is “marked up” (or “marked down” as it were) with formatting codes that determine how the text looks on a screen or when printed out. If you were to look inside a PDF file you would find commands that do this as well. And, a web page is rendered properly in your browser because of formatting codes in HTML. (If you want to see what the HTML guts of this web page look like and you are using Firefox, just hit ctrl-U and a window with the raw HTML coding will pop up and amaze you.)

Markdown is a version of format coding that has three important characteristics:

  • It is entirely text based (as are many other formatting systems) so you can enter the raw coding in a text editor, or read a file that is “marked down” in a text editor. This makes it hard to truly “break” a file, the files tend to be small, the files can be handled with a number of different tools, and since the coding is all jumbled up and stuff it is hard to make a text-based formatting system proprietary or otherwise secret or hard to write software for.

  • The coding is minimal. Unlike HTML which requires many characters to format a bit of text, markdown uses formatting characters that are both minimalistic and visually intuitive for a human. More about this in a moment.

Here’s an example. The following text uses italics in one place and includes three links, in HTML:

The best places on the web to learn about the evolution of <em>Homo sapiens</em> are <a href="http://scienceblogs.com/gregladen/">Greg Laden’s blog</a>, <a href="http://johnhawks.net/weblog">John Hawks’ blog</a>, and <a href="http://www.talkorigins.org/">Talk Origns</a>.

Here is the same text written in markdown:

The best places on the web to learn about the evolution of *Homo sapiens* are [Greg Laden's blog], [John Hawks blog] and [Talk Origins].

[Greg Laden's blog]:"http://scienceblogs.com/gregladen/"
[John Hawks blog]:"http://johnhawks.net/weblog"
[Talk Origins]:"http://www.talkorigins.org/"

The second text is easier to type (fewer formatting characters) and easier to read (for the same reason).

Markdown is a way of formatting text that is easy, fast, clean, and slightly dangerous. In other words, totally cool. But if markdown codes specify formatting, how does the formatting get put on the text and where does the text go? Well, markdown can be used in connection with LaTex to turn marked-down text into some universal format such as PDF. Or, it can be used to specify text that will be converted into HTML. On a Mac you can get software such as Marked which automatically reads a text file to convert it on the fly into raw HTML and allows this to be previewed on your screen, like this:

Screen Shot 2013-09-07 at 10.21.01 AM

Writing things like blog posts in markdown can be easier, cleaner, and more fun than using those dumb editing boxes that most blogging platforms use, and it is quicker and easier to proofread than HTML code.

In Linux, and probably on other platforms, one might use either the markdown utility or pandoc to render the markdown code. Pandoc uses a variant of classic markdown, and can convert markdown into HTML, LaTex, PDF and many other formats, using in some cases LaTex software that you should already have installed.

Comments

  1. #1 peter
    February 1, 2010

    don’t know why they’d be annoyed… Hyper Text Markup ‘Language’ after all… I think some get a bit annoyed at html being referred to as a ‘programming’ language…

  2. #2 Greg Laden
    February 1, 2010

    Peter: Good point.

    ….. :)

  3. #3 C. Chu
    February 1, 2010

    Greg, you may be interested in Jeff Atwood’s take on the current state of Markdown..

  4. #4 Greg Laden
    February 1, 2010

    C.Chu, thanks for the link.

    The convention known as *markdown* sure is

    * convenient
    * intuitive
    * versatile.

  5. #5 Bert Chadick
    February 2, 2010

    I internally resolved this argument with Hypercard, and I’ve slept just fine ever since.

  6. #6 Jean-Denis Muys
    February 2, 2010

    I guess it would be fair to mention that markdown is the brainchild of John Gruber (http://fireball.net).

    And maybe even that its birthplace was a Mac.

  7. #7 MadScientist
    February 2, 2010

    Aaaaugh! Yet Another Markup Language! I can barely retain my TeX/LaTeX and PostScript abilities (PostScript is a programming language as well as markup while TeX/LaTeX are programmable markup environments).

  8. #8 Greg Laden
    February 2, 2010

    I didn’t discuss the history of Mark-down because I don’t know enough about it yet, but if you go to the link provided then you can follw a link to the current “markdown” site and there might be some information there.

    Also, one thing to keep in mind is that the original markdown language is sed. Sort of. If you don’t like some detail of markdown, you can always make a sed filter that does exactly what you want.

    In fact, markdown does some stuff that would be hard to re-program, and is best used as it is. But other stuff would be very simple to reprogram. So a pre-markdown filter would work nicely. Also, there are problems using markdown with various outputs. I have a hard time geting some markdwon outputs to work with Lyx (so far) I assume a pre- or post-filter would fix that.

  9. #9 David Marjanović
    February 2, 2010

    There are ScienceBlogs that interpret both HTML and markdown in the comments. As a result, it’s almost impossible to post a URL with underscores in it.

  10. #10 MadScientist
    February 3, 2010

    Programming with sed? How bizarre. Are there any emacs LISP implementations? Hehehe.

  11. #11 Marko
    February 3, 2010

    I prefer YAML for markup and Ruby for scripting. But that’s just me. Whatever floats your tags and one-liners.

  12. #12 masklinn
    February 3, 2010

    As a result, it’s almost impossible to post a URL with underscores in it.

    You can escape underscores with backslash (\), and there should be no problem with posting links “fully” (instead of expecting the parser to pick them up): [link text](http://link-url)

    I prefer YAML for markup

    YAML is a data serialization format, it’s a terrible thing to markup text with. And, in fact, it’s never used for that. Meanwhile, that’s the sole role of Markdown (and cousins, such as ReStructured Text or Textile)

  13. #13 abarbarian
    February 5, 2010

    http://antrix.net/stuff/writr/

    An easy peasy tool to use.

  14. #14 Dror Harari
    February 5, 2010

    Were you show the first markdown example, you say: “Here is the same text written in markdown” but actually the words “Homo sapiens” are italicized rather than showing the relevant markdown marking.

  15. #15 Dror Harari
    February 9, 2010

    … and for whomever is curious, the equivalent to Homo sapiens in Markdown is _Homo sapiens_ or *Homo sapiens*.

  16. #16 timberwoof
    September 24, 2010

    HTML and markdown, aren’t considered programming languages because they do not iterate and they do not control flow of execution with logical expressions. IOW, there’s no for/next and no if/then/else.

    That said, markdown is pretty cool. Add to it the ability to embed pictures (but forget the fancy-schmantzy text flow!)and graphviz graps and I’d be really happy.

  17. #17 Greg Laden
    September 24, 2010

    Timberwoof, yes, that is correct, but does that also mean that a typical “hello world” is not really a program, or that a huge percentage of the “html” we see is actually “php”?

    It gets really tricky with things like postcript. Markdown’ed text run through a “compiler” can produce postscript which may well contain if/then constructs. Put it this way: If LaTeX or ps is (marginally) a programming langauge (and they do have the control structures) then markdown is pseudocode.

    Not that it really matters. Markdown is cool!

  18. #18 timberwoof
    September 24, 2010

    Not that it really matters*, my point is that in a Turing-complete programming language, you can make loops and if-then things. In HTML and markup you cannot.

    No, hello.c doesn’t demonstrate every capability of c. Since rap does not demonstrate the lyrical power of English, I do not conclude that English is not poetic.

    When you look at a properly generated web page with a .php name, you will see ordinary html, and not the embedded PHP. PHP is a programming language, but its output is not necessarily a programming language.

    Well, anything can be used to write pseudocode. ;-) (And FORTRAN code can be written in any language.)

    Oh, and none of this matters. Much.

    *No! It doesn’t mater! Arrrgh! ;-) (And I apologize for that wayward comma in my first post. It had been part of a pair offsetting an adjective phrase that I deleted.)

  19. #19 Greg Laden
    September 24, 2010

    What about drop down list boxes on a web page that determine some outcome?

    Can you use HTML to simulate a human being hiding in the next room. THAT’s the real question!

  20. #20 Timberwoof
    September 24, 2010

    That’s the sort of question which when I ask it of my boss, he says, “Excellent question,” and I wonder if he’s slightly annoyed.

    Excellent question! A pop-up list, along with radio buttons, check boxes, and text entry fields, does provide an if/then construct. But it’s only half the decision (the identity of the item chosen). The resulting flow of execution is handled by the server, which then gives you a new web page. There’s no way in HTML to present, say, one set of text if it’s Timberwoof reading it and some other set if it’s some guy who’s nit-picking about whether HTML is Turing-complete. (Yeah, you can do it with Javascript and PHP and Perl. But these are Turing-complete languages.)

    As for your second question, no, but http://alice.pandorabots.com/ lets you do it with a variety of systems.

  21. #21 Greg Laden
    September 25, 2010

    The resulting flow of execution is handled by the server

    Actually, I was thinking that the other part of the flow was handled by a silly human!

  22. #22 Monado
    November 14, 2010

    sed? not runoff, nroff. troff eroff?

  23. #23 Greg Laden
    November 14, 2010

    Runoff, nroff, troff and eroff? Why not Groff?

    Oh, wait, that is groff.

    Yes, that would be fine. Maybe even better, but it helps to use what you know, and sed is more generally useful so I tend to know how to use it more.

  24. #24 Donald Iljazi
    February 14, 2012

    You are wrong about the bracket thing and that you can’t write [something] in brackets you can always do [\[something\]]

  25. #25 Greg Laden
    February 14, 2012

    ” this sort of screw-up can be avoided. There are ways to “escape” characters that are normally used for formatting that you wish to be displayed “

  26. #26 on
    April 2, 2014

    Markdown is crap. It’s a retarded tool for people who try to impress other with their useless knowledge (read: geeks). It’s a step back from WYSIWYG technologies, which got really well.
    It’s awkward to do stuff in this useless “language”. The one who invented this should seriously consider a brain surgery.

Current ye@r *