markdown.rb 10 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
  #
18 19
  # It also parses Emoji codes to insert images. See
  # http://www.emoji-cheat-sheet.com/ for a list of the supported icons.
20
  #
21
  # Examples
22
  #
23
  #   >> gfm("Hey @david, can you fix this?")
Martin Bastien's avatar
Martin Bastien committed
24
  #   => "Hey <a href="/u/david">@david</a>, can you fix this?"
25
  #
26
  #   >> gfm("Commit 35d5f7c closes #1234")
27
  #   => "Commit <a href="/gitlab/commits/35d5f7c">35d5f7c</a> closes <a href="/gitlab/issues/1234">#1234</a>"
28 29 30 31
  #
  #   >> gfm(":trollface:")
  #   => "<img alt=\":trollface:\" class=\"emoji\" src=\"/images/trollface.png" title=\":trollface:\" />
  module Markdown
32 33
    include IssuesHelper

34 35
    attr_reader :html_options

36 37 38 39 40
    def gfm_with_tasks(text, project = @project, html_options = {})
      text = gfm(text, project, html_options)
      parse_tasks(text)
    end

41 42 43
    # Public: Parse the provided text with GitLab-Flavored Markdown
    #
    # text         - the source text
skv's avatar
skv committed
44
    # project      - extra options for the reference links as given to link_to
45
    # html_options - extra options for the reference links as given to link_to
skv's avatar
skv committed
46
    def gfm(text, project = @project, html_options = {})
47 48
      return text if text.nil?

49 50 51 52
      # 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
53

54
      @html_options = html_options
55 56 57

      # Extract pre blocks so they are not altered
      # from http://github.github.com/github-flavored-markdown/
58 59 60 61 62
      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) }
63 64 65

      # TODO: add popups with additional information

skv's avatar
skv committed
66
      text = parse(text, project)
67 68 69

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

73 74 75 76 77 78 79
      # Used markdown pipelines in GitLab:
      # GitlabEmojiFilter - performs emoji replacement.
      #
      # see https://gitlab.com/gitlab-org/html-pipeline-gitlab for more filters
      filters = [
        HTML::Pipeline::Gitlab::GitlabEmojiFilter
      ]
80

81 82 83 84 85
      markdown_context = {
              asset_root: Gitlab.config.gitlab.url,
              asset_host: Gitlab::Application.config.asset_host
      }

86 87
      markdown_pipeline = HTML::Pipeline::Gitlab.new(filters).pipeline

88
      result = markdown_pipeline.call(text, markdown_context)
89 90
      text = result[:output].to_html(save_with: 0)

skv's avatar
skv committed
91 92 93 94 95 96
      allowed_attributes = ActionView::Base.sanitized_allowed_attributes
      allowed_tags = ActionView::Base.sanitized_allowed_tags

      sanitize text.html_safe,
               attributes: allowed_attributes + %w(id class),
               tags: allowed_tags + %w(table tr td th)
97 98
    end

99 100
    private

101 102 103 104 105 106 107 108 109 110 111 112
    def extract_piece(text)
      @extractions ||= {}

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

    def insert_piece(id)
      @extractions[id]
    end

113 114 115 116 117
    # Private: Parses text for references and emoji
    #
    # text - Text to parse
    #
    # Returns parsed text
skv's avatar
skv committed
118 119
    def parse(text, project = @project)
      parse_references(text, project) if project
120 121 122 123

      text
    end

124 125 126
    NAME_STR = '[a-zA-Z][a-zA-Z0-9_\-\.]*'
    PROJ_STR = "(?<project>#{NAME_STR}/#{NAME_STR})"

127
    REFERENCE_PATTERN = %r{
128 129
      (?<prefix>\W)?                         # Prefix
      (                                      # Reference
130
         @(?<user>#{NAME_STR})               # User name
131
        |(?<issue>([A-Z\-]+-)\d+)            # JIRA Issue ID
132 133
        |#{PROJ_STR}?\#(?<issue>([a-zA-Z\-]+-)?\d+) # Issue ID
        |#{PROJ_STR}?!(?<merge_request>\d+)  # MR ID
134
        |\$(?<snippet>\d+)                   # Snippet ID
135
        |(#{PROJ_STR}@)?(?<commit>[\h]{6,40}) # Commit ID
136
        |(?<skip>gfm-extraction-[\h]{6,40})  # Skip gfm extractions. Otherwise will be parsed as commit
137
      )
138
      (?<suffix>\W)?                         # Suffix
139 140
    }x.freeze

141 142
    TYPES = [:user, :issue, :merge_request, :snippet, :commit].freeze

skv's avatar
skv committed
143
    def parse_references(text, project = @project)
144
      # parse reference links
145
      text.gsub!(REFERENCE_PATTERN) do |match|
146
        type       = TYPES.select{|t| !$~[t].nil?}.first
147

148 149 150 151 152 153
        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
154
        end
155 156 157 158 159 160 161

        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
162 163 164
    # 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.
165 166 167 168
    def parse_result(match_info, type, project, project_prefix)
      prefix = match_info[:prefix]
      suffix = match_info[:suffix]

Vinnie Okada's avatar
Vinnie Okada committed
169 170
      return nil if html_entity?(prefix, suffix) || type.nil?
      return nil if project.nil? && !project_prefix.nil?
171 172 173 174 175 176 177 178

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

      if ref_link
        "#{prefix}#{ref_link}#{suffix}"
      else
        nil
179 180
      end
    end
181

182 183 184 185 186 187
    # 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

188 189 190 191 192 193
    # 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
194 195
    def reference_link(type, identifier, project = @project, prefix_text = nil)
      send("reference_#{type}", identifier, project, prefix_text)
196 197
    end

198
    def reference_user(identifier, project = @project, _ = nil)
199
      options = html_options.merge(
200 201
          class: "gfm gfm-team_member #{html_options[:class]}"
        )
202 203

      if identifier == "all"
204
        link_to("@all", project_url(project), options)
205
      elsif User.find_by(username: identifier)
skv's avatar
skv committed
206
        link_to("@#{identifier}", user_url(identifier), options)
207 208 209
      end
    end

210
    def reference_issue(identifier, project = @project, prefix_text = nil)
211
      if project.using_issue_tracker?
skv's avatar
skv committed
212 213
        if project.issue_exists? identifier
          url = url_for_issue(identifier, project)
214
          title = title_for_issue(identifier, project)
skv's avatar
skv committed
215 216 217 218
          options = html_options.merge(
            title: "Issue: #{title}",
            class: "gfm gfm-issue #{html_options[:class]}"
          )
219

220
          link_to("#{prefix_text}##{identifier}", url, options)
221
        end
222
      else
223
        external_issue_tracker = project.external_issue_tracker
224
        if external_issue_tracker.present?
Vinnie Okada's avatar
Vinnie Okada committed
225 226
          reference_external_issue(identifier, external_issue_tracker, project,
                                   prefix_text)
227
        end
228 229 230
      end
    end

231 232
    def reference_merge_request(identifier, project = @project,
                                prefix_text = nil)
skv's avatar
skv committed
233 234 235 236 237 238
      if merge_request = project.merge_requests.find_by(iid: identifier)
        options = html_options.merge(
          title: "Merge Request: #{merge_request.title}",
          class: "gfm gfm-merge_request #{html_options[:class]}"
        )
        url = project_merge_request_url(project, merge_request)
239
        link_to("#{prefix_text}!#{identifier}", url, options)
240 241 242
      end
    end

243
    def reference_snippet(identifier, project = @project, _ = nil)
skv's avatar
skv committed
244 245 246 247 248 249 250
      if snippet = project.snippets.find_by(id: identifier)
        options = html_options.merge(
          title: "Snippet: #{snippet.title}",
          class: "gfm gfm-snippet #{html_options[:class]}"
        )
        link_to("$#{identifier}", project_snippet_url(project, snippet),
                options)
251 252 253
      end
    end

254
    def reference_commit(identifier, project = @project, prefix_text = nil)
skv's avatar
skv committed
255 256 257 258 259
      if project.valid_repo? && commit = project.repository.commit(identifier)
        options = html_options.merge(
          title: commit.link_title,
          class: "gfm gfm-commit #{html_options[:class]}"
        )
Vinnie Okada's avatar
Vinnie Okada committed
260
        prefix_text = "#{prefix_text}@" if prefix_text
261 262 263 264 265
        link_to(
          "#{prefix_text}#{identifier}",
          project_commit_url(project, commit),
          options
        )
266 267
      end
    end
268

269
    def reference_external_issue(identifier, issue_tracker, project = @project,
Vinnie Okada's avatar
Vinnie Okada committed
270
                                 prefix_text = nil)
Andrew Kumanyaev's avatar
Andrew Kumanyaev committed
271
      url = url_for_issue(identifier, project)
272
      title = issue_tracker.title
273

skv's avatar
skv committed
274 275 276 277
      options = html_options.merge(
        title: "Issue in #{title}",
        class: "gfm gfm-issue #{html_options[:class]}"
      )
Vinnie Okada's avatar
Vinnie Okada committed
278
      link_to("#{prefix_text}##{identifier}", url, options)
279
    end
280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298

    # 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'

        if checked
          "#{li_tag}#{checked_box}"
        else
          "#{li_tag}#{unchecked_box}"
        end
      end
    end
299 300
  end
end