Markdown in-depth

Hi there, if you are looking to get familiar with markdown language, or to clear the confusion between markup, markdown, common-mark... and all that jazz, or even go a bit deeper about the subject, you are in the right spot, i hope you enjoy the ride and you take something useful with you from this post.

So, what is all that about, an easy answer is, it's just a text formatting thing, which is not something new, almost every text editor have a text formatting mechanism no matter how rich it is, even with a sticky note now you can make your text bold, italic change the color and make a list, but there are differences between them.

The old well-known system for that matter is WYSIWYG, an abbreviation for what you see is what you get, this one is used in MS word and most texts editors, easy to use and very rich, you can buttons to formats words and phrases, but it's not suitable for all kinds of documents, especially for a web page where you need the syntax to add to the text to indicate which words and phrases should look different, that's where HTML comes to play.

HTML stands for Hypertext Markup Language is the standard markup language for documents designed to be displayed in a web browser, it's a syntax sugar where you add elements to your text to change its look, here is a basic example of that.

<h1>This is a title</h1>

<strong>This text should look bold</strong>

You can add attributes to those elements for further specification and you can apply some styling like CSS for even more formatting, HTML now is fundamental in web development, very rich and very expressive, but with great power comes great fall downs, when applying many elements and attributes the text becomes unreadable, also with the huge number of elements and attributes it becomes challenging to write a document without switching back and forth between the text editor and the HTML interpreter, this opens the doors for markdown language to kick in.

Markdown is a lightweight version of markup, a simpler syntax to add to format a text, and it could be converted to HTML and other formats, it focuses on readability and ease of use, so anyone can work with it without any learning curve. It is mainly used for documentation files, GitHub readme, forum, and blog posts, and with the rise of static site generators, markdown becomes a big player in the web, as almost all the big SSG, from Gatsby to Hugo to Jekyll uses it as the formatting language for their output.

Now that we are familiar with the context let's get a bit practical and see how easy it is to learn how to work with markdown.

<!-- Heading : you only add a # before the text -->
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

<!-- Italics -->
*This part is in italc* this is not
_This part is in italc_ this is not

<!-- Strong  -->
**This part is in strong** this is not
__This part is in strong__ this is not

<!-- Strikethrough -->
~~Strikethrough this~~ not this

<!-- Separator -->
---
___

<!-- Blockquote -->
> This is a quote

<!-- Links -->
[Some text](Some link)
[Some text](Some link "Some tag")
![Image title](Image link)

<!-- UL -->
* Item 1
* Item 2
  * Nested item

<!-- OL -->
1. Item 1
1. Item 2
1. Item 3

<!-- Inline code bloc -->
`<p>This is a paragraph</p>`

This is it, you can now go to the wild fearing nothing.

After noticing the potential for this easy way to write for the web, many flavors of the language start to appear, the important ones to know about are GFM or GitHub Flavored Markdown which is a superset of commonmark the markdown specification, a standardization effort aims to document various tools and resources available to document authors and developers, as well as implementors of the various markdown implementations, it's basically the same thing with some more capabilities and small variation, the second flavor is Markdown Extra as the name said, it adds features not available with plain Markdown syntax such as

• markdown markup inside HTML blocks
• elements with id/class attribute
• fenced code blocks that span multiple lines of code
• definition lists
• footnotes
• abbreviations

By now you are capable of writing markdown documents, you know the context in which all this jazz is happening, and you can extend your skills by looking at commonmark, GFM, or markdown extra, all of them are well documented and easy to digest. If you are not tired yet, we can dive a bit more here.

The obvious question now is, how markdown works? well, not because it is easy there is not much happening under the hood, it's the opposite, it is easy because it hides the stuff happening behind the scenes. When you write markdown the text is stored in a plain text file with .md or .markdown extension, then you will need a markdown application to process the file by converting it to an HTML so it can be displayed in a web browser or to a print-ready document, for that matter they use a markdown processor called parser, the various implementation of the parser gives you the ability to do almost everything with the language:

• Websites
  It is essentially designed for the web, so there are a lot of applications for that, for a simple way to do that you can check, blot.im, and smallvictori.es, you only need to signup and have a Dropbox to host your files and boom, you have a website, for more advanced stuff, you can use one of the SSG mentioned above, the advantage to this approach is that GitHub pages provide free hosting for those websites, you can add a CMS to manage your content, easy and free from services like Ghost.

• Documents
  It doesn't have all the fancy stuff of MS word processors but for basic documents you can do pretty much anything, you can use some authoring application to create and export to PDF then do whatever you want with the PDF, for the authoring part you can use, iA Writer, Ulysses for Mac, iOS and Android, MarkdownPad for Windows and Dillinger or StackEdit for the web.

• Notes
  Unfortunately, Evernote and OneNote don't support the language yet, there are some other solutions such as SimpleNote, Bear, and BoostNote which can do the work pretty well.

• Books
  If you are looking to self-publish, Try Leanpub, it's a nice service that takes your markdown files and converts them into an electronic book, it has many output format, it can produce PDF, EPUB, or MOBI.

• Documentation
  Markdown is a natural fit for technical documentation, if you write documentation for a product or service, you should check these, Read the Docs which generates a documentation website from your open-source markdown, MkDocs, Docusaurus, VuePress those are SSG oriented toward documentation generation.

That's it for now, i hope you get something for this post.