Markdown is the technology behind the README files seen on Github and elsewhere. The file extension is .md, and the output when rendered in a browser follows a consistent syntax. The goal of Markdown is foremost readability.[1] Even in a non-HTML rendered state, it can be read and understood. This is achieved by using punctuation characters as markers for what a text represents.
Markdown was developed by John Gruber, who has a pretty awesome blog on Daring Fireball.[2]
Syntax
Headers
There are two types of headers in Markdown. The first, which only allows for two levels of headers, uses bars of ‘=’ and ‘-‘ of any length (minimum 1):
This is a top header ======== This is a lower header ----------
The second provides many levels by the use of the ‘#’, with the more of them lowering the level (maximum 6):
# This is a top header ## This is a lower header ### Even lower header
Emphasis
To provide emphasis on words via <em> or <strong> tags, you can surround the text with asterisks or underscores.
*emphasize me* _emphasize me_ **really emphasize me** __really emphasize me__
Lists
Markdown supports ordered (numbered) and unordered (bulleted) lists. Each use a different syntax — unordered lists (<ul>) use *, +, or -, and ordered lists use numbers (any, not necessarily in order) followed by periods.
## Unordered list * Cheese * Pepperoni - Black olives ## Ordered list 1. Washington 1. Adams 2. Jefferson 5. Madison
As noted from elsewhere, you may encounter inadvertently creating a list by ending a sentence with a number and a period (13.). Do avoid, escape the period with a backslash (13.).
Code Blocks
Code blocks are essential to Markdown, since so many uses of it are for documenting code! To employ it, simply indent the code by 4 or more spaces, and Markdown will render it inside <pre> and <code> tags, which are prevalent in other systems. Alternatively, you can use three ticks (`) with an optional language identifier.
Here is some gibberish describing some code:
Here is code.
Here is a loop
With internal operations
End loop
```
console.log('Another example!')
```
```js
console.log('Code block with language marker')
```
Blockquotes
Blockquotes are used to group text into an indented block to make them stand out. Typically css will adjust the display to show importance. The format is similar to other systems, using the ‘>’ character before the text. The unique thing about Markdown is that you can blockquote on different lines with preceding >, or just at the front of the first line in a paragraph:
> This blockquote > is manually line broken > but will appear as a single blockquote > This blockquote is on the same line without any line breaks. It could be really long, and extend beyond an editor's screen width, but will wrap when rendered. > This last blockquote is manually line broken but does not have preceding the &lt;, but still makes a single blockquote.
Other Markdown elements can be included in a blockquote as well, such as another header, just by preceding with a >.
Bars
You can create bars (<hr/>) by writing 3 or more hyphens, asterisks, or underscores on a line by themselves.
One with spaces, three without, GO! - - - ---- ***** ______
Escape Characters
Because Markdown uses special characters to denote formatting, you may find yourself needing to use one of these characters and not executing the formatting. To do so, include a backslash () before the character. Here are the escape characters for Markdown:
- backslash
- ` backtick
- * asterisk
- _ underscore
- {} curly braces
- [] square brackets
- () parentheses
- # hash mark
- + plus sign
- – minus sign (hyphen)
- . dot
- ! exclamation mark
Links
When a link is necessary, the syntax is pretty easy. Surround the text to display with single square brackets, then follow it with the url in parenthesis.
Feel free to visit [my website](http://www.clearthehaze.com).