Ultimate Markdown guide: 5 rules to know

What is Markdown?

Markdown is a lightweight markup language created in 2004. It is an easy-to-read and easy-to-write way to format text using a plaintext editor when the features of a full word processor are not available or appropriate. While word processors, like Microsoft Word or LibreOffice Writer, offer formatting buttons to define bold, italics or other features, text editors do not provide these options. Instead, text-formatting instructions must be embedded in the content itself.

You may already be familiar with some famous plain text editors, such as Vim or Nano. Writers, developers and administrators use these tools when graphical environments are unavailable, the power of a word processor isn't needed or the hidden formatting instructions in word processor-based documents interfere with file parsing. Markdown offers a similar benefit. Many Markdown editors exist. Some are standalone products, while others are integrated with broader tools. There are even browser-based editors, such as StackEdit.

Additionally, some scenarios require quick and nimble typing to generate documentation. Using a mouse to navigate toolbars and menus to create bullet points, generate ordered lists and emphasize text can be cumbersome. The most efficient documentation authors keep their hands on the keyboard and avoid the mouse. Markdown uses specific symbols to represent formatting instructions. In the following example, two asterisk symbols on either side of a word indicate the word should be bolded.

Markdown is helpful in scenarios where you must rely on text editors, avoid complex formatting tools and convert the content to other formats.

Markdown's importance is related to its simplicity, readability and flexibility. Authors can format text without removing their hands from the keyboard. It's also easy to read when editing. Finally, Markdown can be converted to HTML efficiently, making it more practical to learn and use than HTML.

Common use cases for Markdown

Markdown is helpful in scenarios where you must rely on text editors, avoid complex formatting tools and convert the content to other formats. It avoids the complex formatting that apps such as Microsoft Word might embed in the text, which can interfere with compiling code or formatting for different languages, such as HTML.

Consider the following Markdown use cases:

• Technical writing and documentation. Markdown is easy to work with and can be converted into many other formats depending on the requirement.
• Web content. Blogs, webpages, online instructions and other sites rely on Markdown to enable authors to manage and format content easily.
• Writing and note-taking. Authors who need a simple way of formatting notes, presentations, lecture materials and similar documents rely on Markdown for its efficiency.
• Email and IM. Mobile device users can quickly format messages without working with complex formatting tools that may be tedious on small screens.

Markdown isn't appropriate for all authoring or editing tasks, but it certainly helps in specific situations.

What are the different Markdown flavors?

One of the most challenging aspects of Markdown is variations among vendors -- known as flavors. All Markdown types follow the same general rules. Some vendors customize their Markdown specifications with unique features that fit a specific use case.

For example, GitHub Flavored Markdown (GFM) adds the text strikethrough -- example -- capability to the standard Markdown specification.

Here are several extended Markdown specifications:

• CommonMark. CommonMark provides standardization and compatibility for consistency across platforms, applications and vendors.
• GFM. GFM provides formatting for README files and other software documentation. Specific features include task lists, syntax highlighting, tables and text strikethrough.
• Markdown Extra. Markdown Extra provides updated features, including fenced code blocks, abbreviations, footnotes and tables. It is implemented in several programming languages, including PHP and Python.
• MultiMarkdown. MultiMarkdown provides valuable features for more extensive documentation with support for math formulas and bibliographic references.

Because these flavors enhance the original Markdown specification, they are often called supersets. Select your preferred Markdown flavor based on available features, project requirements and product support. Remember that most of what you know about one flavor applies to any other.

5 essential Markdown rules to learn

Begin learning Markdown by selecting a few specific formatting instructions to integrate into your documentation project or note-taking sessions. Here are five syntax examples to get you started with structuring documents and emphasizing text.

1. Create headers

One of the most essential document structure definitions is headers. Markdown relies on familiar H1, H2, H3, etc. header definitions. It sets these structures using the hash character #, with a single hash representing H1, two hashes indicating H2 and so forth.

2. Create lines

Horizontal rules or lines help define sections of text. Markdown uses three dashes --- to depict a horizontal line across the text.

Perhaps you want to separate the notes you took yesterday from those you're taking today, or maybe you need to break software documentation into more digestible or specific chunks. Line breaks are useful in these cases.

3. Generate unordered and ordered lists

Listing tasks or steps helps readers understand what needs to be accomplished and whether there is a specific order to complete steps. Markdown provides an easy way to structure both lists.

Unordered lists are a series of bullet points defined using a single dash -, as seen here.

Ordered lists specify steps to be accomplished sequentially and are defined using the digit one followed by a dot 1., as seen in this example.

Listing items is common when creating documentation, taking notes or communicating with others.

4. Emphasize text

Some text needs a little extra attention. Markdown lets you emphasize these strings by italicizing or bolding them:

• Italicized text. Represented by a single asterisk * or a single underscore _ character.
• Bolded text. Represented by two asterisks ** or two underscore _ _ characters.
• Italicized and bolded text. Represented by three asterisks *** or three underscore _ _ _ characters.

5. Link additional resources

Another useful method of text manipulation is linking to websites. Markdown's link definition uses three elements: the text to link, the URL and a title.

Inline links define the basic text in square brackets followed by the URL in parentheses. For example, to embed a link to the TechTarget website in text, use the following instructions: This text links to [TechTarget](https://www.techtarget.com/ "TechTarget homepage"). The title is displayed when a reader hovers over the link.

To create an automatic link, enclose the URL in < > brackets.

Example of a Markdown document

Consider the following sample document, created with Markdown. As you analyze the content and code, consider how handy it is not to remove your hands from the keyboard when generating this simple but well-formatted information.

Damon Garn owns Cogspinner Coaction and provides freelance IT writing and editing services. He has written multiple CompTIA study guides, including the Linux+, Cloud Essentials+ and Server+ guides, and contributes extensively to TechTarget Editorial, The New Stack and CompTIA Blogs.