Using Markdown for READMEs in Open Source projects

On github, virtually all projects provide a README.md file (the “.md” denotes the file as type ‘Markdown’). Markdown is a means to easily style text without having to use real HTML tags – style indication is provided by the use of ASCII characters.

For instance, if you wanted to create a level 1 header (really big), simple prepend the line with ‘#’:

#My Really Big Headline

Markdown was created by John Gruber (of Daring Fireball fame): http://daringfireball.net/projects/markdown/syntax. I use to follow DaringFireball, but stopped when John started turning it into a forum for his political opinions.

Today I tripped on a really neat way to explore Markdown: http://www.markdowntutorial.com. The site presents info along with short lessons, and you must complete each one before the next one appears. Really cool use of HTML and I assume Javascript.

Github lets you embed images in our READMEs when you use Markdown, and thus you can possible users with screen shots of what your code does.

Also, I found a free text editor, LightPaper, that lets you write using Markdown in the left pane, and shows you the rendering in a right pane: http://clockworkengine.com/lightpaper-mac/. It doesn’t show images, but it’s really nice to see in real time what the README will look at in a web browser.

Advertisements