Syntax Guide for Markdown

Overview

Markdown is a plain text and lightweight markup programming language meant for formatting for the web and following source code form. It is designed to use a plain-text editor, however, specialist editors now exist that have been adapted for its use, such as CKEditor 5. The language was originally created in 2004 and continues to be used in web writing as an alternative to WYSIWYG editors and HTML formatting (although some overlap exists).

Markdown aims to make text documents more readable without relying on various tags to abstruse the document or confuse the reader. It was also to add text formatting options like italics or bold.

Reasons to use Markdown

Markdown is an unobtrusive language that can be used for a variety of purposes. This includes writing notes, composing email messages, creating web pages and technical documents in addition to standard web writing as it converts to HTML easily. It is also relatively painless or quick to learn for non-programmers.

Basic syntax

Keep in mind that there are minor discrepancies between Markdown processors. However, nearly all Markdown applications support the basic syntax outlined in the original Markdown design document.

Headings

Headings are used to separate sections of a document and change the font size depending on the heading being used; they range from level 1-6. In order to create headings, simply add a number sign (#) in front of the first word of the heading sentence you will be using.

The lower the number, starting with <h1> , the more important the level is of the heading. For example the heading below uses <h2> or the second level beyond the most important headings and thus it can be considered a subheading of the main heading of the page or <h1>:

Also keep in mind that for best compatibility across Markdown applications, always put a space between the first letter of a heading and the number sign as shown above with the T and the second #. Putting a blank line between headings or other sections of the document above or below a heading is also a good idea.

Line breaks

The best way to ensure a line break and split up sentences or forms of writing within a document is to add two or more (we recommend three to be sure) spaces at the end of the line before clicking enter. That way the second line or sentence does not join with the first in one continuous line or paragraph.

Another option is to use the HTML <br> tag if your markdown application supports HTML.

Paragraphs

Paragraphs are created like in standard word processors, except in Markdown the best practice is not to indent it in any way. This means a blank line should be used to separate paragraphs and the first letter should be on the leftmost side of the page. Here is an example:

Bold

In order to create bold syntax within a word, phrase, or line of text, using Markdown, simply put two asterisks, or underscores, before and after the text you want bolded.

Using the asterisks method is a better practice to keep in mind as you may want to bold just certain letters within a larger word or phrase and for compatibility having asterisks before and after this word will work better than underscoring the letters.

Just **Like** This

Italics

Italics works in a similar way to bold except having two asterisks or underscores, it is one in this case. Like bold, it is recommended to use asterisks as it is possible to italicise just a word within a phrase or even a letter within a word.

Using both italics and bold simultaneously

In order to put a strong emphasis on a word, phrase or text using Markdown and using both italics and bold at the same time, simply add three asterisks to the section you want emphasized this way.

Blockquotes

If you want to create a paragraph as a block quote, insert the greater-than sign in front of it. Just like the example below shows:

It is a good practice to put a blank line before and after a blockquote within a Markup document.

Blockquotes with more than one paragraph

If you want a single blockquote to cover multiple paragraphs being part of the blockquote you have to add the greater-than sign between the paragraphs you are including.

Nested blockquotes

To create nested blockquote, or a blockqote as part of a larger blockquote, add to greater-than signs in front of the specific paragraph you want nested in the main paragraph. Keep one greater-than sign between them as well.

Keep in mind that you can insert other Markdown elements within the blockquotes as well, such as bold or italics.

Lists

Lists separate items, such as to-do tasks, in a top-down order. However, the order does not have to be chronological or ordered a certain way, but it can be, within Markdown syntax.

Ordered lists

Creating ordered or numbered lists is as easy as it is in a standard word document. Simply add a number and a period following it, then write your item or content on that same line.

Unordered lists

In order to create a list of items without a specific order or numbering system, add asterisk (*), dashes (-), or plus signs (+) in front of the items in the list. Keep the marks consistent for the list you are creating. You can also indent one or more of the items to nest them within the overall list.

elements within a list Other elements within a list

You can add other elements to a list without starting to write a new list and having it continue by indenting the line with the element by four spaces or a tab.

Blockquotes within a list

To add a blockquote that is within a list, but not a list item, use the greater-than sign.

Nesting ordered and unordered lists together

You can nest ordered and unordered lists within one another. Here is an example:

The indented item will be nested in the overall list.

Code blocks

To create a code block, indent one tab or four spaces from the left-most side of the document. Then start writing your code or tags if it is HTML code, for example. If it is in a list, indent by eight spaces or to tabs.

<html>
   <head>
     <title>code block example</title>
   </head>
</html>

Denoting code

To denote a section of code or even one line of code as an example within a larger set of text simply add backtick marks (`) to it.

Keep in mind that if a word already has a backlink in it, but you still want to denote code around it somehow, you can do so by using two backtick marks (``) where the beginning of the code block starts and end with two where it ends while the single backtick words can still be present inside.

Images

Markdown also supports adding images using a specific Markdown syntax, which you can see below:

Here is a more specific example of an image with the name “NewLogo.jpg”:

Linked images

You may want to have a link present within an image someone can refer to when clicking on it. In order to do this, add the link in parenthesis before enclosing the Markdown code for images in brackets.

Escaping formatting syntax

Sometimes, you may want to use particular syntax or character within the document as text that is usually reserved for formatting tasks. In order to escape the formatting Markdown does using these characters or particular syntax, use a backlash (\) in front of it.

\* this avoids a bullet list

An asterik remains instead of being turned into a bullet with the example above. There are various characters or syntax you can escape being auto formatted this way, ranging from underscores to brackets, so play around with it and experiment.

Horizontal rules

In order to create a horizontal rule, you have to use three or more asterisk (***), dashes (---), or underscores (___) on a line with no other text present. The rendered output will then be the same or a horizontal rule.

Having a blank line before and after the rule is a good idea for compatibility.

Creating links

In order to create a link, you have to use brackets to enclose the text of the link, then follow it with the url within parenthesis.

Adding a title to a link

You can add a title to a link that will appear as a tooltip when someone hovers over the link (for a second keeping it still) with a mouse. In order to do this, enclose the title text in quotation marks and within the parenthesis following the url.

Turning an URL or email address into a link

In order to turn an URL email address into a link, simply enclose it in angle brackets.

Formatting links

Add asterisks (*) before and after brackets and parenthesis to emphasize a link. You can also denote links as code by adding backticks inside the brackets.

Basically, the emphasized link will appear bolder and the code more as italicized in a way.

Also, a thing to note is that Markdown applications handle spaces in an irregular manner within links so do not add spaces within an URL. To counter this if you need to have spaces present use the symbols %20 instead of spaces.

These are sometimes referred to as inline links. There is also something called reference style links, which is a bit more complicated and probably reserved for those already familiar with Markdown and in specific cases.

They are formatted like this and they can link multiple parts to the same ID, instead of having to paste a link multiple ties throughout the text.

Then, you can create the reference ID and the above link references to it every time you feel like adding it within your document (using a number is a good idea but it can be anything you want):

The second part for reference ID above can be anywhere within the document like after the paragraph it is mentioned or at the end of the document. There are more complex ways to add such links like including core attributes, like title text, but this is the basic method.

Adding HTML code into Markdown

You can use HTML tags in Markdown-formatted text in many applications as they will convert or accept it (but be careful as not all may do this). It can be helpful if you are familiar with HTML code and maybe not Markdown syntax. It also may give more options for doing certain things like changing attributes of an element including specifying the color of text within the document.

It is also worth noting that some applications only support a subset of HTML tags within Markdown documents. Also of note is that you cannot add a block-level HTML tag with Markdown syntax inside it and expect good results.

Tables

Although this is more complicated and a part of Markdown extended syntax, it is worth noting that you can create tables in Markdown as well. Use hyphens for this purpose (-).

The widths can vary in the example above but the output should look similar. This is just a basic table however, and there are more options like adding links or code within the tables as well.

To sum it up

There you have it. We hope this Markdown guide will be a good starting point for your journey in the world of Markdown and give you a scope what is possible using this language.