Download as
Browse Code »

Commit 04b2864b64a11a347401e1817d1409e9c8b3b50f

Authored by Dmitriy Zaporozhets
2 parents 867f4607 1f1ce5fb
Exists in master and in 4 other branches 6-8-stable, 7-0-stable, 7-0-stable-spb, spb-stable

Merge pull request #1290 from riyad/improve-gfm-user-docs 

Improve GFM user docs
Showing 7 changed files with 126 additions and 35 deletions   Show diff stats
app/assets/stylesheets/sections/notes.scss
  Diff comments   View file @04b2864
... ... @@ -38,6 +38,10 @@
38 38 }
39 39 }
40 40  
  41 +#preview-note {
  42 + margin-bottom: 0;
  43 +}
  44 +
41 45 .note {
42 46 padding: 8px 0;
43 47 border-bottom: 1px solid #eee;
... ...
app/helpers/gitlab_markdown_helper.rb
  Diff comments   View file @04b2864
... ... @@ -54,17 +54,24 @@ module GitlabMarkdownHelper
54 54 end
55 55  
56 56 def markdown(text)
57   - @__renderer ||= Redcarpet::Markdown.new(Redcarpet::Render::GitlabHTML.new(self, filter_html: true, with_toc_data: true), {
58   - no_intra_emphasis: true,
59   - tables: true,
60   - fenced_code_blocks: true,
61   - autolink: true,
62   - strikethrough: true,
63   - lax_html_blocks: true,
64   - space_after_headers: true,
65   - superscript: true
66   - })
  57 + unless @markdown
  58 + gitlab_renderer = Redcarpet::Render::GitlabHTML.new(self,
  59 + # see https://github.com/vmg/redcarpet#darling-i-packed-you-a-couple-renderers-for-lunch-
  60 + filter_html: true,
  61 + with_toc_data: true,
  62 + hard_wrap: true)
  63 + @markdown ||= Redcarpet::Markdown.new(gitlab_renderer,
  64 + # see https://github.com/vmg/redcarpet#and-its-like-really-simple-to-use
  65 + no_intra_emphasis: true,
  66 + tables: true,
  67 + fenced_code_blocks: true,
  68 + autolink: true,
  69 + strikethrough: true,
  70 + lax_html_blocks: true,
  71 + space_after_headers: true,
  72 + superscript: true)
  73 + end
67 74  
68   - @__renderer.render(text).html_safe
  75 + @markdown.render(text).html_safe
69 76 end
70 77 end
... ...
app/views/help/markdown.html.haml
  Diff comments   View file @04b2864
1   -- bash_lexer = Pygments::Lexer[:bash]
2   -%h3.page_title Gitlab Markdown
  1 +%h3.page_title Gitlab Flavored Markdown
3 2 .back_link
4 3 = link_to help_path do
5 4 ← to index
6 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.
... ...
app/views/issues/_form.html.haml
  Diff comments   View file @04b2864
... ... @@ -38,7 +38,7 @@
38 38 = f.label :description, "Details"
39 39 .input
40 40 = f.text_area :description, maxlength: 2000, class: "xxlarge", rows: 14
41   - %p.hint Markdown is enabled.
  41 + %p.hint Issues are parsed with #{link_to "Gitlab Flavored Markdown", help_markdown_path, target: '_blank'}.
42 42  
43 43  
44 44 .actions
... ...
app/views/milestones/_form.html.haml
  Diff comments   View file @04b2864
... ... @@ -22,7 +22,7 @@
22 22 = f.label :description, "Description", class: "control-label"
23 23 .controls
24 24 = f.text_area :description, maxlength: 2000, class: "input-xlarge", rows: 10
25   - %p.hint Markdown is enabled.
  25 + %p.hint Milestones are parsed with #{link_to "Gitlab Flavored Markdown", help_markdown_path, target: '_blank'}.
26 26 .span6
27 27 .control-group
28 28 = f.label :due_date, "Due Date", class: "control-label"
... ...
app/views/notes/_form.html.haml
  Diff comments   View file @04b2864
... ... @@ -9,10 +9,9 @@
9 9 = f.hidden_field :noteable_type
10 10 = f.text_area :note, size: 255
11 11 #preview-note.well.hide
12   - %p.hint
13   - = link_to "Gitlab Markdown", help_markdown_path, target: '_blank'
14   - is enabled.
  12 + .hint
15 13 = link_to 'Preview', preview_project_notes_path(@project), id: 'preview-link'
  14 + .right Comments are parsed with #{link_to "Gitlab Flavored Markdown", help_markdown_path, target: '_blank'}.
16 15  
17 16 .row.note_advanced_opts.hide
18 17 .span2
... ...
app/views/wikis/_form.html.haml
  Diff comments   View file @04b2864
... ... @@ -14,9 +14,10 @@
14 14 .middle_box_content
15 15 .input
16 16 %span.cgray
17   - Wiki content is parsed with #{link_to "Markdown", "http://en.wikipedia.org/wiki/Markdown"}.
18   - To add link to new page you can just type
  17 + Wiki content is parsed with #{link_to "Gitlab Flavored Markdown", help_markdown_path, target: '_blank'}.
  18 + To link to a (new) page you can just type
19 19 %code [Link Title](page-slug)
  20 + \.
20 21  
21 22 .bottom_box_content
22 23 = f.label :content
... ...