markdown.rb 7.11 KB
Newer Older
1 2
require 'html/pipeline'

3
module Gitlab
4
  # Custom parser for GitLab-flavored Markdown
5
  #
6
  # See the files in `lib/gitlab/markdown/` for specific processing information.
7
  module Markdown
8 9
    # Convert a Markdown String into an HTML-safe String of HTML
    #
10 11 12 13 14 15 16 17
    # Note that while the returned HTML will have been sanitized of dangerous
    # HTML, it may post a risk of information leakage if it's not also passed
    # through `post_process`.
    #
    # Also note that the returned String is always HTML, not XHTML. Views
    # requiring XHTML, such as Atom feeds, need to call `post_process` on the
    # result, providing the appropriate `pipeline` option.
    #
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
    # markdown - Markdown String
    # context  - Hash of context options passed to our HTML Pipeline
    #
    # Returns an HTML-safe String
    def self.render(markdown, context = {})
      html = renderer.render(markdown)
      html = gfm(html, context)

      html.html_safe
    end

    # Convert a Markdown String into HTML without going through the HTML
    # Pipeline.
    #
    # Note that because the pipeline is skipped, SanitizationFilter is as well.
    # Do not output the result of this method to the user.
    #
    # markdown - Markdown String
    #
    # Returns a String
    def self.render_without_gfm(markdown)
39
      renderer.render(markdown)
40 41
    end

42 43 44 45 46 47 48
    # Perform post-processing on an HTML String
    #
    # This method is used to perform state-dependent changes to a String of
    # HTML, such as removing references that the current user doesn't have
    # permission to make (`RedactorFilter`).
    #
    # html     - String to process
49
    # options  - Hash of options to customize output
50 51 52
    #            :pipeline  - Symbol pipeline type
    #            :project   - Project
    #            :user      - User object
53 54
    #
    # Returns an HTML-safe String
55
    def self.post_process(html, options)
56 57 58 59 60
      context = {
        project:      options[:project],
        current_user: options[:user]
      }
      doc = post_processor.to_document(html, context)
61 62 63 64 65 66

      if options[:pipeline] == :atom
        doc.to_html(save_with: Nokogiri::XML::Node::SaveOptions::AS_XHTML)
      else
        doc.to_html
      end.html_safe
67 68
    end

69
    # Provide autoload paths for filters to prevent a circular dependency error
70
    autoload :AutolinkFilter,               'gitlab/markdown/autolink_filter'
71 72 73 74
    autoload :CommitRangeReferenceFilter,   'gitlab/markdown/commit_range_reference_filter'
    autoload :CommitReferenceFilter,        'gitlab/markdown/commit_reference_filter'
    autoload :EmojiFilter,                  'gitlab/markdown/emoji_filter'
    autoload :ExternalIssueReferenceFilter, 'gitlab/markdown/external_issue_reference_filter'
75
    autoload :ExternalLinkFilter,           'gitlab/markdown/external_link_filter'
76 77 78
    autoload :IssueReferenceFilter,         'gitlab/markdown/issue_reference_filter'
    autoload :LabelReferenceFilter,         'gitlab/markdown/label_reference_filter'
    autoload :MergeRequestReferenceFilter,  'gitlab/markdown/merge_request_reference_filter'
Robert Speicher's avatar
Robert Speicher committed
79
    autoload :RedactorFilter,               'gitlab/markdown/redactor_filter'
80
    autoload :RelativeLinkFilter,           'gitlab/markdown/relative_link_filter'
81
    autoload :SanitizationFilter,           'gitlab/markdown/sanitization_filter'
82
    autoload :SnippetReferenceFilter,       'gitlab/markdown/snippet_reference_filter'
83
    autoload :SyntaxHighlightFilter,        'gitlab/markdown/syntax_highlight_filter'
84
    autoload :TableOfContentsFilter,        'gitlab/markdown/table_of_contents_filter'
85
    autoload :TaskListFilter,               'gitlab/markdown/task_list_filter'
86
    autoload :UserReferenceFilter,          'gitlab/markdown/user_reference_filter'
87
    autoload :UploadLinkFilter,             'gitlab/markdown/upload_link_filter'
88

89
    # Public: Parse the provided HTML with GitLab-Flavored Markdown
90
    #
91 92 93 94 95 96 97 98 99 100 101 102
    # html    - HTML String
    # options - A Hash of options used to customize output (default: {})
    #           :no_header_anchors - Disable header anchors in TableOfContentsFilter
    #           :path              - Current path String
    #           :pipeline          - Symbol pipeline type
    #           :project           - Current Project object
    #           :project_wiki      - Current ProjectWiki object
    #           :ref               - Current ref String
    #
    # Returns an HTML-safe String
    def self.gfm(html, options = {})
      return '' unless html.present?
103

104
      @pipeline ||= HTML::Pipeline.new(filters)
105 106

      context = {
107 108 109
        # SanitizationFilter
        pipeline: options[:pipeline],

110
        # EmojiFilter
111
        asset_host: Gitlab::Application.config.asset_host,
112
        asset_root: Gitlab.config.gitlab.base_url,
113

114
        # ReferenceFilter
115 116
        only_path: only_path_pipeline?(options[:pipeline]),
        project:   options[:project],
117 118

        # RelativeLinkFilter
119
        project_wiki:   options[:project_wiki],
120 121
        ref:            options[:ref],
        requested_path: options[:path],
122

123 124 125
        # TableOfContentsFilter
        no_header_anchors: options[:no_header_anchors]
      }
skv's avatar
skv committed
126

127
      @pipeline.to_html(html, context).html_safe
128 129
    end

130 131
    private

132 133 134 135 136 137 138 139 140
    # Check if a pipeline enables the `only_path` context option
    #
    # Returns Boolean
    def self.only_path_pipeline?(pipeline)
      case pipeline
      when :atom, :email
        false
      else
        true
141 142 143
      end
    end

144 145 146 147 148 149 150 151 152 153 154 155 156 157
    def self.redcarpet_options
      # https://github.com/vmg/redcarpet#and-its-like-really-simple-to-use
      @redcarpet_options ||= {
        fenced_code_blocks:  true,
        footnotes:           true,
        lax_spacing:         true,
        no_intra_emphasis:   true,
        space_after_headers: true,
        strikethrough:       true,
        superscript:         true,
        tables:              true
      }.freeze
    end

158 159 160 161 162 163 164 165 166 167 168
    def self.renderer
      @markdown ||= begin
        renderer = Redcarpet::Render::HTML.new
        Redcarpet::Markdown.new(renderer, redcarpet_options)
      end
    end

    def self.post_processor
      @post_processor ||= HTML::Pipeline.new([Gitlab::Markdown::RedactorFilter])
    end

169
    # Filters used in our pipeline
170
    #
171 172 173
    # SanitizationFilter should come first so that all generated reference HTML
    # goes through untouched.
    #
174
    # See https://github.com/jch/html-pipeline#filters for more filters.
175
    def self.filters
176
      [
177
        Gitlab::Markdown::SyntaxHighlightFilter,
178
        Gitlab::Markdown::SanitizationFilter,
179

180
        Gitlab::Markdown::UploadLinkFilter,
181
        Gitlab::Markdown::RelativeLinkFilter,
182
        Gitlab::Markdown::EmojiFilter,
183
        Gitlab::Markdown::TableOfContentsFilter,
184
        Gitlab::Markdown::AutolinkFilter,
185
        Gitlab::Markdown::ExternalLinkFilter,
186

187 188 189 190 191 192 193
        Gitlab::Markdown::UserReferenceFilter,
        Gitlab::Markdown::IssueReferenceFilter,
        Gitlab::Markdown::ExternalIssueReferenceFilter,
        Gitlab::Markdown::MergeRequestReferenceFilter,
        Gitlab::Markdown::SnippetReferenceFilter,
        Gitlab::Markdown::CommitRangeReferenceFilter,
        Gitlab::Markdown::CommitReferenceFilter,
194 195
        Gitlab::Markdown::LabelReferenceFilter,

196
        Gitlab::Markdown::TaskListFilter
197
      ]
198
    end
199 200
  end
end