preHTML tags. From this point on, I will be using GitHub Gist to embed all my code samples here, but in the case of Markdown, I’ll only replace all my HTML code samples with Gist.
Still the Very Basics
Here’s a little recap of what we learned from the previous tutorial:
- Paragraphs and Line Breaks
- How to emphasize a word or a phrase in bold and italic
Using simple special characters that you can find in just a few keystrokes to format your text for the web can get a little hard to get used to, but once you use Markdown more often, it will be just second nature to you when you write your lovely text.
What we will be covering in this section?
In Part 3, we will be focusing on the following:
- Code Examples (preformatted text to show a sample code, code blocks, inline code samples, etc.)
- Lists (unordered and ordered)
- Horizontal Rules
- Inline HTML
- Let’s put it all together!
We will be using this example here:
divtag is an HTML general container tag that doesn’t really have any specific functions unless they are being defined with other attributes, such as CSS styling. You can find more info here at W3Schools and various sources around the internet. Google is everybody’s best friend.
Here’s an example of a
divtag code in action:
You can learn more about HTML in the following sites:
Can Markdown do everything and then automatically convert to HTML?
Not really. Sometimes we would need to mix in a few HTML tags along with Markdown whenever we try to style some text in a certain way. Like this, for example:
It’s the site that we’re on!
You see that text above? We need to use some HTML to create this style because Markdown can’t style that on its own.
Let’s break the example above into the following parts:
- We’ve got two headers on this sample text. One Header 1 and Header 2:
- Header 1: What is a div tag?
- Header 2: Can Markdown do everything and then automatically convert to HTML?
- And then we have two types of code samples and preformatted text:
- Inline code sample: div
- We have a code block showing the example of the usage of the div.
- We have two links on the first paragraph in W3Schools and Google.
- We have an unordered list with linked items: W3Schools, Codeacademy, W3C, as well as … and plenty more sites around the interwebs!
- We have two horizontal rules below the code block and before the sentence: Can Markdown do everything… section.
- And lastly, we’ve got the indented text in between the paragraphs: The NINPOJineous – It’s the site that we’re on! How can we do this kind of indented styling in Markdown? Is it even possible?
So, how do we write all that using Markdown? Again, very simple. This time, let’s do it in a little different way than the previous.
First, let’s write the entire message in plain text. No coding or styling of any sort.
Now we can begin! First, let’s start adding the headers. We already know how to do that.
Now, let’s proceed with the new stuff!
Markdown has also become a standard for many web developers to write their content in their projects, such as README files, online manuals, and other forms of documentation. With web developers, it is required and important to show code examples for their documentation, tutorials (like this one), and more. But how do we do all that with Markdown?
Markdown supports two types: inline code and code block. In our example, we will add an inline code in the following text using backticks.
A `div` tag is an HTML general container tag that doesn't really have any specific functions unless they are being defined with other attributes, such as CSS styling. You can find more info here at W3Schools and various sources around the internet. Google is everybody's best friend. Here's an example of a `div` tag code in action:
From above, the HTML output would look like this:
Wait, what’s a “backtick”
If you are not sure what a backtick
` is, it’s the key right on the top left corner along with the tilde
~. On a Windows keyboard, you can just press that key. On a Mac keyboard, I’ve read that it’s a little more complicated than we think. I read that sometimes the backtick will be located on the top left or the bottom left of the Mac keyboard and sometimes in between. But I am a Windows user, so I won’t have to deal with that.
Now, on our next example, we will make this entire piece of code in a code block:
With code blocks, you don’t need any special characters, but you do need some spacing by pressing the spacebar 4 times or press the Tab key on every line. You end the piece of code with an unindented line.
To illustrate this, let’s use this entire chunk of text and add the necessary Markdown:
The HTML output would be the following below:
There are a lot of ways for you to create links using Markdown. On the first paragraph of our sample text, we have two links: W3Schools and Google.
There are two types of links that Markdown supports: inline and reference.
But first, let’s use the simplest way to link a URL:
Now, let’s go back to that example text that we’ll be using. For inline linking, we use brackets and parentheses to create our chosen text to become links:
For reference linking, it would look like this:
Whichever type you use, they still come out this way in HTML:
I personally prefer the inline style, but the reference style is much cleaner.
Although in our example, we don’t have an ordered list, but I’ll also include them in our section.
We will be using this small piece of text to make an unordered list.
W3Schools Codeacademy W3C … and plenty more sites around the interwebs!
For an unordered list, you can use one of the following: asterisk, plus, or hypen (*, +, -), just like below:
/* asterisk */ * W3Schools * Codeacademy * W3C * ... and plenty more sites around the interwebs! /* plus */ + W3Schools + Codeacademy + W3C + ... and plenty more sites around the interwebs! /* hyphen */ - W3Schools - Codeacademy - W3C - ... and plenty more sites around the interwebs!
Any one of the three special characters will have this same HTML output:
For an ordered list, it’s very simple. Take a guess how:
1. W3Schools 2. Codeacademy 3. W3C 4. ... and plenty more sites around the interwebs!
Just use the numbers in order and you will get this HTML output:
Now that we’re talking about both ordered and unordered lists, what about second level (and beyond) lists? There’s no need for you to do any other extra special characters but you do need to indent the secondary list item underneath the primary list item (4 spaces or the Tab key). Then, just use the special character you were using like any other list. When you’re done adding the secondary list items for that primary list item, you can just unindent the next list item.
Here’s a quick sample of that: (using a different example)
- My favorite fruits: - Grapes - The Muscat kind - The green ones too! - Apples - Especially Fuji and Gala - Bananas - Even the plantain bananas too! - My favorite manga: - Card Captor Sakura - Mermaid Melody Pichi Pichi Pitch - The Kindaichi Case Files
And because our sample text has links, let’s not forget the links!
- [W3Schools](http://www.w3schools.com) - [Codeacademy](http://www.codeacademy.com) - [W3C](http://www.w3.org) - ... and plenty more sites around the interwebs!
Some people call them hairlines or separators, but because I’m a little formal, in HTML, we call them horizontal rules. In case you’re confused, it’s those two lines that surround the list of links that we have on our sample text.
Let’s go back to the list sample text again:
You can learn more about HTML in the following sites: W3Schools Codeacademy W3C … and plenty more sites around the interwebs!
We want to add two horizontal rules above and below this entire block of text. There are three ways to do it: Use the hr HTML tag, 3 asterisks (*), or 3 hyphens (-). You can use either one of the three, but be sure you are consistent with your Markdown markup.
Here they are in all options:
But wait, why are we using an HTML in a Markdown markup?
I’m about to cover that in the next section. Really!
Although Markdown makes it easy for writers and procrastinators to write out their content for their web-based articles or sites, Markdown also has its limitations. When the limitations hit, we have no other choice but to use HTML to style a portion of our content as much as we can.
For instance in our example text, this last part presents a bit of a problem for Markdown:
Can Markdown do everything and then automatically convert to HTML? Not really. Sometimes we would need to mix in a few HTML tags along with Markdown whenever we try to style some text in a certain way. Like this, for example: The NINPOJineous It’s the site that we’re on! You see that text above? We need to use some HTML to create this style because Markdown can’t style that on its own.
The problem here is none other than the indented text that we see in the example text. The solution to indent this portion of the text is to simply use HTML within Markdown, like this:
You can use HTML to mix in with your Markdown syntax whenever needed. It will still be converted to HTML either way.
Let’s put it all together!
Here’s how our Markdown will look like to form the example text above.
On the next section of my Markdown tutorial, I will be introducing the more advanced features, so stay tuned for Part 4! Till then!