3.2 Markdown

Markdown is a text to HTML conversion tool that was created by John Gruber almost ten years ago in 2004. Now as we author in Markdown you will. Soon realise that because we strip away much of the HTML tags, the authoring appears very light. And then we use various tools, such as Desktop apps, or browser, or frameworks to kind of render the HTML out of it. And I assure you it is also tremendously fun to do so. So firstly, let's look at the syntax. If you go to the documentation itself, the syntax is very clear and more importantly it is very easy to pick up. So we will go through a lot of HTML tags. Just paragraphs, headers, code block, lists. Now, before we dive into Markdown, I wanted to point out, so before we delve into the markdown syntax, I wanted to point out that many times the read-me files will be done in the markdown format. Now, note here, the authors did not code this in HTML. He actually did it in Markdown and GitHub parser actually rendered it as HTML. So it is really fun to pick up and let's get started with the Markdown concept. Now this is probably something you will not do everyday but just for the fun of it let's see how Markdown actually works. So I'm just gonna download Markdown version 1,0.1. And after I open up the zip file, let's go and see what it is inside. Essentially two of this are just text files, which is for us, developers, to read through. But we are just using one file, which is one pearl file, markdown.pl. And we'll be using to quote it out. So let's create a brand new file. So I add inside my terminal, inside the folder that consists of the three files, and I also created an empty file called input.md, md stands for Markdown. Why don't we include a very simple Markdown content. And in this case, I'll just do hatch and then let's just put the heading which is Markdown. Hash is simply refers to header one tags in html, so whenever you include one hatch and then a content it basically renders into a H1 tag. Why don't we include this inside input.nd. Great, so now input.nd basically has #markdown. So if you want to use the original file which is the Perl file Markdown.pl. Let's see how you can compile it. So I'll, I'll say Perl. Now just make sure that Perl is actually installed in your machine. Perl is a programming language. And then after this, we'll simply do Markdown.pl, and then we'll do input.md and output to .html file. Whoops, I obviously did a wrong command. It should be Perl and not person. And there you go. I have an html file, so there you go, Markdown is as shown in the browser and of course, the view source is, as you guessed. This profile will convert the text into HTML. So there you have it, a very simple way of converting text to HTML. I will be firing up this application called Mou, so that I can code side by side and you'll be able to see the result in HTML immediately. So firstly in this case let me just create a file called readme,md, for Markdown. And let me just open this up and it is completely empty as of now. Now let's do the familiar thing that we learned which is hash and then markdown. So this is a header 1 tag. Now why don't we go ahead and explore more header tags. So if you do a double hash and then you do. The content, you will notice that it will be slightly smaller, it will also be rendered as a header two tag. Similarly three # signs will be header three, and of course you might have guessed the pattern by now, four # signs will be header four. Header 5 and lastly header 6. Next let's try out some paragraph. For this I'll just select text from this wonderful website Fillerati. And I'll just select maybe 59 words. And in order to create a paragraph, all I need to do is just paste in the text. And if you want a new paragraph, you just need to paste in the text with a line break. This will easily be rendered as paragraph. Let me quickly show you the preference panel for MOAB. Over here I like to enable scrolling. Later you will understand why, because when. This portion of the Markdown syntax gets very long when you scroll this side will also scroll in sync. Very cool. The other thing that you can play with, basically the editing base bond or the indentation. Lastly you can try some themes as well, pretty cool. More paper, tomorrow blue, writer, maybe I should try more air fresh, or air plus. Now notice that whenever there's a plus sign it will actually show you the bigger text in terms of the header tags or wherever it's needed. But if you don't choose the plus sign it will not be shown. So, why don't I try fresh air? All right, that looks good. The other one is CSS. Over here I like to include it in the GitHub format, because I churn out a lot of files that goes into GitHub. And, hence, the Github CSS helps me see how it will eventually turn out to be. You can definitely try the rest. For example, the Clearness. You will notice that this side of the HTML file will keep changing, or Clearness dark, which will give you a dark theme. All right, so I'll just keep it to Github. And, of course, you can even reload or edit it, as well. The next thing is a block code. To include block code it will be as simple as including this less than sign and then sentence. Once again I'll just copy some text from here and put it like this and notice here it will give this a little black code or indented sort of html. Let's include some formatting shall we, so maybe lists. And here, maybe I'll say paragraphs. All right, great. So for lists I will include say, ordered lists. With a little bit of header three tag, heading. So let's say number one can say apple. Number two, banana, number three, orange. Notices your, when you press enter your app will automatically give you 4. but often times it might be cutting and pasting stuff from other places. In this case, it is perfectly fine to just put it as one, one, and one. And, guess what? The more app will, kind of, render it out for you. Now, let's try out a bit of un-ordered list. Same thing. Apple, banana, orange, and pineapple. Now, notice here, as I'm scrolling on the left-hand side, the right-hand side. Side of the rendered HTML scrolls together with it. Next let's try to include some images so for in this case why don't we try to include this? All right, that looks good. So I'm just going to copy this, get it to my folders so wget. And I have a Tutsplus.jpg inside my folder. So now that it is inside the same folder as this file how do we include it? First we will have the exclamation mark and then within square brackets we will put the value of the alt-text for image tags. So let's say in this case I'll just say tuts+ and inside here I will have the path to the image. Now the path to the image would just be tuts+.jpeg because it is in the same folder. And, there you go. You can see the image right here. Next, we will include the hyperlink, and the format is very similar to the image actually. But instead of the exclamation mark, we sill start straight away with the square brackets, and then we will put in the text. So, in this case it's tuts plus. And inside the rounded brackets we will put in the link. And there you go. You can see that this is hyperlinked and if you click this it will bring us straight to the tutsplus.com in the browser. Finally, we also need to learn how to add escape sequences. So, let's see we are looking at vis sort of Wikipedia page. Which ends with a bracket right at at the end, so how are we going to link it? So same thing. And here we include the link. Now, let's see what happens here. Here, you will notice that it will be slightly broken, because we will need to put in the escape sequence. So, for this, we will just need to put in backslash, just like the rest of the programming languages. But now when we click a closure in programming, yep, it will bring us to the correct Wikipedia page. Finally, let's say we want to include a snippet of code, which is very usual for us developers. So let's say I will, type in a sentence to compile markdown to html. So over here it will be a command that we usually put in the terminal. So how do we code that out in HTML? Usually it will be inside the code tags. So to simulate that in markdown syntax we just need to put in the tilde sign. And inside here we will put in the syntax. For us as you remember it was a Perl markdown. And then input.md to output.html. And once you do that, when you come back here, notice it has this sort of code, design to it. Great. Now what if you want to do it as a block of code, like, you don't have just a line, but you have multiple lines for that we will do. The tildas and then another three tildas. Now this is probably specific to the Github way of doing things as well. And inside here we will paste in the code. So for our simplicity I will go to the HTML five boilerplate. And let's just go to the CSS and there you go. You have a multiple lines of code that are properly formatted. Now the cool thing about Markdown is also that you can also put in HTML so. So let's try it with a table syntax. Once we're done with that, we scroll up and there you go. We have the table rendered out for us. So, once again, markdown, as you can see, is really simple. You can create header tags, you can create paragraphs, lists, both un-ordered and ordered. Images, hyperlinks, code, tables, the usual stuff that we as developers need to create a documentation file or even for blogging purpose. So let's quickly view other useful websites related to Markdown. Now I have showed you. From the Mou app, which is a desktop editor. There is also Showdown which is a browser based editor. Now notice, once again you can very clearly, like, remove everything, clean it up, and then go, like, header and then, as usual, you have paragraph. Or you can also have a block code like this. So it's very similar to moab just that it is browser driven. And very nicely, you can also do the html output. So let's check it out. And, yep, there you go. You have the paragraph, block code h1 all done up for you. So you might thinking where else can I use markdown files other than creating documentation. Well there are plenty of users for using this Markdown syntax. A quick search on the Github we will already give you many such libraries. For example jekyll is a very popular blogging software among developers. And over here you can also write your blog post in actually Markdown and it will convert it to HTML for you. So, that was Markdown, and I bet it was really fun and easy to use, and you can get started with it right today.