gitlabhq/app/views/help/markdown.html.haml

%h3.page_title Gitlab Flavored Markdown
.back_link
  = link_to help_path do 
    ← to index
%hr

.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.