Writing documentation is fun—really, really fun. One of the coolest aspects has been using Markdown to write and format almost all of that documentation.
What is Markdown(.md
)
Markdown is a lightweight markup language created in 2004 by John Gruber and Aaron Swartz. It creates formatted text via a plain-text editor. Unlike HTML or XML
, it is still easily digestible by readers of all backgrounds in its source form.
You don’t need to be a programmer to get the gist of things. And although it borrows its syntax from HTML.
Markdown is used almost everywhere, from GitHub to Slack. It’s the unofficial text writing and formatting standard. Most README
files are written and formatted using Markdown. Most text editors accept it as well.
Why use Markdown?
It’s simple
Markdown is very simple, quicker and easier to learn.
That is its biggest benefit. It hardly takes 30 minutes
to learn and about an hour
to become proficient.
Another added benefit is that Markdown text is easy to parse and read in its raw form. This is important because both XML
and HTML
have a learning curve.
It’s a soft introduction to programming
If you’re new, **Markdown ** works as an interesting peek into the power of code. Markdown’s syntax is simple
if you’ve never coded. Formatting in Markdown might feel like coding.
It’s fast
Markdown makes job easier. Anyone can write with Markdown at a faster than I could with HTML or XML.
It’s collaborative
Markdown is more than just a simplified language
. The power of Markdown is that it levels the playing field for technical writers and fosters collaboration between them.
Basic syntax
Headings
Usually Heading 1
, Heading 2
and Heading 3
are recommended to use for best practices.
Alternative syntax
Bold
Normal Text Bold Text
Normal Text **Bold Text**
OR
Normal Text __Bold Text__
Italic
Italic Text
*Italic Text*
OR
_Italic Text_
Strikethrough
Strikethrough
~~Strikethrough~~
Blockquote
blockquote
> blockquote
Ordered List
First item
Second item
Third item
1. First item
2. Second item
3. Third item
Unordered List
First item
Second item
Third item
- First item
- Second item
- Third item
Code
code
`code`
Horizontal Rule
---
OR
___
Link
[Github](https://github.com/ujjawalmaurya)
Image
![Github profile picture](https://avatars.githubusercontent.com/u/34861422?v=4)