` tags in the HTML output. For example, this input:
* Bird
* Magic
will turn into:
It's worth noting that it's possible to trigger an ordered list by accident, by writing something like this:
1986. What a great season.
In other words, a *number-period-space* sequence at the beginning of a line. To avoid this, you can backslash-escape the period:
1986\. What a great season.
Code Blocks
Pre-formatted code blocks are used for writing about programming or markup source code. Rather than forming normal paragraphs, the lines of a code block are interpreted literally. Markdown wraps a code block in both `` and `` tags.
To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab. For example, given this input:
This is a normal paragraph:
This is a code block.
Markdown will generate:
This is a normal paragraph:
This is a code block.
One level of indentation -- 4 spaces or 1 tab -- is removed from each line of the code block. For example, this:
Here is an example of AppleScript:
tell application "Foo"
beep
end tell
will turn into:
Here is an example of AppleScript:
tell application "Foo"
beep
end tell
A code block continues until it reaches a line that is not indented (or the end of the article).
Within a code block, ampersands (`&`) and angle brackets (`<` and `>`) are automatically converted into HTML entities. This makes it very easy to include example HTML source code using Markdown -- just paste it and indent it, and Markdown will handle the hassle of encoding the ampersands and angle brackets. For example, this:
will turn into:
<div class="footer">
© 2004 Foo Corporation
</div>
Regular Markdown syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block. This means it's also easy to use Markdown to write about Markdown's own syntax.
New with Github-Flavored-Markdown
Fenced Code Blocks
Markdown converts text with four spaces at the front of each line to code blocks. GFM supports that, but we also support fenced blocks. Just wrap your code blocks in ``` and you won't need to indent manually to trigger a code block.
New with Garrett-Flavored-Markdown
Syntax highlighting
We take code blocks a step further and add syntax highlighting if you request it. In your fenced block, add an optional language identifier and we'll run it through syntax highlighting. For example, to syntax highlight Ruby code:
``` ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```
will use an online [pygments-powered](http://pygments.appspot.com) syntax-highlighter to generate pretty-formatted html for your sourcecode:
``` ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```
#### Syntax-highlighter Languages
The following is a list of the more common languages that are supported.
Toggle full language list
Language | highlight code | Language | highlight code |
Bash | bash | Batchfile | bat |
C | c | C# | csharp |
C++ | cpp | CMake | cmake |
CoffeeScript | coffee-script | CSS | css |
Delphi | delphi | Diff | diff |
HTML | html | INI | ini |
IRC logs | irc | Java | java |
JavaScript | js | Lua | lua |
Makefile | make | Makefile (basemake) | basemake |
MySQL | mysql | NASM | nasm |
Perl | perl | PHP | php |
Python | python | Python 3 | python3 |
Python 3.0 Traceback | py3tb | Python console session | pycon |
Python Traceback | pytb | Raw token data | raw |
Ruby | rb | Ruby irb session | rbcon |
SQL | sql | Text only | text |
VB.net | vb.net | XML | xml |
XSLT | xslt | YAML | yaml |
Language | highlight code | Language | highlight code |
ABAP | abap | ActionScript | as |
ActionScript 3 | as3 | Ada | ada |
ANTLR | antlr | ANTLR With ActionScript Target | antlr-as |
ANTLR With C# Target | antlr-csharp | ANTLR With CPP Target | antlr-cpp |
ANTLR With Java Target | antlr-java | ANTLR With ObjectiveC Target | antlr-objc |
ANTLR With Perl Target | antlr-perl | ANTLR With Python Target | antlr-python |
ANTLR With Ruby Target | antlr-ruby | ApacheConf | apacheconf |
AppleScript | applescript | aspx-cs | aspx-cs |
aspx-vb | aspx-vb | Asymptote | asy |
Bash | bash | Bash Session | console |
Batchfile | bat | BBCode | bbcode |
Befunge | befunge | Boo | boo |
Brainfuck | brainfuck | C | c |
C# | csharp | C++ | cpp |
c-objdump | c-objdump | cfstatement | cfs |
Cheetah | cheetah | Clojure | clojure |
CMake | cmake | CoffeeScript | coffee-script |
Coldufsion HTML | cfm | Common Lisp | common-lisp |
cpp-objdump | cpp-objdump | CSS | css |
CSS+Django/Jinja | css+django | CSS+Genshi Text | css+genshitext |
CSS+Mako | css+mako | CSS+Myghty | css+myghty |
CSS+PHP | css+php | CSS+Ruby | css+erb |
CSS+Smarty | css+smarty | Cython | cython |
D | d | d-objdump | d-objdump |
Darcs Patch | dpatch | Debian Control file | control |
Debian Sourcelist | sourceslist | Delphi | delphi |
Diff | diff | Django/Jinja | django |
Dylan | dylan | Embedded Ragel | ragel-em |
ERB | erb | Erlang | erlang |
Erlang erl session | erl | Evoque | evoque |
Felix | felix | Fortran | fortran |
GAS | gas | Genshi | genshi |
Genshi Text | genshitext | Gettext Catalog | pot |
Gherkin | Cucumber | GLSL | glsl |
Gnuplot | gnuplot | Go | go |
Groff | groff | Haml | haml |
Haskell | haskell | haXe | hx |
HTML | html | HTML+Cheetah | html+cheetah |
HTML+Django/Jinja | html+django | HTML+Evoque | html+evoque |
HTML+Genshi | html+genshi | HTML+Mako | html+mako |
HTML+Myghty | html+myghty | HTML+PHP | html+php |
HTML+Smarty | html+smarty | INI | ini |
Io | io | IRC logs | irc |
Java | java | Java Server Page | jsp |
JavaScript | js | JavaScript+Cheetah | js+cheetah |
JavaScript+Django/Jinja | js+django | JavaScript+Genshi Text | js+genshitext |
JavaScript+Mako | js+mako | JavaScript+Myghty | js+myghty |
JavaScript+PHP | js+php | JavaScript+Ruby | js+erb |
JavaScript+Smarty | js+smarty | Lighttpd configuration file | lighty |
Literate Haskell | lhs | LLVM | llvm |
Logtalk | logtalk | Lua | lua |
Makefile | make | Makefile (basemake) | basemake |
Mako | mako | Matlab | matlab |
MiniD | minid | Modelica | modelica |
Modula-2 | modula2 | MoinMoin/Trac Wiki markup | trac-wiki |
MOOCode | moocode | MuPAD | mupad |
MXML | mxml | Myghty | myghty |
MySQL | mysql | NASM | nasm |
Newspeak | newspeak | Nginx configuration file | nginx |
NumPy | numpy | objdump | objdump |
Objective-C | objective-c | Objective-J | objective-j |
OCaml | ocaml | Ooc | ooc |
Perl | perl | PHP | php |
POVRay | pov | Prolog | prolog |
Python | python | Python 3 | python3 |
Python 3.0 Traceback | py3tb | Python console session | pycon |
Python Traceback | pytb | Raw token data | raw |
RConsole | rconsole | REBOL | rebol |
Redcode | redcode | reStructuredText | rst |
RHTML | rhtml | Ruby | rb |
Ruby irb session | rbcon | S | splus |
Sass | sass | Scala | scala |
Scheme | scheme | Smalltalk | smalltalk |
Smarty | smarty | SQL | sql |
sqlite3con | sqlite3 | SquidConf | squidconf |
Tcl | tcl | Tcsh | tcsh |
TeX | tex | Text only | text |
Vala | vala | VB.net | vb.net |
VimL | vim | XML | xml |
XML+Cheetah | xml+cheetah | XML+Django/Jinja | xml+django |
XML+Evoque | xml+evoque | XML+Mako | xml+mako |
XML+Myghty | xml+myghty | XML+PHP | xml+php |
XML+Ruby | xml+erb | XML+Smarty | xml+smarty |
XSLT | xslt | YAML | yaml |
New with Garrett-Flavored-Markdown
Smuggling links into syntax-highlighted regions
It's possible to do some meta-formatting with the content in the syntax-highlighted blocks if you want to put a link around a peice of text.
Note: This is a big-hack, and it's pretty certain there are conditions where this won't work and will spew hashes around your code.
Reformat the code you want to have a link in with the following:
«ORIGINAL-BIT-OF-CODE«LINK»
The `«` character can be typed using ALT-174 on the numpad.
The `»` character can be typed using ALT-175 on the numpad.
Replace the `ORIGINAL-BIT-OF_CODE` with the code in the block.
Replace the `LINK` with the link target.
For an example, see [ptk page source](https://raw.github.com/coapp/coapp.org/master/src/dynamic/reference/ptk.html.md)
New with Github-Flavored-Markdown
A bit of the GitHub spice
In addition to the changes in the previous section, certain references are auto-linked :
note: these work when there is a project context. Probably broken right now.
* SHA: be6a8cc1c1ecfe9489fb51e4869af15a13fc2cd2
* User@SHA ref: mojombo@be6a8cc1c1ecfe9489fb51e4869af15a13fc2cd2
* User/Project@SHA: mojombo/god@be6a8cc1c1ecfe9489fb51e4869af15a13fc2cd2
* \#Num: #1
* User/#Num: mojombo#1
* User/Project#Num: mojombo/god#1
becomes
* SHA: be6a8cc1c1ecfe9489fb51e4869af15a13fc2cd2
* User@SHA ref: mojombo@be6a8cc1c1ecfe9489fb51e4869af15a13fc2cd2
* User/Project@SHA: mojombo/god@be6a8cc1c1ecfe9489fb51e4869af15a13fc2cd2
* \#Num: #1
* User/#Num: mojombo#1
* User/Project#Num: mojombo/god#1
Horizontal Rules
You can produce a horizontal rule tag (`
`) by placing three or more hyphens, asterisks, or underscores on a line by themselves. If you wish, you may use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule:
* * *
***
*****
- - -
---------------------------------------
* * *
Span Elements
### [Links](!link)
Markdown supports two style of links: *inline* and *reference*.
In both styles, the link text is delimited by [square brackets].
To create an inline link, use a set of regular parentheses immediately after the link text's closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an *optional* title for the link, surrounded in quotes. For example:
This is [an example](http://example.com/ "Title") inline link.
[This link](http://example.net/) has no title attribute.
Will produce:
This is
an example inline link.
This link has no
title attribute.
If you're referring to a local resource on the same server, you can use relative paths:
See my [About](/about/) page for details.
Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link:
This is [an example][id] reference-style link.
You can optionally use a space to separate the sets of brackets:
This is [an example] [id] reference-style link.
Then, anywhere in the document, you define your link label like this,
on a line by itself:
[id]: http://example.com/ "Optional Title Here"
That is:
* Square brackets containing the link identifier (optionally
indented from the left margin using up to three spaces);
* followed by a colon;
* followed by one or more spaces (or tabs);
* followed by the URL for the link;
* optionally followed by a title attribute for the link, enclosed
in double or single quotes, or enclosed in parentheses.
The following three link definitions are equivalent:
[foo]: http://example.com/ "Optional Title Here"
[foo]: http://example.com/ 'Optional Title Here'
[foo]: http://example.com/ (Optional Title Here)
**Note:** There is a known bug in Markdown.pl 1.0.1 which prevents single quotes from being used to delimit link titles.
The link URL may, optionally, be surrounded by angle brackets:
[id]: "Optional Title Here"
You can put the title attribute on the next line and use extra spaces or tabs for padding, which tends to look better with longer URLs:
[id]: http://example.com/longish/path/to/resource/here
"Optional Title Here"
Link definitions are only used for creating links during Markdown processing, and are stripped from your document in the HTML output.
Link definition names may consist of letters, numbers, spaces, and punctuation -- but they are *not* case sensitive. E.g. these two links:
[link text][a]
[link text][A]
are equivalent.
The *implicit link name* shortcut allows you to omit the name of the link, in which case the link text itself is used as the name. Just use an empty set of square brackets -- e.g., to link the word "Google" to the google.com web site, you could simply write:
[Google][]
And then define the link:
[Google]: http://google.com/
Because link names may contain spaces, this shortcut even works formultiple words in the link text:
Visit [Daring Fireball][] for more information.
And then define the link:
[Daring Fireball]: http://daringfireball.net/
Link definitions can be placed anywhere in your Markdown document. Itend to put them immediately after each paragraph in which they'reused, but if you want, you can put them all at the end of yourdocument, sort of like footnotes.
Here's an example of reference links in action:
I get 10 times more traffic from [Google] [1] than from
[Yahoo] [2] or [MSN] [3].
[1]: http://google.com/ "Google"
[2]: http://search.yahoo.com/ "Yahoo Search"
[3]: http://search.msn.com/ "MSN Search"
Using the implicit link name shortcut, you could instead write:
I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].
[google]: http://google.com/ "Google"
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
[msn]: http://search.msn.com/ "MSN Search"
Both of the above examples will produce the following HTML output:
I get 10 times more traffic from Google than from
Yahoo
or MSN.
For comparison, here is the same paragraph written usingMarkdown's inline link style:
I get 10 times more traffic from [Google](http://google.com/ "Google")
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
[MSN](http://search.msn.com/ "MSN Search").
The point of reference-style links is not that they're easier towrite. The point is that with reference-style links, your documentsource is vastly more readable. Compare the above examples: usingreference-style links, the paragraph itself is only 81 characterslong; with inline-style links, it's 176 characters; and as raw HTML,it's 234 characters. In the raw HTML, there's more markup than thereis text.
With Markdown's reference-style links, a source document much moreclosely resembles the final output, as rendered in a browser. Byallowing you to move the markup-related metadata out of the paragraph,you can add links without interrupting the narrative flow of yourprose.
New with Garrett-Flavored-Markdown
Inter-document References
Pages in the site can declare a `docid` in their YAML Front Matter. The docid can be used as a reference from any other page in the website, making it less likely that pages will break links if moved around.
For example, this page has the header:
---
layout: 'article'
title: 'Garrett Flavored Markdown Reference Guide'
version: '1.0'
docid: 'gfm'
---
And other documents in this site can reference it by simply:
Check out the [garrett-flavored-markdown][gfm] page.
which renders as:
Check out the [garrett-flavored-markdown][gfm] page.
**Referece Anchors**
If you want to declare an anchor on a page (so that you can have a link jump to it with `#anchorname`) you can create one with the following syntax:
[anchor text] (!anchorname)
which registers an sitewide reference as `docid#anchorname` which means you can even use anchors within the page to jump to a particular location in another document:
Check out this [links section][gfm#link] .
which renders as:
Check out this [links section][gfm#link] .
Emphasis
Markdown treats asterisks (`*`) and underscores (`_`) as indicators ofemphasis. Text wrapped with one `*` or `_` will be wrapped with anHTML `` tag; double `*`'s or `_`'s will be wrapped with an HTML`` tag. E.g., this input:
*single asterisks*
_single underscores_
**double asterisks**
__double underscores__
will produce:
single asterisks
single underscores
double asterisks
double underscores
You can use whichever style you prefer; the lone restriction is that the same character must be used to open and close an emphasis span.
Emphasis can be used in the middle of a word:
un*frigging*believable
But if you surround an `*` or `_` with spaces, it'll be treated as a literal asterisk or underscore.
To produce a literal asterisk or underscore at a position where it would otherwise be used as an emphasis delimiter, you can backslash escape it:
\*this text is surrounded by literal asterisks\*
New with Github-Flavored-Markdown
Multiple underscores in words
It is not reasonable to italicize just part of a word, especially when you're dealing with code and names often appear with multiple underscores. Therefore, GFM ignores multiple underscores in words.
perform_complicated_task
do_this_and_do_that_and_another_thing
becomes
perform_complicated_task
do_this_and_do_that_and_another_thing
Code
To indicate a span of code, wrap it with backtick quotes (`` ` ``).Unlike a pre-formatted code block, a code span indicates code within anormal paragraph. For example:
Use the `printf()` function.
will produce:
Use the printf()
function.
To include a literal backtick character within a code span, you can usemultiple backticks as the opening and closing delimiters:
``There is a literal backtick (`) here.``
which will produce this:
There is a literal backtick (`) here.
The backtick delimiters surrounding a code span may include spaces --one after the opening, one before the closing. This allows you to placeliteral backtick characters at the beginning or end of a code span:
A single backtick in a code span: `` ` ``
A backtick-delimited string in a code span: `` `foo` ``
will produce:
A single backtick in a code span: `
A backtick-delimited string in a code span: `foo`
With a code span, ampersands and angle brackets are encoded as HTMLentities automatically, which makes it easy to include example HTMLtags. Markdown will turn this:
Please don't use any `