background October 15, 2009

Markdown, One Year Later

We made a few key technology bets when we created Stack Overflow: OpenID Markdown ASP.NET MVC I’ll defer the discussion on the other two items for another day, but after spending a year immersed in Markdown — the lightweight markup language we use to format posts on all Trilogy sites — I have some thoughts…
Avatar for Jeff Atwood
Co-Founder (Former)

We made a few key technology bets when we created Stack Overflow:

I’ll defer the discussion on the other two items for another day, but after spending a year immersed in Markdownthe lightweight markup language we use to format posts on all Trilogy sites — I have some thoughts I’d like to share.

We knew early on that there were a handful of Markdown Gotchas, thanks to the sage advice of John Fraser (who, sadly, I have completely lost contact with.) Based on those gotchas, we quickly adjusted our Markdown support to fix a few obvious things:

  1. Removed support for intra-word emphasis like_this_example

  2. Added auto-hyperlink support for http:// URLs in posts

Apparently GitHub also uses Markdown, and they independently arrived at some of the same conclusions we did — synthesizing something they call GitHub Flavored Markdown.

  1. Removed support for intra-word emphasis like_this_example

  2. Added auto-hyperlink support for http:// URLs in posts

  3. Automatic return-based linebreaks instead of “two spaces at end of line” linebreaks

  4. Support for some magic strings that auto-convert to GitHub specific links

Since GitHub and Stack Overflow match exactly on #1 and #2, it’s fairly safe to say that those are in fact deficiencies in Markdown, at least for a programming audience. (Though I’d argue they apply to general audiences, too.)

As for #3, that’s one I hadn’t considered. In normal Markdown, this:

Roses are red¶
Violets are blue¶

Will render like this:

Roses are red violets are blue

The Markdown answer is to add two spaces at the end of the line (or a literal
, I suppose).

Roses are red  ¶
violets are blue¶

Although it’s easy once you know the trick, this is far from intuitive to most. I’m reminded a bit of the double-click mouse problem. I wonder if we should adopt the GitHub linebreak approach here.

As for the fourth item, when text is entered in these specific formats …

* SHA: be6a8cc1c1ecfe9489fb51e4869af15a13fc2cd2
* User@SHA ref: mojombo@be6a8cc1c1ecfe9489fb51e4869af15a13fc2cd2
* User/Project@SHA: mojombo/god@be6a8cc1c1ecfe9489fb51e4869af15a13fc2cd2
* #Num: #1
* User/#Num: mojombo#1
* User/Project#Num: mojombo/god#1

… those magic strings are detected by the GitHub Flavored Markdown and auto-converted into GitHub specific hyperlinks. Something similar has been proposed on meta for internal Stack Overflow references, so this is an idea we’ve been entertaining for some time as well.

Markdown is remarkably flexible, because it allows you to intermix a narrow list of whitelisted HTML tags with Markdown “fancy ASCII” syntax in a fairly logical way, at least most of the time.

So, now that you’ve had a chance to mess around with Markdown for a year — what are your thoughts?

Podcast logo The Stack Overflow Podcast is a weekly conversation about working in software development, learning to code, and the art and culture of computer programming.

Related

newsletter February 21, 2020

The Overflow #11: Efficiently lazy

February 2020 Welcome to ISSUE #11 of The Overflow, a newsletter by developers, for developers, written and curated by the Stack Overflow team and Cassidy Williams of React Training. You can read more about it here. In this week’s newsletter, we’re efficiently lazy, calculating probabilities in chocolates, and thinking about how to maintain open source.…
newsletter March 6, 2020

The Overflow #12: Plain text

Welcome to ISSUE #12 of The Overflow, a newsletter by developers, for developers, written and curated by the Stack Overflow team and Cassidy Williams of React Training. You can read more about it here. In this week's newsletter, we're seeing what's up with Blazor, wondering if it's legal to crack MD5 hashes, and making the most of our JavaScript console.
code-for-a-living November 18, 2019

The Interactive News Platform for Everyone

Journalists have an uneasy relationship with technology. On one hand, journalism at the highest levels still focuses on print distribution, a technology hundreds of years old. On the other hand, even the Gray Lady has a snazzy mobile app and  stories custom made for virtual reality. Traditional news outlets are increasingly discovering the power of…