Commit 1f1ce5fbd47a8a9966323caf6b5b59672c74007a
1 parent
806695f4
Exists in
master
and in
4 other branches
Revamp GFM user docs.
Showing
1 changed file
with
97 additions
and
17 deletions
Show diff stats
app/views/help/markdown.html.haml
| 1 | -- bash_lexer = Pygments::Lexer[:bash] | ||
| 2 | -%h3.page_title Gitlab Markdown | 1 | +%h3.page_title Gitlab Flavored Markdown |
| 3 | .back_link | 2 | .back_link |
| 4 | = link_to help_path do | 3 | = link_to help_path do |
| 5 | ← to index | 4 | ← to index |
| 6 | %hr | 5 | %hr |
| 7 | 6 | ||
| 8 | -%p.slead We extend Markdown with some GITLAB specific syntax. It allows you to link to: | 7 | +.row |
| 8 | + .span8 | ||
| 9 | + %p | ||
| 10 | + For Gitlab we developed something we call "Gitlab Flavored Markdown" (GFM). | ||
| 11 | + It extends the standard Markdown in a few significant ways adds some useful functionality. | ||
| 9 | 12 | ||
| 10 | -%ul | ||
| 11 | - %li issues (#123) | ||
| 12 | - %li merge request (!123) | ||
| 13 | - %li commits (1234567) | ||
| 14 | - %li team members (@foo) | ||
| 15 | - %li snippets ($123) | 13 | + %p You can use GFM in: |
| 14 | + %ul | ||
| 15 | + %li commit messages | ||
| 16 | + %li comments | ||
| 17 | + %li wall posts | ||
| 18 | + %li issues | ||
| 19 | + %li merge requests | ||
| 20 | + %li milestones | ||
| 21 | + %li wiki pages | ||
| 16 | 22 | ||
| 17 | -%p.slead in | 23 | + %h3 Differences from traditional Markdown |
| 18 | 24 | ||
| 19 | -%ul | ||
| 20 | - %li commit messages | ||
| 21 | - %li notes/comments/wall posts | ||
| 22 | - %li issues | ||
| 23 | - %li merge requests | ||
| 24 | - %li milestones | ||
| 25 | - %li wiki pages | 25 | + %h4 Newlines |
| 26 | + | ||
| 27 | + %p | ||
| 28 | + The biggest difference that GFM introduces is in the handling of linebreaks. | ||
| 29 | + 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. | ||
| 30 | + GFM treats newlines in paragraph-like content as real line breaks, which is probably what you intended. | ||
| 31 | + | ||
| 32 | + | ||
| 33 | + %p The next paragraph contains two phrases separated by a single newline character: | ||
| 34 | + %pre= "Roses are red\nViolets are blue" | ||
| 35 | + %p becomes | ||
| 36 | + = markdown "Roses are red\nViolets are blue" | ||
| 37 | + | ||
| 38 | + %h4 Multiple underscores in words | ||
| 39 | + | ||
| 40 | + %p | ||
| 41 | + 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. | ||
| 42 | + Therefore, GFM ignores multiple underscores in words. | ||
| 43 | + | ||
| 44 | + %pre= "perform_complicated_task\ndo_this_and_do_that_and_another_thing" | ||
| 45 | + %p becomes | ||
| 46 | + = markdown "perform_complicated_task\ndo_this_and_do_that_and_another_thing" | ||
| 47 | + | ||
| 48 | + %h4 URL autolinking | ||
| 49 | + | ||
| 50 | + %p | ||
| 51 | + GFM will autolink standard URLs you copy and paste into your text. | ||
| 52 | + 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. | ||
| 53 | + | ||
| 54 | + %h4 Fenced code blocks | ||
| 55 | + | ||
| 56 | + %p | ||
| 57 | + Markdown converts text with four spaces at the front of each line to code blocks. | ||
| 58 | + GFM supports that, but we also support fenced blocks. | ||
| 59 | + Just wrap your code blocks in <code>```</code> and you won't need to indent manually to trigger a code block. | ||
| 60 | + | ||
| 61 | + %pre= %Q{```ruby\nrequire 'redcarpet'\nmarkdown = Redcarpet.new("Hello World!")\nputs markdown.to_html\n```} | ||
| 62 | + %p becomes | ||
| 63 | + = markdown %Q{```ruby\nrequire 'redcarpet'\nmarkdown = Redcarpet.new("Hello World!")\nputs markdown.to_html\n```} | ||
| 64 | + | ||
| 65 | + %h4 Special Gitlab references | ||
| 66 | + | ||
| 67 | + %p | ||
| 68 | + GFM recognizes special references. | ||
| 69 | + You can easily reference e.g. a team member, an issue or a commit within a project. | ||
| 70 | + GFM will turn that reference into a link so you can navigate between them easily. | ||
| 71 | + | ||
| 72 | + %p GFM will recognize the following references: | ||
| 73 | + %ul | ||
| 74 | + %li | ||
| 75 | + %code @foo | ||
| 76 | + for team members | ||
| 77 | + %li | ||
| 78 | + %code #123 | ||
| 79 | + for issues | ||
| 80 | + %li | ||
| 81 | + %code !123 | ||
| 82 | + for merge request | ||
| 83 | + %li | ||
| 84 | + %code $123 | ||
| 85 | + for snippets | ||
| 86 | + %li | ||
| 87 | + %code 1234567 | ||
| 88 | + for commits | ||
| 89 | + | ||
| 90 | + -# this example will only be shown if the user has a project with at least one issue | ||
| 91 | + - if @project = current_user.projects.first | ||
| 92 | + - if issue = @project.issues.first | ||
| 93 | + %p For example in your #{link_to @project.name, project_path(@project)} project something like | ||
| 94 | + %pre= "This is related to ##{issue.id}. @#{current_user.name} is working on solving it." | ||
| 95 | + %p becomes | ||
| 96 | + = markdown "This is related to ##{issue.id}. @#{current_user.name} is working on solving it." | ||
| 97 | + | ||
| 98 | + | ||
| 99 | + | ||
| 100 | + .span4.right | ||
| 101 | + .alert.alert-info | ||
| 102 | + %p | ||
| 103 | + If you're not already familiar with Markdown, you should spend 15 minutes and go over the excellent | ||
| 104 | + %strong= link_to "Markdown Syntax Guide", "http://daringfireball.net/projects/markdown/syntax" | ||
| 105 | + at Daring Fireball. |