2016-07-04

MarkDown is the Easy MarkUP

Generally when you are preparing documentation of your app / software, HTML markups are greatly preferred, as they can be used to put up on the website and people can benefit from it.

HTML Markup's inherent problem

Though HTML is a great language for writing documents for web, It requires some technical knowledge for a person to compose a decent documentation. You always need to key in the markups like <h1> Welcome To neps.in</h1>. You should pay extra attention to make sure each open tags are closed properly. They are properly nested. Browser never does error reporting when you miss out the closing tags, or you misspel a tag, rathers it simply interprets in its own way. Sometimes it become very messy when you are using multiple level of nesting of various tags like.

<ul>
    <li>Living Things
        <ul>
            <li>Animals</li>
            <li>Plants</li>
            <li>Human Beings</li>
        </ul>
    </li>
    <li>Non Living Things
        <ul>
            <li>Table</li>
            <li>Chair</li>
        </ul>
    </li>

</ul>

In the above markup, its quite easy to miss out a <li> or miss out </ul> closing ul after Human Beings is going to change the original view of your document.

Markup That is properly nested

list-right.png

When you miss a </ul> the entire structure gets changed as below

<ul>
    <li>Living Things
        <ul>
            <li>Animals</li>
            <li>Plants</li>
            <li>Human Beings</li>
        <!-- </ul> is missing -->
    </li>
    <li>Non Living Things</li>
</ul>

list-wrong.png

Readibility is hard

Another common problem when using HTML Markup its very hard to read. You lose focus of the content to the Markup Structures, or you have a browser window open side by side to preview it. Switching back and forth would be quite a bit of hell.

Problems with Using Wordpress or other CMS

So a better Solution is to use a CMS like Joomla or Wordpress. Sounds like a great win. you don't need to pay attention to writing a structured markups. But They have a different set of problems.

Creating content would be easy but its normally time consuming because many times WYSIWYG editors inserts page breaks </br> at places that are not required. This could lead to lot of page inconsistent look.

Adding Code snippets is like adding fuel to the fire.

It becomes really challenging when you have some code snippets in your documentation. You often need to switch between Visual Mode and Text Mode. During these switching also the editor inserts unwanted </br> and makes really painful.

Markdown is the Solution.

Markdown is basically a set of syntax. Damm Simple, and its also a tool to generate HTML from the same Markdown Syntax. This was created by JOHN GRUBER.

Markdown makes it easy for you to write and read. All you need to remember is few Simple Markup structures that are easy to key in. Once you compose your document give as input to a markdown to html generator and generate HTML content. You can directly use it wherever you want, it could be a wordpress blog or joomla cms.

Markdown References

  1. Markdown CheatSheet
  2. Stack Edit - In-browser MD document editor
  3. Minimalist Online Markdown Editor