{"id":3076,"date":"2011-04-08T05:53:23","date_gmt":"2011-04-08T13:53:23","guid":{"rendered":"http:\/\/www.yousephtanha.com\/blog\/?p=3076"},"modified":"2011-04-08T05:53:23","modified_gmt":"2011-04-08T13:53:23","slug":"using-markdown","status":"publish","type":"post","link":"http:\/\/www.yousephtanha.com\/blog\/2011\/04\/08\/using-markdown\/","title":{"rendered":"Using Markdown"},"content":{"rendered":"

I recently wrote about keeping a simple wiki with just text files<\/a>. Text files are fast to open and easy to work with. In fact you can open a text file on any kind of computer running any kind of\u00a0operating\u00a0system and it will just work. If you have a modern\u00a0operating\u00a0system like me, (I am running Mac OS X) you will be able to do a simple find command to not only locate the text file you want but even search within the content of that text file quickly and easily.<\/p>\n

I want to talk a little bit about some ideas on how you should format that text file. There are going to be times where you don’t need to think about formatting your text file. The text file may not contain enough information to bother with formatting. I have text files that just contain the information with in the name of the text file its self, but nothing is actually inside of it. Other times I have so much content in my text file I need to write it in a way that it is\u00a0organized\u00a0and easy to read. This is where Markdown comes into play.<\/p>\n

Wikipedia discribes Markdown<\/a> as this:<\/p>\n

Markdown is a\u00a0lightweight markup language<\/a>, originally created by\u00a0John Gruber<\/a> and\u00a0Aaron Swartz<\/a> allowing people “to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid\u00a0XHTML<\/a> (or\u00a0HTML<\/a>)”. <\/span>The language takes many cues from existing\u00a0conventions<\/a> for marking up\u00a0plain text<\/a> in\u00a0email<\/a>.<\/p><\/blockquote>\n

What does that mean in English? Well, here is how I look at it. Markdown gives you a set of rules for writing a plain text document which gives it\u00a0structure, which makes it easier to read and at the same time allowing it to be rendered into something you would see in a word processor or in HTML with all the correct tags.<\/p>\n

So let me give you an example of what I am talking about. In my post I\u00a0mentioned\u00a0earlier about keeping a very simple wiki, I also talked about one of my favorite recipes, Corned beef. With out using any Markdown what-so-ever here is what the text document looks like when you open it up.<\/p>\n

Slow Cooker Corned Beef and Vegetables<\/p>\n

Prep Time: 15 min
\nTotal Time: 9 hours 15 min
\nMakes: 10 servings<\/p>\n

Ingredients<\/p>\n

2 and 1\/2 pounds medium new potatoes, (about 8), cut in half
\n2 cups baby cut carrots
\n1 cup frozen small whole onions, thawed
\n1 corned beef brisket (3 to 3 1\/2 pounds)
\n1\/8 teaspoon pepper
\n1\/2 cup of water
\n1 tablespoon Worcestershire sauce
\n1 tablespoon cornstarch
\n2 tablespoons cold water<\/p>\n

Directions<\/p>\n

1.) Mix potatoes, carrots and onions in 4 to 6 quart slow cooker
\n2.) Thoroughly rinse corned beef; discard seasoning packet. Place beef on vegetables; sprinkle with pepper. Mix 1\/2 cup water and the Worcestershire sauce; pour over beef.
\n3.) Cover and cook on low heat setting 8 to 9 hours or until beef and vegetables are tender.
\n4.) Remove beef and vegetables from slow cooker; cover to keep warm. Pour juices from slow cooker into 1-quart saucepan; heat to boiling. Mix cornstarch and cold water until smooth; stir into juices. Cook, stirring constantly, until sauce has thickened. Serve sauce with beef and vegetables.<\/p>\n

Nutrition Information<\/p>\n

1 Serving: Calories 340 (Calories from Fat 160 )<\/p><\/blockquote>\n

From\u00a0the get go I am clearly not working with the most complex document on the planet, but I do think it works as a springboard for showing you how to write Markdown and why I think it is so\u00a0beneficial.<\/p>\n

So to get started. We are going to jump right to the top of the document. The first line reads:<\/p>\n

Slow Cooker Corned Beef and Vegetables<\/p><\/blockquote>\n

All we are going to do is at a pound sign in front of the title so it looks like this:<\/p>\n

#Slow Cooker Corned Beef and Vegetables<\/p><\/blockquote>\n

\"\"<\/a>In Markdown a pound sign represents a header 1 tag\u00a0or an H1 tag. The first level header. If we where to put this in a program like Textmate<\/a> (the greatest text editor ever) that can render Markdown, it would render the font large and bold. I will show you an example of this once we get a few more lines written.<\/p>\n

The next three lines of the recipe are:<\/p>\n

Prep Time: 15 min
\nTotal Time: 9 hours 15 min
\nMakes: 10 servings<\/p><\/blockquote>\n

Now with this I want to make an unordered list. Unordered is just an odd way to say that I don’t want my list number or alphabetized. So to do this in my text editor I and going to add a dash and a space in front of each line like this:<\/p>\n

– Prep Time: 15 min
\n– Total Time: 9 hours 15 min
\n– Makes: 10 servings<\/p><\/blockquote>\n

So now my whole plain text document looks like this:<\/p>\n

#Slow Cooker Corned Beef and Vegetables<\/p>\n

– Prep Time: 15 min
\n– Total Time: 9 hours 15 min
\n– Makes: 10 servings<\/p><\/blockquote>\n

So lets look at what this looks like rendered in Textmate:<\/p>\n

\"\"<\/p>\n

Pretty sharp. From Textmate, I could also render out HTML and it would look like this:<\/p>\n

<h1 id=”Slow Cooker Corned Beef and Vegetables”>Slow Cooker Corned Beef and Vegetables<\/p>\n

<ul>
\n<li>Prep Time: 15 min <\/li>
\n<li>Total Time: 9 hours 15 min <\/li>
\n<li>Makes: 10 servings<\/li>
\n<\/ul><\/p><\/blockquote>\n

So lets continue on with the rest of the recipe.<\/p>\n

#Slow Cooker Corned Beef and Vegetables<\/p>\n

– Prep Time: 15 min
\n– Total Time: 9 hours 15 min
\n– Makes: 10 servings<\/p>\n

##Ingredients<\/p>\n

– 2 and 1\/2 pounds medium new potatoes, (about 8), cut in half
\n–\u00a02 cups baby cut carrots
\n–\u00a01 cup frozen small whole onions, thawed
\n–\u00a01 corned beef brisket (3 to 3 1\/2 pounds)
\n–\u00a01\/8 teaspoon pepper
\n–\u00a01\/2 cup of water
\n–\u00a01 tablespoon Worcestershire sauce
\n–\u00a01 tablespoon cornstarch
\n–\u00a02 tablespoons cold water<\/p>\n

##Directions<\/p>\n

1. Mix potatoes, carrots and onions in 4 to 6 quart slow cooker
\n2. Thoroughly rinse corned beef; discard seasoning packet. Place beef on vegetables; sprinkle with pepper. Mix 1\/2 cup water and the Worcestershire sauce; pour over beef.
\n3. Cover and cook on low heat setting 8 to 9 hours or until beef and vegetables are tender.
\n4. Remove beef and vegetables from slow cooker; cover to keep warm. Pour juices from slow cooker into 1-quart saucepan; heat to boiling. Mix cornstarch and cold water until smooth; stir into juices. Cook, stirring constantly, until sauce has thickened. Serve sauce with beef and vegetables.<\/p>\n

##Nutrition Information<\/p>\n

1 Serving: Calories 340 (Calories from Fat 160 )<\/p><\/blockquote>\n

So you will see with the sub headers. The Header 2 or H2 I started the line with two pound signs. You can do this all the way to header 6 or H6 with six pound signs.<\/p>\n

Under “Directions” I also used numbers followed by a period and a space rather than dashes. This means if I render out that section it will be a numbered list. So lets render this out in Textmate and see what we got.<\/p>\n

\"\"<\/p>\n

Not a bad-looking document. Something that looks great and is easy to read as a text file. Giving it\u00a0structure and\u00a0conformity, a\u00a0cleanliness\u00a0that was not there before. It looks even better when rendered out. I hope you I have done a good job explaining how great I think Markdown is and how useful it can be. I will be including all basic formatting\u00a0information\u00a0for Markdown below as my recipe example above did not use all the\u00a0possible\u00a0formatting tags.<\/p>\n

Paragraphs<\/h2>\n

Just write\u00a0sentences\u00a0like you would normally do. No tags for paragraphs are needed.<\/p><\/blockquote>\n

Emphasized text<\/h2>\n

*Italics*\u00a0Anything\u00a0surrounded\u00a0with “*” Is\u00a0italicized.<\/p>\n

**Bold Text** Anything surrounded with two “*” is turned bold.<\/p><\/blockquote>\n

Code<\/h2>\n

Blocking off code inline requires it to be `surrounded` by a backtick.<\/p>\n

Indent several lines of code by at least four spaces.<\/p><\/blockquote>\n

Lists<\/h2>\n

* \u00a0This is an
\n* unordered list
\n* This is a sub list item<\/p>\n

1. This is an
\n2.) in\u00a0an enumerated (ordered) list<\/p><\/blockquote>\n

Headings<\/h2>\n

#First level heading<\/p>\n

##Second level heading<\/p>\n

######Sixth level heading<\/p><\/blockquote>\n

Blockquotes<\/h2>\n

> This text will be enclosed in an HTML blockquote element.
\n> Blockquote elements are reflowable. You may arbitrarily
\n> wrap the text to your liking, and it will all be parsed
\n> into a single blockquote element.<\/p><\/blockquote>\n

Links<\/h2>\n

This is [an example](http:\/\/example.com\/ “Title”) inline link.
\n[This link](http:\/\/example.net\/) has no title attribute.<\/p>\n

This is [an example][id] reference-style link.<\/p>\n

hen, anywhere in the document, you define your link label like this, on a line by itself:
\n[id]: http:\/\/example.com\/ \u00a0“Optional Title Here”<\/p><\/blockquote>\n

Horizontal rules<\/h2>\n

Horizontal rules are created by placing three or more hyphens, asterisks, or underscores on a line by themselves. You may use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule:
\n* * *
\n***
\n*****
\n– – –
\n—————————————<\/p><\/blockquote>\n

For more information on Markdown and to see a few more tags I did not include here please check out the following links.<\/p>\n