Introduction to Markdown

What is Markdown?

Markdown is a markup language used to format documents of all types, created by John Gruber and Aaron Swartz in 2004, today it is one of the most popular languages ​​among programmers.

According to Wikipedia:

NOTE: A markup language is composed of a specific set of tags or symbols used to correctly apply stylization to content, the most popular ones are undoubtedly HTML, XML, and Markdown.

The image below shows a file formatted with Markdown using the Sublime Text editor.

A Markdown file is typically composed of plain text, is easy to intuitively understand and doesn't have all that HTML markup polluting the essential content.

NOTE: MD is short for Markdown.

With Markdown you can smilingly add formatting to your documents conveniently using simple markup symbols.

It's critical to carefully note that Markdown formatting is different from the formatting used by WYSIWYG editors.

NOTE: WYSIWYG stands for "What You See Is What You Get". Basically, the formatting of the content happens in real time, that is, it's visible immediately. To learn more you can read this Wikipedia article.

For example, in Microsoft Word, which is a WYSIWYG editor, text formatting occurs when selecting a certain content and pressing a specific button, a key combination or clicking on some menu option.

In Markdown, formatting is applied using symbols such as the hash #, the asterisk * and the underscore _.

This symbology is used by the Markdown processor to know which words / phrases should be formatted when converting your file to HTML.

For example, **I want this text to be bold** and _this text is in italics_

Too confusing? Let's simplify it a little bit.

When you surround the content with two asterisks ** you emphasize it in bold, in the second example, we used the underscore _ character to apply italics to the text.

How to edit a Markdown file

A Markdown file is nothing more but text, so any simple text editor is enough for the task.

However, it is interesting to take into account:

• An editor that allows you to convert the Markdown document to another format.
• An editor that can highlight Markdown syntax.
• An editor that shows the conversion to HTML in real time.

The good news is that:

• There are several Markdown applications for various operating systems, including, for Windows, for Linux, for Android and even, for iOS.
• When it comes to the Web, things get even better, several sites offer free Markdown applications for you to edit your documents online, and many have a real-time converter, that is, as you type the application converts Markdown to HTML.

NOTE: It is worth remembering that Markdown formatting is extremely simple, therefore, a document formatted with this language, is still readable.

Markdown vs WYSIWYG

If a WYSIWYG editor (which offers real-time formatting) is extremely convenient, why should I use Markdown?

If using a WYSIWYG editor I can press a button and have the formatting I want, why am I going to type a document with Markdown markup?

Let's look at some reasons to use Markdown:

• Markdown can be used to create almost any type of document, whether it's websites, books, presentations, e-mails, technical documentation and more.
• Markdown's portability is exceptional. Because it is a plain text document, it can be edited in any text application. If we contrast with Microsoft Word, the .docx format is proprietary and needs a specific program to be opened, which is not the case with the .md file.
• Freedom to choose which program to use when editing your documents, an .md file can be edited anywhere.
• No matter what operating system you use, Windows, Mac or Android, Markdown is supported.
• Have your document accessible even in the event of a catastrophe. Does your favorite text editor no longer work? Has support ended? Did the program become paid? No problem, just choose any other text editor and continue editing and accessing your document, which is extremely important for files such as technical documentation, books and TCCs.
• The giant Markdown community has made it accessible on a variety of sites as a standard language for formatting posts. Github and Reddit are examples of great sites using Markdown.
• A large number of people already use Markdown, so your formatted documents will be understood by more and more people.

Practicing

The best way to learn is practicing!

It is interesting to have a Markdown editor available while learning the language syntax.

The quickest way to start practicing Markdown is to use online editors. With web applications you don't need to download anything, just go to the website and start editing your .md file.

StackEdit, Dillinger and Editor.md (Markeditor) are good options to start with.

NOTE: Open one of the online editors in another tab of your browser and take the opportunity to train the Markdown syntax in real time.

StackEdit

The StackEdit editor is one of the most complete applications. In addition to the editor, it also provides a real-time converter that renders HTML and shows the result in the right panel.

You can see more information about the StackEdit editor in the tools section.

Dillinger

Dillinger has a very simple interface, but it offers several options for editing your Markdown document. In addition to real-time conversion you can also export the file to HTML and PDF formats

For more information on Dillinger click here.

Editor.md (Markeditor)

Editor.md is an open source tool, has an MD to HTML converter in real time and buttons that allow you to create a Markdown element with just one click.

Now what?

After gaining more experience, you can download an application for your operating system and start editing documents offline.

In the tools section you will find an extensive list of applications with instructions on how to use them, in addition, of course, information on compatibility with Markdown elements.

Well, now that you have an editor available to practice Markdown let's understand how the conversion, from one format to another, works.

How to Convert a Markdown File

Let's understand the procedure used by Markdown applications to convert your .md file to another format, usually HTML or PDF.

The simplicity of Markdown

How do you identify a Markdown file? By the extension, correct? Usually .md or .markdown.

A Markdown file is plain text, has no formatting, is neither an encrypted file nor a compiled file.

NOTE: This simplicity allows programs to analyze your text content and look for symbols that identify Markdown elements.

Several Markdown applications, in addition to the editor, also have an integrated converter. The converter is responsible for translating the Markdown syntax into another format.

How the conversion works

The Markdown converter uses a Parser to scan the file content searching for tags compatible with Markdown. Found any? Cool, now, it checks for a match, that is, a similar markup in the output format, for example, an HTML tag.

Below you can see an example, side by side, comparing the Markdown formatting syntax with the HTML tag.

Note that the HTML format is one of the most used when it comes to converting Markdown. Your file converted to HTML can be viewed in any web browser such as Google Chrome, Mozilla Firefox and Microsoft Edge.

The image below shows how the conversion process takes place, the simplified version, at least.

NOTE: It is important to note that, in a more robust application, the components can be separated, even, they can be independent of each other. The editor, the converter, the parser, etc. The image above is just a simple representation of how the process occurs.

Let's summarize the conversion in four steps.

• First we have to create a Markdown file, for that, we add the extension .md or .markdown when saving the document. For editing, any text editor will do the job.
• Then, we load the file into some Markdown application.
• The time has come to convert to another format, in our case, HTML. In this step, an application dedicated to Markdown is essential.
• View the conversion result. If it's HTML, just load the file in a web browser.

Some points should be highlighted.

• This procedure may vary a lot depending on where you're editing the Markdown file.
• When we talk about simple editing, that is, using any generic editor, these steps are more evident.
• In the case of online editors such as Dillinger, StackEdit and Editor.md, there is a merging of steps 2,3 and 4 directly into the graphical interface of these applications.

Using Markdown

Ok, Markdown is simple, easy to learn and compatible with "everything", but, exactly what types of documents can I create with this markup language?

Right away, we can say that the web content creation is the most popular way of using Markdown. Not only in generating HTML pages, but also when creation and editing posts of all types, from simple comments on forums to writing important technical documentation.

You can also format task lists, email messages, shopping lists and much more.

Below you can see some examples of documents that can be created using Markdown.

Websites

John Gruber and Aaron Swartz developed Markdown thinking about the Internet, so creating content for the web has become one of the biggest attractions of the language.

Many applications, compatible with Markdown, convert your content automatically to HTML.

You can create complete websites using Markdown formatted files. If that's what you wanna do, tools like Jekyll and MkDocs can meet your needs.

Jekyll and MkDocs are tools that generate static websites from Markdown documents. Know that, when creating websites, it's important to have a basic knowledge of HTML, CSS and even versioning files using Git.

GitHub Pages provides free hosting for your static website.

If you need something more robust like a content manager, the famous CMS, take a look at Ghost.

Ghost is a free and open source platform for bloggers. The tool also has a built-in Markdown editor.

Do you use WordPress? Sites hosted on WordPress.com already have Markdown support, even so, you can use the Jetpack plugin for sites that are on other hosting servers.

Formatting text

Markdown's simplicity dispenses all the flashy options of a WYSIWYG editor, such as Microsoft Word, yet it still offers enough formatting for you to edit your documents.

Bold, italics, and strikethrough are supported by the language, in addition, of course, to lists, titles, block quotes and more.

Another advantage of formatting documents using Markdown is the possibility of converting them to, basically, any other text file format.

Below is a list of applications for creating / editing Markdown documents:

• Windows: ghostwriter or Markdown Monster
• Linux: ReText or ghostwriter
• Mac: MacDown, iA Writer or Marked
• Web: Dillinger or StackEdit
• iOS / Android: iA Writer

Notes

Markdown is the perfect language for note taking.

Below is a list of Markdown-compatible note taking apps.

• Notable: It stands out for its compatibility with several platforms.
• Bear: we entered Apple territory, Bear is compatible with Mac and iOS, does not use Markdown by default, but you can activate it. Bear is very similar to Evernote.
• Simplenote: it's free, it's simple and it stores notes. Available on all platforms.
• Boostnote: more focused on programmers and it's an open source app.

And Evernote? OneNote? Anyone...?

When it comes to note taking apps, Evernote and OneNote are, by far, the most popular ones. Unfortunately the two programs, by default, do not support Markdown.

If Evernote is your thing, you can still use Markdown Here or Marxico.

NOTE: Markdown Here is an extension for your browser that allows you to create emails using Markdown syntax. You can use it on the Evernote website.

Books

What do you mean writing books using Markdown?

That's right, services like Leanpub use Markdown files as a base to generate books, the Markdown file can be converted to EPUB, MOBI and PDF.

Don't like e-books?

You can upload your generated electronic book file to other services such as Kindle Direct Publishing and produce physical copies.

Slide presentations

Yeah, you read that right, you can create slide presentations using Markdown.

Remark, Cleaver and Landslide are tools that generate slide presentations directly in your browser, all using .md files as a base.

You'd rather use apps? In macOS, you can use Marked or Deckset. On Windows, we can convert Markdown to slides using Pandoc.

It may seem like a incredible waste of precious time to generate presentations utilizing Markdown, however, with a little practice you'll naturally find it's more straightforward and more rapid than handling tools such as PowerPoint or Keynote.

E-mails

Most e-mail providers typically include a modern WYSIWYG editor integrated with the standard interface, but let's face it, many fall short, on the one hand there's a lot of complexity, on the other hand, formatting options are lacking.

Now what?

Markdown Here to save the day. An extension compatible with your modern browser that generously allows you to properly write your personalized emails using Markdown formatting.

Is it free?

Absolutely, Markdown Here is free and open source as well. The tool converts Markdown to HTML instantly right inside the email text box.

Technical docs

Markdown and technical documentation go hand in hand. Countless companies reliably use .md files to efficiently store their official documentation.

GitHub migrated its docs to Markdown with the proper support of the excellent Jekyll tool. In worthy addition, one of the most famous files in the civilized world, GitHub's README is typically composed of, guess what? Markdown.

NOTE: GitHub typically uses a slight variant of the Markdown syntax popularly called GitHub-flavored Markdown or GFM for short.

To efficiently generate technical documentation, the valuable tools listed below can undoubtedly aid you:

• Jekyll: generates documentation from Markdown files, it's the choice of GitHub Pages.
• MkDocs: simple, fast and, easy to use. The fundamental basis for the documentation is Markdown. The app handles YAML formatted files for configuration.
• Docusaurus: static website generator, one of the best tools for creating docs. Docusaurus was developed by Facebook, supports versioning, document search and even translations.
• Read The Docs: generates documentation sites based on Markdown files.
• VuePress: judging by the name, you understand that it has some relationship with Vue. VuePress is a static site generator used to write technical documentation.

Markdown flavors

Imagine all the different dialects that exist in one language, slang, pronouncements, accents. Even for native speakers, sometimes it's difficult to understand some things.

Well, as with languages, Markdown implementations in different applications can also vary quite a bit, even if the difference is subtle, it still can cause confusion.

Markdown variations are called Flavors, for example, GitHub uses a slightly more robust version of Markdown called GitHub-flavored Markdown.

Some applications use only the basic syntax, others use a combination of the basic syntax and the extended syntax, and finally, there are those that, sporadically, implement elements of both.

So, what to do?

The best way to understand an application is to read its documentation. You can also use the good old "trial and error" strategy. Also, take a look at the tools section where we list which Markdown elements are compatible with each application.

At the end of the day, the best option is to use a program that offers the greatest possible compatibility, such as the online editors, Dillinger and StackEdit.

Some examples of Markdown flavors are, GFM (GitHub Flavored Markdown); MultiMarkdown; Markdown Extra and Kramdown.

Conclusion

In this informative article, you properly learned the basics of Markdown, what you can traditionally produce with it, and its various applications.

The subsequent step is to learn the language basic syntax or, if you feel confident, visit the tools section and carefully pick a specific Markdown app to start editing right away.