Commit 32ae7fb616673a003ba24dcde1ded3bad8ff37d1
1 parent
0e5dbd1c
Exists in
master
and in
4 other branches
Improve GFM code documentation
Showing
2 changed files
with
33 additions
and
7 deletions
Show diff stats
app/helpers/gitlab_markdown_helper.rb
| 1 | module GitlabMarkdownHelper | 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 | def gfm(text, html_options = {}) | 11 | def gfm(text, html_options = {}) |
| 3 | return text if text.nil? | 12 | return text if text.nil? |
| 4 | return text if @project.nil? | 13 | return text if @project.nil? |
| 5 | 14 | ||
| 6 | - # Extract pre blocks | 15 | + # Extract pre blocks so they are not altered |
| 7 | # from http://github.github.com/github-flavored-markdown/ | 16 | # from http://github.github.com/github-flavored-markdown/ |
| 8 | extractions = {} | 17 | extractions = {} |
| 9 | text.gsub!(%r{<pre>.*?</pre>|<code>.*?</code>}m) do |match| | 18 | text.gsub!(%r{<pre>.*?</pre>|<code>.*?</code>}m) do |match| |
| @@ -25,7 +34,15 @@ module GitlabMarkdownHelper | @@ -25,7 +34,15 @@ module GitlabMarkdownHelper | ||
| 25 | text.html_safe | 34 | text.html_safe |
| 26 | end | 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 | def link_to_gfm(body, url, html_options = {}) | 46 | def link_to_gfm(body, url, html_options = {}) |
| 30 | gfm_body = gfm(body, html_options) | 47 | gfm_body = gfm(body, html_options) |
| 31 | 48 |
lib/gitlab/markdown.rb
| 1 | module Gitlab | 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 | # Examples | 13 | # Examples |
| 5 | # | 14 | # |
| @@ -67,25 +76,25 @@ module Gitlab | @@ -67,25 +76,25 @@ module Gitlab | ||
| 67 | def reference_user(identifier) | 76 | def reference_user(identifier) |
| 68 | if user = @project.users.where(name: identifier).first | 77 | if user = @project.users.where(name: identifier).first |
| 69 | member = @project.users_projects.where(user_id: user).first | 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 | end | 80 | end |
| 72 | end | 81 | end |
| 73 | 82 | ||
| 74 | def reference_issue(identifier) | 83 | def reference_issue(identifier) |
| 75 | if issue = @project.issues.where(id: identifier).first | 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 | end | 86 | end |
| 78 | end | 87 | end |
| 79 | 88 | ||
| 80 | def reference_merge_request(identifier) | 89 | def reference_merge_request(identifier) |
| 81 | if merge_request = @project.merge_requests.where(id: identifier).first | 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 | end | 92 | end |
| 84 | end | 93 | end |
| 85 | 94 | ||
| 86 | def reference_snippet(identifier) | 95 | def reference_snippet(identifier) |
| 87 | if snippet = @project.snippets.where(id: identifier).first | 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 | end | 98 | end |
| 90 | end | 99 | end |
| 91 | 100 |