Commit 04b2864b authored by Dmitriy Zaporozhets's avatar Dmitriy Zaporozhets

Merge pull request #1290 from riyad/improve-gfm-user-docs

Improve GFM user docs
parents 867f4607 1f1ce5fb
...@@ -38,6 +38,10 @@ ...@@ -38,6 +38,10 @@
} }
} }
#preview-note {
margin-bottom: 0;
}
.note { .note {
padding: 8px 0; padding: 8px 0;
border-bottom: 1px solid #eee; border-bottom: 1px solid #eee;
......
...@@ -54,17 +54,24 @@ module GitlabMarkdownHelper ...@@ -54,17 +54,24 @@ module GitlabMarkdownHelper
end end
def markdown(text) def markdown(text)
@__renderer ||= Redcarpet::Markdown.new(Redcarpet::Render::GitlabHTML.new(self, filter_html: true, with_toc_data: true), { unless @markdown
no_intra_emphasis: true, gitlab_renderer = Redcarpet::Render::GitlabHTML.new(self,
tables: true, # see https://github.com/vmg/redcarpet#darling-i-packed-you-a-couple-renderers-for-lunch-
fenced_code_blocks: true, filter_html: true,
autolink: true, with_toc_data: true,
strikethrough: true, hard_wrap: true)
lax_html_blocks: true, @markdown ||= Redcarpet::Markdown.new(gitlab_renderer,
space_after_headers: true, # see https://github.com/vmg/redcarpet#and-its-like-really-simple-to-use
superscript: 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)
end
@__renderer.render(text).html_safe @markdown.render(text).html_safe
end end
end end
- bash_lexer = Pygments::Lexer[:bash] %h3.page_title Gitlab Flavored Markdown
%h3.page_title Gitlab Markdown
.back_link .back_link
= link_to help_path do = link_to help_path do
← to index ← to index
%hr %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 %p You can use GFM in:
%li issues (#123) %ul
%li merge request (!123) %li commit messages
%li commits (1234567) %li comments
%li team members (@foo) %li wall posts
%li snippets ($123) %li issues
%li merge requests
%li milestones
%li wiki pages
%p.slead in %h3 Differences from traditional Markdown
%ul %h4 Newlines
%li commit messages
%li notes/comments/wall posts %p
%li issues The biggest difference that GFM introduces is in the handling of linebreaks.
%li merge requests 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.
%li milestones GFM treats newlines in paragraph-like content as real line breaks, which is probably what you intended.
%li wiki pages
%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 <em>part</em> 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 <code>```</code> 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.
...@@ -38,7 +38,7 @@ ...@@ -38,7 +38,7 @@
= f.label :description, "Details" = f.label :description, "Details"
.input .input
= f.text_area :description, maxlength: 2000, class: "xxlarge", rows: 14 = 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 .actions
......
...@@ -22,7 +22,7 @@ ...@@ -22,7 +22,7 @@
= f.label :description, "Description", class: "control-label" = f.label :description, "Description", class: "control-label"
.controls .controls
= f.text_area :description, maxlength: 2000, class: "input-xlarge", rows: 10 = 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 .span6
.control-group .control-group
= f.label :due_date, "Due Date", class: "control-label" = f.label :due_date, "Due Date", class: "control-label"
......
...@@ -9,10 +9,9 @@ ...@@ -9,10 +9,9 @@
= f.hidden_field :noteable_type = f.hidden_field :noteable_type
= f.text_area :note, size: 255 = f.text_area :note, size: 255
#preview-note.well.hide #preview-note.well.hide
%p.hint .hint
= link_to "Gitlab Markdown", help_markdown_path, target: '_blank'
is enabled.
= link_to 'Preview', preview_project_notes_path(@project), id: 'preview-link' = 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 .row.note_advanced_opts.hide
.span2 .span2
......
...@@ -14,9 +14,10 @@ ...@@ -14,9 +14,10 @@
.middle_box_content .middle_box_content
.input .input
%span.cgray %span.cgray
Wiki content is parsed with #{link_to "Markdown", "http://en.wikipedia.org/wiki/Markdown"}. Wiki content is parsed with #{link_to "Gitlab Flavored Markdown", help_markdown_path, target: '_blank'}.
To add link to new page you can just type To link to a (new) page you can just type
%code [Link Title](page-slug) %code [Link Title](page-slug)
\.
.bottom_box_content .bottom_box_content
= f.label :content = f.label :content
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment