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

code-for-a-living December 31, 2021

700,000 lines of code, 20 years, and one developer: How Dwarf Fortress is built

Dwarf Fortress is one of those oddball passion projects that’s broken into Internet consciousness. It’s a free game where you play either an adventurer or a fortress full of dwarves in a randomly generated fantasy world. The simulation runs deep, with new games creating multiple civilizations with histories, mythologies, and artifacts. I reached out to him to see how he’s managed a single, growing codebase over 15+ years, the perils of pathing, and debugging dead cats. Our conversation below has been edited for clarity. 
code-for-a-living December 23, 2021

Best practices for writing code comments

While there are many resources to help programmers write better code—such as books and static analyzers—there are few for writing better comments. While it's easy to measure the quantity of comments in a program, it's hard to measure the quality, and the two are not necessarily correlated. A bad comment is worse than no comment at all. Here are some rules to help you achieve a happy medium.