Revamp GFM user docs.

app/views/help/markdown.html.haml

-- bash_lexer = Pygments::Lexer[:bash]
-%h3.page_title Gitlab Markdown
+%h3.page_title Gitlab Flavored Markdown
 .back_link
   = link_to help_path do 
     ← to index
 %hr
-%p.slead We extend Markdown with some GITLAB specific syntax. It allows you to link to:
-%ul
-  %li issues (#123)
-  %li merge request (!123)
-  %li commits (1234567)
-  %li team members (@foo)
-  %li snippets ($123)
-%p.slead in
-%ul
-  %li commit messages
-  %li notes/comments/wall posts
-  %li issues
-  %li merge requests
-  %li milestones
-  %li wiki pages
+.row
+  .span8
+    %p
+      For Gitlab we developed something we call "Gitlab Flavored Markdown" (GFM).
+      It extends the standard Markdown in a few significant ways adds some useful functionality.
+    %p You can use GFM in:
+    %ul
+      %li commit messages
+      %li comments
+      %li wall posts
+      %li issues
+      %li merge requests
+      %li milestones
+      %li wiki pages
+    %h3 Differences from traditional Markdown
+    %h4 Newlines
+
+    %p
+      The biggest difference that GFM introduces is in the handling of linebreaks.
+      With traditional Markdown you can hard wrap paragraphs of text and they will be combined into a single paragraph. We find this to be the cause of a huge number of unintentional formatting errors.
+      GFM treats newlines in paragraph-like content as real line breaks, which is probably what you intended.
+
+
+    %p The next paragraph contains two phrases separated by a single newline character:
+    %pre= "Roses are red\nViolets are blue"
+    %p becomes
+    = markdown "Roses are red\nViolets are blue"
+
+    %h4 Multiple underscores in words
+
+    %p
+      It is not reasonable to italicize just <em>part</em> of a word, especially when you're dealing with code and names often appear with multiple underscores.
+      Therefore, GFM ignores multiple underscores in words.
+
+    %pre= "perform_complicated_task\ndo_this_and_do_that_and_another_thing"
+    %p becomes
+    = markdown "perform_complicated_task\ndo_this_and_do_that_and_another_thing"
+
+    %h4 URL autolinking
+
+    %p
+      GFM will autolink standard URLs you copy and paste into your text.
+      So if you want to link to a URL (instead of a textual link), you can simply put the URL in verbatim and it will be turned into a link to that URL.
+
+    %h4 Fenced code blocks
+
+    %p
+      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 <code>```</code> and you won't need to indent manually to trigger a code block.
+
+    %pre= %Q{```ruby\nrequire 'redcarpet'\nmarkdown = Redcarpet.new("Hello World!")\nputs markdown.to_html\n```}
+    %p becomes
+    = markdown %Q{```ruby\nrequire 'redcarpet'\nmarkdown = Redcarpet.new("Hello World!")\nputs markdown.to_html\n```}
+
+    %h4 Special Gitlab references
+
+    %p
+      GFM recognizes special references.
+      You can easily reference e.g. a team member, an issue or a commit within a project.
+      GFM will turn that reference into a link so you can navigate between them easily.
+
+    %p GFM will recognize the following references:
+    %ul
+      %li
+        %code @foo
+        for team members
+      %li
+        %code #123
+        for issues
+      %li
+        %code !123
+        for merge request
+      %li
+        %code $123
+        for snippets
+      %li
+        %code 1234567
+        for commits
+
+    -# this example will only be shown if the user has a project with at least one issue
+    - if @project = current_user.projects.first
+      - if issue = @project.issues.first
+        %p For example in your #{link_to @project.name, project_path(@project)} project something like
+        %pre= "This is related to ##{issue.id}. @#{current_user.name} is working on solving it."
+        %p becomes
+        = markdown "This is related to ##{issue.id}. @#{current_user.name} is working on solving it."
+
+
+
+  .span4.right
+    .alert.alert-info
+      %p
+        If you're not already familiar with Markdown, you should spend 15 minutes and go over the excellent
+        %strong= link_to "Markdown Syntax Guide", "http://daringfireball.net/projects/markdown/syntax"
+        at Daring Fireball.