diff --git a/app/assets/stylesheets/sections/notes.scss b/app/assets/stylesheets/sections/notes.scss
index 30587ef5b63..afa5095267d 100644
--- a/app/assets/stylesheets/sections/notes.scss
+++ b/app/assets/stylesheets/sections/notes.scss
@@ -38,6 +38,10 @@
}
}
+#preview-note {
+ margin-bottom: 0;
+}
+
.note {
padding: 8px 0;
border-bottom: 1px solid #eee;
diff --git a/app/helpers/gitlab_markdown_helper.rb b/app/helpers/gitlab_markdown_helper.rb
index 88e3473baf2..b4e3b9626e0 100644
--- a/app/helpers/gitlab_markdown_helper.rb
+++ b/app/helpers/gitlab_markdown_helper.rb
@@ -54,17 +54,24 @@ module GitlabMarkdownHelper
end
def markdown(text)
- @__renderer ||= Redcarpet::Markdown.new(Redcarpet::Render::GitlabHTML.new(self, filter_html: true, with_toc_data: true), {
- no_intra_emphasis: true,
- tables: true,
- fenced_code_blocks: true,
- autolink: true,
- strikethrough: true,
- lax_html_blocks: true,
- space_after_headers: true,
- superscript: true
- })
+ unless @markdown
+ gitlab_renderer = Redcarpet::Render::GitlabHTML.new(self,
+ # see https://github.com/vmg/redcarpet#darling-i-packed-you-a-couple-renderers-for-lunch-
+ filter_html: true,
+ with_toc_data: true,
+ hard_wrap: true)
+ @markdown ||= Redcarpet::Markdown.new(gitlab_renderer,
+ # see https://github.com/vmg/redcarpet#and-its-like-really-simple-to-use
+ no_intra_emphasis: true,
+ tables: true,
+ fenced_code_blocks: true,
+ autolink: true,
+ strikethrough: true,
+ lax_html_blocks: true,
+ space_after_headers: true,
+ superscript: true)
+ end
- @__renderer.render(text).html_safe
+ @markdown.render(text).html_safe
end
end
diff --git a/app/views/help/markdown.html.haml b/app/views/help/markdown.html.haml
index 8d6fb2a590f..6a4bbb02c6c 100644
--- a/app/views/help/markdown.html.haml
+++ b/app/views/help/markdown.html.haml
@@ -1,25 +1,105 @@
-- bash_lexer = Pygments::Lexer[:bash]
-%h3.page_title Gitlab Markdown
+%h3.page_title Gitlab Flavored Markdown
.back_link
= link_to help_path do
← to index
%hr
-%p.slead We extend Markdown with some GITLAB specific syntax. It allows you to link to:
+.row
+ .span8
+ %p
+ For Gitlab we developed something we call "Gitlab Flavored Markdown" (GFM).
+ It extends the standard Markdown in a few significant ways adds some useful functionality.
-%ul
- %li issues (#123)
- %li merge request (!123)
- %li commits (1234567)
- %li team members (@foo)
- %li snippets ($123)
+ %p You can use GFM in:
+ %ul
+ %li commit messages
+ %li comments
+ %li wall posts
+ %li issues
+ %li merge requests
+ %li milestones
+ %li wiki pages
-%p.slead in
+ %h3 Differences from traditional Markdown
-%ul
- %li commit messages
- %li notes/comments/wall posts
- %li issues
- %li merge requests
- %li milestones
- %li wiki pages
+ %h4 Newlines
+
+ %p
+ The biggest difference that GFM introduces is in the handling of linebreaks.
+ With traditional Markdown you can hard wrap paragraphs of text and they will be combined into a single paragraph. We find this to be the cause of a huge number of unintentional formatting errors.
+ GFM treats newlines in paragraph-like content as real line breaks, which is probably what you intended.
+
+
+ %p The next paragraph contains two phrases separated by a single newline character:
+ %pre= "Roses are red\nViolets are blue"
+ %p becomes
+ = markdown "Roses are red\nViolets are blue"
+
+ %h4 Multiple underscores in words
+
+ %p
+ It is not reasonable to italicize just part of a word, especially when you're dealing with code and names often appear with multiple underscores.
+ Therefore, GFM ignores multiple underscores in words.
+
+ %pre= "perform_complicated_task\ndo_this_and_do_that_and_another_thing"
+ %p becomes
+ = markdown "perform_complicated_task\ndo_this_and_do_that_and_another_thing"
+
+ %h4 URL autolinking
+
+ %p
+ GFM will autolink standard URLs you copy and paste into your text.
+ So if you want to link to a URL (instead of a textual link), you can simply put the URL in verbatim and it will be turned into a link to that URL.
+
+ %h4 Fenced code blocks
+
+ %p
+ Markdown converts text with four spaces at the front of each line to code blocks.
+ GFM supports that, but we also support fenced blocks.
+ Just wrap your code blocks in ```
and you won't need to indent manually to trigger a code block.
+
+ %pre= %Q{```ruby\nrequire 'redcarpet'\nmarkdown = Redcarpet.new("Hello World!")\nputs markdown.to_html\n```}
+ %p becomes
+ = markdown %Q{```ruby\nrequire 'redcarpet'\nmarkdown = Redcarpet.new("Hello World!")\nputs markdown.to_html\n```}
+
+ %h4 Special Gitlab references
+
+ %p
+ GFM recognizes special references.
+ You can easily reference e.g. a team member, an issue or a commit within a project.
+ GFM will turn that reference into a link so you can navigate between them easily.
+
+ %p GFM will recognize the following references:
+ %ul
+ %li
+ %code @foo
+ for team members
+ %li
+ %code #123
+ for issues
+ %li
+ %code !123
+ for merge request
+ %li
+ %code $123
+ for snippets
+ %li
+ %code 1234567
+ for commits
+
+ -# this example will only be shown if the user has a project with at least one issue
+ - if @project = current_user.projects.first
+ - if issue = @project.issues.first
+ %p For example in your #{link_to @project.name, project_path(@project)} project something like
+ %pre= "This is related to ##{issue.id}. @#{current_user.name} is working on solving it."
+ %p becomes
+ = markdown "This is related to ##{issue.id}. @#{current_user.name} is working on solving it."
+
+
+
+ .span4.right
+ .alert.alert-info
+ %p
+ If you're not already familiar with Markdown, you should spend 15 minutes and go over the excellent
+ %strong= link_to "Markdown Syntax Guide", "http://daringfireball.net/projects/markdown/syntax"
+ at Daring Fireball.
diff --git a/app/views/issues/_form.html.haml b/app/views/issues/_form.html.haml
index 1b67eabd5a5..65bf605a038 100644
--- a/app/views/issues/_form.html.haml
+++ b/app/views/issues/_form.html.haml
@@ -38,7 +38,7 @@
= f.label :description, "Details"
.input
= f.text_area :description, maxlength: 2000, class: "xxlarge", rows: 14
- %p.hint Markdown is enabled.
+ %p.hint Issues are parsed with #{link_to "Gitlab Flavored Markdown", help_markdown_path, target: '_blank'}.
.actions
diff --git a/app/views/milestones/_form.html.haml b/app/views/milestones/_form.html.haml
index 1cd08ac3bcf..49200c6705f 100644
--- a/app/views/milestones/_form.html.haml
+++ b/app/views/milestones/_form.html.haml
@@ -22,7 +22,7 @@
= f.label :description, "Description", class: "control-label"
.controls
= f.text_area :description, maxlength: 2000, class: "input-xlarge", rows: 10
- %p.hint Markdown is enabled.
+ %p.hint Milestones are parsed with #{link_to "Gitlab Flavored Markdown", help_markdown_path, target: '_blank'}.
.span6
.control-group
= f.label :due_date, "Due Date", class: "control-label"
diff --git a/app/views/notes/_form.html.haml b/app/views/notes/_form.html.haml
index dac026bd23d..326f1add485 100644
--- a/app/views/notes/_form.html.haml
+++ b/app/views/notes/_form.html.haml
@@ -9,10 +9,9 @@
= f.hidden_field :noteable_type
= f.text_area :note, size: 255
#preview-note.well.hide
- %p.hint
- = link_to "Gitlab Markdown", help_markdown_path, target: '_blank'
- is enabled.
+ .hint
= link_to 'Preview', preview_project_notes_path(@project), id: 'preview-link'
+ .right Comments are parsed with #{link_to "Gitlab Flavored Markdown", help_markdown_path, target: '_blank'}.
.row.note_advanced_opts.hide
.span2
diff --git a/app/views/wikis/_form.html.haml b/app/views/wikis/_form.html.haml
index 6b6411be55b..305607d4118 100644
--- a/app/views/wikis/_form.html.haml
+++ b/app/views/wikis/_form.html.haml
@@ -14,9 +14,10 @@
.middle_box_content
.input
%span.cgray
- Wiki content is parsed with #{link_to "Markdown", "http://en.wikipedia.org/wiki/Markdown"}.
- To add link to new page you can just type
+ Wiki content is parsed with #{link_to "Gitlab Flavored Markdown", help_markdown_path, target: '_blank'}.
+ To link to a (new) page you can just type
%code [Link Title](page-slug)
+ \.
.bottom_box_content
= f.label :content