Get familiar with Markdown

Markdown first came across my radar because I reading a readme.md file on GitHub and I couldn’t figure out how/why GitHub was formatting the document. For example, using my open-source Division42.Data as an example,

I was seeing the content of the file looked like this:

image

but it was rendering like this:

image

What kind of sorcery is this?! Well, it turns out that an “.md” is a “markdown” file.

What is Markdown?
Markdown is a much-more simplified way of formatting a document. Even more magical, not only does it render to HTML (if you have a parser), it also makes the actual text look formatted in a similar way! In other words, look at the example above – notice how even as a text file, this gives the same sense of formatting?

There are many, many formatting guides – but take a look at this one from GitHub for example: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

As you can see, you can have headings, indents, bullet lists, numbered lists, tables, etc, etc.

So, markdown is very simply formatting which is parsed by some markdown parser to generate formatted HTML. This means you can have a well-formatted, readable, ASCII text file – which also renders to a well-formatted HTML document.

How can it be used?
Well, GitHub will automatically show/render a “readme.md” file, if it exists in the root of your project. So, you can easily have a formatted readme page for your project. It will automatically be shown to someone looking at the top-level of your project. For example:

https://github.com/Division42LLC/Division42.Data

What I did too was create a VersionHistory.md which gives you a formatted outline of the version history. Nicely formatted as HTML:

image

or as text:

image

Very cool, right?!

Lastly though, Scott Hanselman blogged about a tool that let’s your format information in your application logging, so that you can view flat-file log files, as markdown. In other words, from this “using markdown for effective logging” post, one might format application logs to have right formatting. That is a fundamentally new thing – to have your text file logs formatted nicely!

Bottom Line:
Markdown has very-quickly become the go-to technology for formatting things that should be readable in Notepad, but also optionally readable in a browser. You should make a point to learn and play around with the syntax.

Oh, and if you’re looking for a Windows-based editor, MarkdownPad seems to be the go-to tool that everyone uses – and it is a very well-written tool (my own opinion).

Posted in Computers and Internet, Development Tools, General, Organization will set you free, Professional Development, Uncategorized

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Archives
Categories

Enter your email address to follow this blog and receive notifications of new posts by email.

Join 5 other followers

%d bloggers like this: