Hey there! A long time ago I shared my markdown experience in PyCon India 2017. What I missed was a gentle introduction to markdown. Let’s get on with it.
Markdown is amazingly simple and I write my blogs using markdown. Credits go to many folks but the one I remember always is Aaron Swartz. Yup, The Internet’s Own Boy. Here is a list of people involved in markdown. Before starting with this post, I went to the website again to see if I find something new, and it was like a book that you read once and when you read it again you are amazed at what all it had!
Headings are created using a
# symbol. The number of
# symbols define the heading level. Like,
This is the notation I used for the heading of this section.
To emphasize text you can wrap the content with
* or a
_. Like this text is emphasized. Strong tag generally makes text bold. It can be used by wrapping the word with
__. For example: This is strong text.
This is the loveliest part about markdown. It not only makes the raw content easy to write but also beautiful! To write code you just need to indent it with a tab or 4 spaces (or more). Using this markdown also escapes the
& like symbols which would otherwise ruin the writing experience.
This is some text written after indenting with a tab. And hence treated as a code block.
For code used in the paragraph itself like
this is also simple. It just uses backticks (
`) to select the area that contains the code. To type backticks as a code like I did above you need to use double backticks (“) around the single backtick.
Another easy task if you’re using markdown! Just write the text to be hyperlinked in square brackets, immediately followed by the link in parenthesis. This link is written like:
[This link](https://www.duckduckgo.com “Optional Title goes here”)
This “Optional Title goes here” part is the text which appears when you hover your mouse over the hyperlinked text. Another part that I came across when I read about the markdown again was reference-style links. I absolutely forgot about them and they just made my life easier!
You can reference a link using the syntax
[link text][reference] which can also include a space by the way. And then later on anywhere in the text, you can use
[reference]: https://yourlink “optional title goes here”
If you feel too lazy to give the
[reference] part, you can just give blank square brackets like
, in which case it would create a reference with the name of reference text. For example:
[ddg]  [ddg]: https://www.duckduckgo.com
Now whenever I want to create a hyperlink, I just create reference-style links and then add a blank reference at the end of the paragraph. When I complete the blog, I can just fill these instead of jumping repeatedly in between to fetch the links.
Another really useful feature is automatic links. If you just type your link and want it to be clickable. That means, a link directing to a link. To clear out the confusion, let us see another example:
This would appear as https://www.duckduckgo.com. More magical is the email address part. If you specify an email address using this method, the email address is encoded so that spambots can’t harvest it from the source of the page! Here is an example email address: email@example.com
To create an unordered list use
+ or even
- to denote items. An example would look like:
* Item 1 * Item 2 * Another item!
And after processing it’ll turn to:
- Item 1
- Item 2
- Another item!
An ordered list is also easy to write.
1. Item 1 2. Item 2
Important thing is that the numbering doesn’t matter. Shocked? The
number followed by
. pattern just shows that this is an ordered list. You can even type random numbers or can have all the numbers exactly the same. Though it is suggested to use
1. as starting number due to a possible change to support starting of lists from a random number.
This means that:
1. Item 1 1. Another item
is perfectly fine for an ordered list. And it’d appear like:
- Item 1
- Another item
Note: If you want to write a number followed by a dot and don’t mean it to be a list, you can escape the dot by using a
\. For example 123. is written as
As simple as writing
*** will create a horizontal rule(a simple line denoted by
<hr/> tag). Any of
- and even
_ can be used. Spaces are also allowed between them. (The number of such characters has to be three or more)
To use images, the syntax is exactly similar to hyperlinking text with just one exclamation mark preceding it.
If you’ve not come across Alt text yet, it’s the text that is displayed in case image can’t be displayed.
I’ve also used markdown for writing this post and it has been a really pleasant experience.
Just write anything, even short content would do to see how amazing is markdown 🙂 (You may find https://daringfireball.net/projects/markdown/dingus helpful)