Download as
Browse Code »

Commit 4b2e151fc69db11b1772d234a233be7cf6eac671

Authored by Dmitriy Zaporozhets
2 parents 0e5dbd1c 32ae7fb6
Exists in master and in 4 other branches 6-8-stable, 7-0-stable, 7-0-stable-spb, spb-stable

Merge pull request #1283 from riyad/improve-gfm-code-docs 

Improve GFM code documentation
Showing 2 changed files with 33 additions and 7 deletions   Show diff stats
app/helpers/gitlab_markdown_helper.rb
  Diff comments   View file @4b2e151
1 1 module GitlabMarkdownHelper
  2 + # Replaces references (i.e. @abc, #123, !456, ...) in the text with links to
  3 + # the appropriate items in Gitlab.
  4 + #
  5 + # text - the source text
  6 + # html_options - extra options for the reference links as given to link_to
  7 + #
  8 + # note: reference links will only be generated if @project is set
  9 + #
  10 + # see Gitlab::Markdown for details on the supported syntax
2 11 def gfm(text, html_options = {})
3 12 return text if text.nil?
4 13 return text if @project.nil?
5 14  
6   - # Extract pre blocks
  15 + # Extract pre blocks so they are not altered
7 16 # from http://github.github.com/github-flavored-markdown/
8 17 extractions = {}
9 18 text.gsub!(%r{<pre>.*?</pre>|<code>.*?</code>}m) do |match|
... ... @@ -25,7 +34,15 @@ module GitlabMarkdownHelper
25 34 text.html_safe
26 35 end
27 36  
28   - # circumvents nesting links, which will behave bad in browsers
  37 + # Use this in places where you would normally use link_to(gfm(...), ...).
  38 + #
  39 + # It solves a problem occurring with nested links (i.e.
  40 + # "<a>outer text <a>gfm ref</a> more outer text</a>"). This will not be
  41 + # interpreted as intended. Browsers will parse something like
  42 + # "<a>outer text </a><a>gfm ref</a> more outer text" (notice the last part is
  43 + # not linked any more). link_to_gfm corrects that. It wraps all parts to
  44 + # explicitly produce the correct linking behavior (i.e.
  45 + # "<a>outer text </a><a>gfm ref</a><a> more outer text</a>").
29 46 def link_to_gfm(body, url, html_options = {})
30 47 gfm_body = gfm(body, html_options)
31 48  
... ...
lib/gitlab/markdown.rb
  Diff comments   View file @4b2e151
1 1 module Gitlab
2   - # Custom parsing for Gitlab-flavored Markdown
  2 + # Custom parser for Gitlab-flavored Markdown
  3 + #
  4 + # It replaces references in the text with links to the appropriate items in Gitlab.
  5 + #
  6 + # Supported reference formats are:
  7 + # * @foo for team members
  8 + # * #123 for issues
  9 + # * !123 for merge requests
  10 + # * $123 for snippets
  11 + # * 123456 for commits
3 12 #
4 13 # Examples
5 14 #
... ... @@ -67,25 +76,25 @@ module Gitlab
67 76 def reference_user(identifier)
68 77 if user = @project.users.where(name: identifier).first
69 78 member = @project.users_projects.where(user_id: user).first
70   - link_to("@#{user.name}", project_team_member_path(@project, member), html_options.merge(class: "gfm gfm-team_member #{html_options[:class]}")) if member
  79 + link_to("@#{identifier}", project_team_member_path(@project, member), html_options.merge(class: "gfm gfm-team_member #{html_options[:class]}")) if member
71 80 end
72 81 end
73 82  
74 83 def reference_issue(identifier)
75 84 if issue = @project.issues.where(id: identifier).first
76   - link_to("##{issue.id}", project_issue_path(@project, issue), html_options.merge(title: "Issue: #{issue.title}", class: "gfm gfm-issue #{html_options[:class]}"))
  85 + link_to("##{identifier}", project_issue_path(@project, issue), html_options.merge(title: "Issue: #{issue.title}", class: "gfm gfm-issue #{html_options[:class]}"))
77 86 end
78 87 end
79 88  
80 89 def reference_merge_request(identifier)
81 90 if merge_request = @project.merge_requests.where(id: identifier).first
82   - link_to("!#{merge_request.id}", project_merge_request_path(@project, merge_request), html_options.merge(title: "Merge Request: #{merge_request.title}", class: "gfm gfm-merge_request #{html_options[:class]}"))
  91 + link_to("!#{identifier}", project_merge_request_path(@project, merge_request), html_options.merge(title: "Merge Request: #{merge_request.title}", class: "gfm gfm-merge_request #{html_options[:class]}"))
83 92 end
84 93 end
85 94  
86 95 def reference_snippet(identifier)
87 96 if snippet = @project.snippets.where(id: identifier).first
88   - link_to("$#{snippet.id}", project_snippet_path(@project, snippet), html_options.merge(title: "Snippet: #{snippet.title}", class: "gfm gfm-snippet #{html_options[:class]}"))
  97 + link_to("$#{identifier}", project_snippet_path(@project, snippet), html_options.merge(title: "Snippet: #{snippet.title}", class: "gfm gfm-snippet #{html_options[:class]}"))
89 98 end
90 99 end
91 100  
... ...