Markdown is a lightweight markup language used by technical professionals to create/edit technical documents and create rich text using a plain text editor. With Markdown, you write text in a plain text editor (such as vi, Emacs, nano, notepad), inserting special characters to create headers, boldface, bullets, paragraphs, links, images and so on. This article would provide a comprehensive guide to help you get started using markdown.
Fun fact: This article is written in markdown.
Why Markdown?
The Markdown language was created in 2004 with readability as its key design goal. Its variants are currently used by renown sites like Slack, Github, BitBucket, Reddit, StackExchange and Hashnode to create rich text and facilitate discussions between users. As Markdown has a very gentle learning curve, its basic concepts can be mastered within minutes. For example, the following text is a simple document formatted with Markdown.
### Markdown has a gentle learning curve.
Markdown parsers convert markdown files into **HTML** or **XHTML**. Browsers then display _resulting_ HTML files to *readers*.
The rendered version of the markdown file above is shown below.
Markdown has a gentle learning curve.
Markdown parsers convert markdown files into HTML or XHTML. Browsers then display resulting HTML files to readers.
Note: StackEdit is an online markdown playground where you can practice markdown concepts you would learn in this guide.
Headers
Headers are formatting conventions used in websites, magazine articles, scientific journals, technical documentation and newspapers to draw attention to a section. There are six types of headers as shown below in decreasing sizes:
Header one
Header two
Header three
Header four
Header five
Header six
Conventionally, in websites, headers help to optimize accessibility by acting as titles and subtitles above sections and subsections.
While HTML tags <h1> <h2> <h3> <h4> <h5> <h6> are used to create headers in HTML, the same convention can be achieved in Markdown by prefixing the phrase with a hash (#). The number of hashes should correspond to the size of the header you want. That is — for h1, use one hash, for h3, use three hashes.
The following shows the header types example above in markdown
# Header one
## Header two
### Header three
#### Header four
##### Header five
###### Header six
Italicizing and Bold
We would proceed to learn two other formatting conventions: italics and bold.
Conventionally, these formatting conventions draw attention to formatted text. In HTML, texts are italicized with tags <i> and <em> and are bolded with tags <b> and <strong> notwithstanding the semantic implication of individual tags. However, the same formatting convention can be achieved in Markdown.
To italicize in Markdown, you surround texts with an underscore (_).
The following example shows a markdown file with italicized text:
_Italicizing text in Markdown is easy_. Ta-da!
The rendered markdown document is shown below.
Italicizing text in Markdown is easy. Ta-da!
Similarly, to make text bold in Markdown, you surround words with two asterisks (**).
This is a **bold text**.
**Another bold text**
The rendered markdown document is shown below.
This is a bold text.
Another bold text
Blockquotes
Blockquotes are a formatting convention used to call attention to a quote from another source or a contextually important block of text. To create a blockquote in Markdown, prefix each line/sentence with the "greater than" caret (>). In the following example, a quotation is turned into a block quote
> While Markdown is a minimal markup language and is read and edited with a normal text editor, there are specially designed editors that preview the files with styles, which are available for all major platforms.
The rendered markdown document is shown below
While Markdown is a minimal markup language and is read and edited with a normal text editor, there are specially designed editors that preview the files with styles, which are available for all major platforms.
If a quote spans multiple paragraphs, caret characters (>) should be placed at the start of each line. In this case, blank inter-paragraph lines must also be prefixed with a caret to ensure common grouping of the entire blockquote.
> This is the first line of this multi-line quote.
>
> Oh! There's a blank line above also prefixed with a caret.
> This is the second line of this multi-line quote.
The above is rendered as shown below
This is the first line of this multi-line quote.
Oh! There's a blank line above also prefixed with a caret.
This is the second line of this multi-line quote.
Links
Links can also be created in Markdown. There are two different linking conventions in Markdown:
- Inline links
- Reference links
However, both conventions render the exact same way. To create an inline link, wrap the link text in brackets ([]), and the link in parentheses (()).
This is an inline link example
[Visit Example](https://example.com)
The above is rendered as shown below.
This is an inline link example
Visit Example.
However, in reference links, the links are text references to a dictionary of links somewhere in the document.
[Here is a reference link][First Reference]
[Here is another reference link][Second Reference]
[This links to Google][Google]
[This links to my portfolio][Portfolio]
[First Reference]: https://github.com
[Second Reference]: https://stackoverflow.com
[Google]: https://google.com
[Portfolio]: https://ifeanyimuogbo.tech
The markdown is rendered as shown below.
Here is a reference link
Here is another reference link
This links to Google
This links to my portfolio
As demonstrated in this example, reference links do not appear in the rendered markdown. They are defined by providing the tag name wrapped in brackets, followed by a colon, followed by the corresponding link.
Images
Image creation in Markdown follows nearly the same syntax used in link creation. The only difference between both is that images are prefixed with an exclamation mark (!) while links are not. Conversely, two conventions exists for creating images in markdown:
- Inline image link
- Reference image link
To create an inline image link, prefix a link with an exclamation mark.
The image link text does not display as it becomes the image alt text. Although it isn't compulsory to supply an alt text, it optimizes your image's accessibility and hence makes your website/document accessible to your audience (including visually impaired people).
Similarly, to create a reference image link, assign a bracketed dictionary text as image link.
![Adult brown chow-chow][Dog]
[Dog]: https://images.unsplash.com/photo-1559515796-f24c8045ea9d?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1055&q=80
Lists
Lists can also be created in Markdown. Two routinely used types of list exist:
- Ordered list
- Unordered list
Both types can be created in markdown.
The unordered list, <ul> in HTML, can be created by prefixing each item in the list with an asterisk (*).
* First Item
* Second Item
* Third Item
* Fourth Item
* Fifth Item
The markdown is rendered as shown below.
- First Item
- Second Item
- Third Item
- Fourth Item
- Fifth Item
The ordered list, <ol> in HTML, can be created by prefixing each item with its corresponding number (the exact way it renders).
1. Item One
2. Item Two
3. Item Three
4. Item Four
5. Item Five
The markdown is rendered as shown below.
- Item One
- Item Two
- Item Three
- Item Four
- Item Five
Lists can be nested by indenting each asterisk one space more than the preceding item.
* First Item
* Nested in First Item
* Second Item
* Nested in Second Item
- First Item
- Nested in First Item
- Second Item
- Nested in Second Item
Paragraphs
Paragraphs in Markdown can be formatted with any of these.
- Hard breaks
- Soft breaks
Hard breaks are accomplished by inserting a new line after a paragraph the usual way while soft breaks are accomplished by inserting two spaces after each new line. Although it is impossible to display either a new line or space in these code blocks, 'new line' would be represented with [new line] and space would be represented with [space].
This paragraph is formatted with a hard break.
[new line]
Another line in this paragraph
[new line]
Yet another line in this paragraph
This paragraph is formatted with a hard break.
Another line in this paragraph
Yet another line in this paragraph
This paragraph is formatted with a soft break.[space][space]
Another line in this paragraph[space][space]
Yet another line in this paragraph
While a hard break breaks the togetherness, a soft break preserves togetherness in a block of text.
What's Next?
Congratulations: You are now grounded in the basics of the Markdown markup language. However, it is important to understand that we have only covered the basics of what can be accomplished with Markdown.
There are quite a number of extended implementations of Markdown that supports formats like tables, footnotes and more. These nonstandard implementations are outside the scope of this article as this article only attempts to cover the basics of standard markdown. A sequel to this article would explore these implementations.
I hope you enjoyed reading this article and learned a thing or two. If you did, drop your comments and reactions, share this post and join my newsletter to get notified when I write a sequel.