1. The Rapid Rise of Markdown
I am an avid reader of ArsTechnica and few days back I read an article on Microsoft overhauling its TechNet and MSDN documentation. This documentation is based on the Markdown markup language . Ever since I started using Github and Gitlab , I have seen Markdown being predominantly used for documentation and readme . I have been planning since then , to take time and understand what this Markdown is all about. So this post is all about Markdown .
What is Markdown ?
Markdown is basically a text-to-html conversion tool for everyone . It allows one to write in simple plain text and the tool will then convert it to valid XHTML or HTML for proper rendering in browsers.
Why was Markdown created ?
Every documentation or readme files needs to be readable. No one wants to read long documentations that runs into pages and pages. In order to make it readable , one also needs to be able to create it easily. In the earlier years , XML and HTML were commonly used. Only users who know these can create the documents. Also over the longer run when the documentation files grow in size and number , it becomes even more difficult to maintain .
Markdown to the rescue. Markdown allows one to write in plain text which means any one can write it . It easy to read and maintain . Still there is a structure or syntax to maintain some sort of standard or you could say design of the final document.
How does Markdown work ?
Markdown has specifically 2 parts
- The plain-text format syntax : This is the one that user uses to write the document.
- A software tool written in Perl which then converts the plain-text to HTML to be rendered in the browsers.
The main part is the syntax and one has to understand it to create the document. It essentially creates a look and feel when its gets converted to html and ultimately in the browser.
So , let’s create a simple Markdown readMe file.
Simple Markdown ReadMe Example
The Markdown has a syntax for all the features currently available. This post is not going to delve deep into it , but rather will touch upon it through example. If you are keen to explore on it , feel free to look here
In general , for any readMe or for that matter any document , we would like to have it in sections , paragraphs and headers as these enable for greater readability and understanding.
I want to write the below content in markdown having structure similar to one below.
ReadMe [Main Header]
1. Introduction [First Section]
A simple example of how markdown is used to create a document or readme file. [Section Contents]
2. Architecture[Second Section]
In this section,we present the overall architecture of the application.The main components are
[Numbered List]
1. Mobile module
2. Webservices module
3. Database module
As you see in the above block , I have a main header followed by 2 sections each having its own content and then there is a numbered list in the second sub section.
The corresponding Markdown will be as shown below
ReadMe
======
1. Introduction
---------------
A simple example of how markdown is used to create a document or readme file.
2. Architecture
---------------
In this section,we present the overall architecture of the application. The main components are
1. Mobile Module
2. Webservices Module
3. Database Module
Couple of comments on the Markdown Source above
- Hyphens and Equals Symbol below the Text (for e.g. ReadMe , Introduction) they indicate different styling to be used.
- Couple lines of text followed by line breaks indicate a paragraph .
- Numbered lists indicate a list of items.
Like this , there are many other features which can be used and these are available in the syntax page.
Once you have written the Markdown source , the next step would be to use the perl tool to convert it to xhtml(html). Normally in case of Github , the framework takes care of conversion and as such we normally don’t use it . It can be easily plugged into your development cycle.
The corresponding html source and the preview source are provided below .
HTML Source : Markdown Perl Tool converts the markdown source to below html .
<h1>ReadMe</h1>
<h2>1. Introduction</h2>
<p>A simple example of how markdown is used to create a document or readme file.</p>
<h2>2. Architecture</h2>
<p>In this section,we present the overall architecture of the application. The main components are </p>
<ol>
<li>Mobile Module</li>
<li>Webservices Module </li>
<li>Database Module </li>
</ol>
What are the advantages of using Markdown ?
The best and most important aspect of Markdown is that it allows you to write in plain-text or what i would say the natural writing way . Just like when you create a report , you start from the beginning , slowly adding sections , sub sections and other items . It a natural way of enhancing readability , because at the end of the day , all I want is that I should be able to read and understand what the documents says. It should also help me get things done and also be easy to maintain.
The second aspect is that it removes the need of knowing a particular language like XML or HTML . Instead it provides a syntax much like English has grammar and as along as syntax is followed , you should be able to write good documentations . Thus this makes for anyone to start using it.
Most of all , it has good manuals to get started . Here is a quick link to Dingus which allows to write Markdown files online.
Summarizing , you should learn Markdown for the below reasons :
- Having Good documentations is a must for any project or application . After all other people should be able to understand what the project or application does , how to use and so on .
- Always keep the end user in mind i.e. Readability is necessary and Markdown helps you achieve that.
- Does not require any new language to be learnt . It just requires that you follow the syntax laid by Markdown.
Have a look at it and start using it .
