markdown.rb 13.6 KB
Newer Older
1 2 3
require 'html/pipeline'
require 'html/pipeline/gitlab'

4
module Gitlab
5
  # Custom parser for GitLab-flavored Markdown
6
  #
7
  # It replaces references in the text with links to the appropriate items in
8
  # GitLab.
9 10 11 12
  #
  # Supported reference formats are:
  #   * @foo for team members
  #   * #123 for issues
13
  #   * #JIRA-123 for Jira issues
14 15 16
  #   * !123 for merge requests
  #   * $123 for snippets
  #   * 123456 for commits
17
  #   * 123456...7890123 for commit ranges (comparisons)
18
  #
19 20
  # It also parses Emoji codes to insert images. See
  # http://www.emoji-cheat-sheet.com/ for a list of the supported icons.
21
  #
22
  # Examples
23
  #
24
  #   >> gfm("Hey @david, can you fix this?")
Martin Bastien's avatar
Martin Bastien committed
25
  #   => "Hey <a href="/u/david">@david</a>, can you fix this?"
26
  #
27
  #   >> gfm("Commit 35d5f7c closes #1234")
28
  #   => "Commit <a href="/gitlab/commits/35d5f7c">35d5f7c</a> closes <a href="/gitlab/issues/1234">#1234</a>"
29 30 31 32
  #
  #   >> gfm(":trollface:")
  #   => "<img alt=\":trollface:\" class=\"emoji\" src=\"/images/trollface.png" title=\":trollface:\" />
  module Markdown
33 34
    include IssuesHelper

35
    attr_reader :options, :html_options
36

37 38 39
    # Public: Parse the provided text with GitLab-Flavored Markdown
    #
    # text         - the source text
40
    # project      - the project
41 42 43
    # html_options - extra options for the reference links as given to link_to
    def gfm(text, project = @project, html_options = {})
      gfm_with_options(text, {}, project, html_options)
44 45
    end

46 47 48
    # Public: Parse the provided text with GitLab-Flavored Markdown
    #
    # text         - the source text
49 50 51 52
    # options      - parse_tasks          - render tasks
    #              - xhtml                - output XHTML instead of HTML
    #              - reference_only_path  - Use relative path for reference links
    # project      - the project
53
    # html_options - extra options for the reference links as given to link_to
54
    def gfm_with_options(text, options = {}, project = @project, html_options = {})
55 56
      return text if text.nil?

57 58 59 60
      # Duplicate the string so we don't alter the original, then call to_str
      # to cast it back to a String instead of a SafeBuffer. This is required
      # for gsub calls to work as we need them to.
      text = text.dup.to_str
61

62 63 64 65 66 67 68
      options.reverse_merge!(
        parse_tasks:          false,
        xhtml:                false,
        reference_only_path:  true
      )

      @options      = options
69
      @html_options = html_options
70 71 72

      # Extract pre blocks so they are not altered
      # from http://github.github.com/github-flavored-markdown/
73 74 75 76 77
      text.gsub!(%r{<pre>.*?</pre>|<code>.*?</code>}m) { |match| extract_piece(match) }
      # Extract links with probably parsable hrefs
      text.gsub!(%r{<a.*?>.*?</a>}m) { |match| extract_piece(match) }
      # Extract images with probably parsable src
      text.gsub!(%r{<img.*?>}m) { |match| extract_piece(match) }
78 79 80

      # TODO: add popups with additional information

skv's avatar
skv committed
81
      text = parse(text, project)
82 83 84

      # Insert pre block extractions
      text.gsub!(/\{gfm-extraction-(\h{32})\}/) do
85
        insert_piece($1)
86 87
      end

88 89
      # Used markdown pipelines in GitLab:
      # GitlabEmojiFilter - performs emoji replacement.
Vinnie Okada's avatar
Vinnie Okada committed
90
      # SanitizationFilter - remove unsafe HTML tags and attributes
91 92 93
      #
      # see https://gitlab.com/gitlab-org/html-pipeline-gitlab for more filters
      filters = [
Vinnie Okada's avatar
Vinnie Okada committed
94 95
        HTML::Pipeline::Gitlab::GitlabEmojiFilter,
        HTML::Pipeline::SanitizationFilter
96
      ]
97

Vinnie Okada's avatar
Vinnie Okada committed
98
      whitelist = HTML::Pipeline::SanitizationFilter::WHITELIST
99
      whitelist[:attributes][:all].push('class', 'id')
Vinnie Okada's avatar
Vinnie Okada committed
100
      whitelist[:elements].push('span')
Vinnie Okada's avatar
Vinnie Okada committed
101 102 103 104 105 106 107 108 109 110 111 112 113 114

      # Remove the rel attribute that the sanitize gem adds, and remove the
      # href attribute if it contains inline javascript
      fix_anchors = lambda do |env|
        name, node = env[:node_name], env[:node]
        if name == 'a'
          node.remove_attribute('rel')
          if node['href'] && node['href'].match('javascript:')
            node.remove_attribute('href')
          end
        end
      end
      whitelist[:transformers].push(fix_anchors)

115
      markdown_context = {
116
              asset_root: Gitlab.config.gitlab.url,
Vinnie Okada's avatar
Vinnie Okada committed
117 118
              asset_host: Gitlab::Application.config.asset_host,
              whitelist: whitelist
119 120
      }

121 122
      markdown_pipeline = HTML::Pipeline::Gitlab.new(filters).pipeline

123
      result = markdown_pipeline.call(text, markdown_context)
124

125
      save_options = 0
126
      if options[:xhtml]
127
        save_options |= Nokogiri::XML::Node::SaveOptions::AS_XHTML
128
      end
129

130
      text = result[:output].to_html(save_with: save_options)
skv's avatar
skv committed
131

132 133 134
      if options[:parse_tasks]
        text = parse_tasks(text)
      end
Vinnie Okada's avatar
Vinnie Okada committed
135

Vinnie Okada's avatar
Vinnie Okada committed
136
      text.html_safe
137 138
    end

139 140
    private

141 142 143 144 145 146 147 148 149 150 151 152
    def extract_piece(text)
      @extractions ||= {}

      md5 = Digest::MD5.hexdigest(text)
      @extractions[md5] = text
      "{gfm-extraction-#{md5}}"
    end

    def insert_piece(id)
      @extractions[id]
    end

153 154 155 156 157
    # Private: Parses text for references and emoji
    #
    # text - Text to parse
    #
    # Returns parsed text
skv's avatar
skv committed
158 159
    def parse(text, project = @project)
      parse_references(text, project) if project
160 161 162 163

      text
    end

164
    NAME_STR = Gitlab::Regex::NAMESPACE_REGEX_STR
165 166
    PROJ_STR = "(?<project>#{NAME_STR}/#{NAME_STR})"

167
    REFERENCE_PATTERN = %r{
168 169
      (?<prefix>\W)?                         # Prefix
      (                                      # Reference
170
         @(?<user>#{NAME_STR})               # User name
Nikita Verkhovin's avatar
Nikita Verkhovin committed
171
        |~(?<label>\d+)                      # Label ID
172
        |(?<issue>([A-Z\-]+-)\d+)            # JIRA Issue ID
173 174
        |#{PROJ_STR}?\#(?<issue>([a-zA-Z\-]+-)?\d+) # Issue ID
        |#{PROJ_STR}?!(?<merge_request>\d+)  # MR ID
175
        |\$(?<snippet>\d+)                   # Snippet ID
176
        |(#{PROJ_STR}@)?(?<commit_range>[\h]{6,40}\.{2,3}[\h]{6,40}) # Commit range
177
        |(#{PROJ_STR}@)?(?<commit>[\h]{6,40}) # Commit ID
178
        |(?<skip>gfm-extraction-[\h]{6,40})  # Skip gfm extractions. Otherwise will be parsed as commit
179
      )
180
      (?<suffix>\W)?                         # Suffix
181 182
    }x.freeze

183
    TYPES = [:user, :issue, :label, :merge_request, :snippet, :commit, :commit_range].freeze
184

skv's avatar
skv committed
185
    def parse_references(text, project = @project)
186
      # parse reference links
187
      text.gsub!(REFERENCE_PATTERN) do |match|
188
        type       = TYPES.select{|t| !$~[t].nil?}.first
189

190 191 192 193 194 195
        actual_project = project
        project_prefix = nil
        project_path = $LAST_MATCH_INFO[:project]
        if project_path
          actual_project = ::Project.find_with_namespace(project_path)
          project_prefix = project_path
196
        end
197 198 199 200 201 202 203

        parse_result($LAST_MATCH_INFO, type,
                     actual_project, project_prefix) || match
      end
    end

    # Called from #parse_references.  Attempts to build a gitlab reference
Vinnie Okada's avatar
Vinnie Okada committed
204 205 206
    # link.  Returns nil if +type+ is nil, if the match string is an HTML
    # entity, if the reference is invalid, or if the matched text includes an
    # invalid project path.
207 208 209 210
    def parse_result(match_info, type, project, project_prefix)
      prefix = match_info[:prefix]
      suffix = match_info[:suffix]

Vinnie Okada's avatar
Vinnie Okada committed
211 212
      return nil if html_entity?(prefix, suffix) || type.nil?
      return nil if project.nil? && !project_prefix.nil?
213 214 215 216 217 218 219 220

      identifier = match_info[type]
      ref_link = reference_link(type, identifier, project, project_prefix)

      if ref_link
        "#{prefix}#{ref_link}#{suffix}"
      else
        nil
221 222
      end
    end
223

224 225 226 227 228 229
    # Return true if the +prefix+ and +suffix+ indicate that the matched string
    # is an HTML entity like &amp;
    def html_entity?(prefix, suffix)
      prefix && suffix && prefix[0] == '&' && suffix[-1] == ';'
    end

230 231 232 233 234 235
    # Private: Dispatches to a dedicated processing method based on reference
    #
    # reference  - Object reference ("@1234", "!567", etc.)
    # identifier - Object identifier (Issue ID, SHA hash, etc.)
    #
    # Returns string rendered by the processing method
236 237
    def reference_link(type, identifier, project = @project, prefix_text = nil)
      send("reference_#{type}", identifier, project, prefix_text)
238 239
    end

240
    def reference_user(identifier, project = @project, _ = nil)
241
      link_options = html_options.merge(
242
          class: "gfm gfm-project_member #{html_options[:class]}"
243
        )
244 245

      if identifier == "all"
246
        link_to(
247 248
          "@all",
          namespace_project_url(project.namespace, project, only_path: options[:reference_only_path]),
249 250
          link_options
        )
Douwe Maan's avatar
Douwe Maan committed
251 252
      elsif namespace = Namespace.find_by(path: identifier)
        url =
253
          if namespace.is_a?(Group)
254
            group_url(identifier, only_path: options[:reference_only_path])
255
          else
256
            user_url(identifier, only_path: options[:reference_only_path])
Douwe Maan's avatar
Douwe Maan committed
257
          end
258

259
        link_to("@#{identifier}", url, link_options)
260 261 262
      end
    end

Nikita Verkhovin's avatar
Nikita Verkhovin committed
263 264
    def reference_label(identifier, project = @project, _ = nil)
      if label = project.labels.find_by(id: identifier)
265
        link_options = html_options.merge(
Nikita Verkhovin's avatar
Nikita Verkhovin committed
266 267 268 269
          class: "gfm gfm-label #{html_options[:class]}"
        )
        link_to(
          render_colored_label(label),
Vinnie Okada's avatar
Vinnie Okada committed
270
          namespace_project_issues_path(project.namespace, project, label_name: label.name),
271
          link_options
Nikita Verkhovin's avatar
Nikita Verkhovin committed
272
        )
273 274 275
      end
    end

276
    def reference_issue(identifier, project = @project, prefix_text = nil)
277
      if project.default_issues_tracker?
skv's avatar
skv committed
278
        if project.issue_exists? identifier
279
          url = url_for_issue(identifier, project, only_path: options[:reference_only_path])
280
          title = title_for_issue(identifier, project)
281
          link_options = html_options.merge(
skv's avatar
skv committed
282 283 284
            title: "Issue: #{title}",
            class: "gfm gfm-issue #{html_options[:class]}"
          )
285

286
          link_to("#{prefix_text}##{identifier}", url, link_options)
287
        end
288
      else
289 290
        if project.external_issue_tracker.present?
          reference_external_issue(identifier, project,
Vinnie Okada's avatar
Vinnie Okada committed
291
                                   prefix_text)
292
        end
293 294 295
      end
    end

296
    def reference_merge_request(identifier, project = @project, prefix_text = nil)
skv's avatar
skv committed
297
      if merge_request = project.merge_requests.find_by(iid: identifier)
298
        link_options = html_options.merge(
skv's avatar
skv committed
299 300 301
          title: "Merge Request: #{merge_request.title}",
          class: "gfm gfm-merge_request #{html_options[:class]}"
        )
Vinnie Okada's avatar
Vinnie Okada committed
302
        url = namespace_project_merge_request_url(project.namespace, project,
303
                                                  merge_request,
304 305
                                                  only_path: options[:reference_only_path])
        link_to("#{prefix_text}!#{identifier}", url, link_options)
306 307 308
      end
    end

309
    def reference_snippet(identifier, project = @project, _ = nil)
skv's avatar
skv committed
310
      if snippet = project.snippets.find_by(id: identifier)
311
        link_options = html_options.merge(
skv's avatar
skv committed
312 313 314
          title: "Snippet: #{snippet.title}",
          class: "gfm gfm-snippet #{html_options[:class]}"
        )
Vinnie Okada's avatar
Vinnie Okada committed
315 316
        link_to(
          "$#{identifier}",
317
          namespace_project_snippet_url(project.namespace, project, snippet,
318 319
                                        only_path: options[:reference_only_path]),
          link_options
Vinnie Okada's avatar
Vinnie Okada committed
320
        )
321 322 323
      end
    end

324
    def reference_commit(identifier, project = @project, prefix_text = nil)
skv's avatar
skv committed
325
      if project.valid_repo? && commit = project.repository.commit(identifier)
326
        link_options = html_options.merge(
skv's avatar
skv committed
327 328 329
          title: commit.link_title,
          class: "gfm gfm-commit #{html_options[:class]}"
        )
Vinnie Okada's avatar
Vinnie Okada committed
330
        prefix_text = "#{prefix_text}@" if prefix_text
331 332
        link_to(
          "#{prefix_text}#{identifier}",
333
          namespace_project_commit_url( project.namespace, project, commit,
334 335
                                        only_path: options[:reference_only_path]),
          link_options
336
        )
337 338
      end
    end
339

340 341 342 343 344 345
    def reference_commit_range(identifier, project = @project, prefix_text = nil)
      from_id, to_id = identifier.split(/\.{2,3}/, 2)

      inclusive = identifier !~ /\.{3}/
      from_id << "^" if inclusive

346 347
      if project.valid_repo? &&
          from = project.repository.commit(from_id) &&
348 349
          to = project.repository.commit(to_id)

350
        link_options = html_options.merge(
351 352 353 354 355 356 357
          title: "Commits #{from_id} through #{to_id}",
          class: "gfm gfm-commit_range #{html_options[:class]}"
        )
        prefix_text = "#{prefix_text}@" if prefix_text

        link_to(
          "#{prefix_text}#{identifier}",
358 359
          namespace_project_compare_url(project.namespace, project,
                                        from: from_id, to: to_id,
360 361
                                        only_path: options[:reference_only_path]),
          link_options
362
        )
363 364
      end
    end
365

366 367
    def reference_external_issue(identifier, project = @project, prefix_text = nil)
      url = url_for_issue(identifier, project, only_path: options[:reference_only_path])
368
      title = project.external_issue_tracker.title
369

370
      link_options = html_options.merge(
skv's avatar
skv committed
371 372 373
        title: "Issue in #{title}",
        class: "gfm gfm-issue #{html_options[:class]}"
      )
374
      link_to("#{prefix_text}##{identifier}", url, link_options)
375
    end
376 377 378 379 380 381 382 383 384 385 386

    # Turn list items that start with "[ ]" into HTML checkbox inputs.
    def parse_tasks(text)
      li_tag = '<li class="task-list-item">'
      unchecked_box = '<input type="checkbox" value="on" disabled />'
      checked_box = unchecked_box.sub(/\/>$/, 'checked="checked" />')

      # Regexp captures don't seem to work when +text+ is an
      # ActiveSupport::SafeBuffer, hence the `String.new`
      String.new(text).gsub(Taskable::TASK_PATTERN_HTML) do
        checked = $LAST_MATCH_INFO[:checked].downcase == 'x'
Vinnie Okada's avatar
Vinnie Okada committed
387
        p_tag = $LAST_MATCH_INFO[:p_tag]
388 389

        if checked
Vinnie Okada's avatar
Vinnie Okada committed
390
          "#{li_tag}#{p_tag}#{checked_box}"
391
        else
Vinnie Okada's avatar
Vinnie Okada committed
392
          "#{li_tag}#{p_tag}#{unchecked_box}"
393 394 395
        end
      end
    end
396 397
  end
end