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

Improve GFM user docs

Merge pull request #1290 from riyad/improve-gfm-user-docs
Improve GFM user docs
Dmitriy Zaporozhets
2 parents 867f4607 1f1ce5fb
Showing 7 changed files with 126 additions and 35 deletions Show diff stats
app/assets/stylesheets/sections/notes.scss
app/helpers/gitlab_markdown_helper.rb
app/views/help/markdown.html.haml
app/views/issues/_form.html.haml
app/views/milestones/_form.html.haml
app/views/notes/_form.html.haml
app/views/wikis/_form.html.haml
@@ -38,6 +38,10 @@
   }
 }
+#preview-note {
+  margin-bottom: 0;
+}
+
 .note { 
   padding: 8px 0; 
   border-bottom: 1px solid #eee;
@@ -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
-- bash_lexer = Pygments::Lexer[:bash]
-%h3.page_title Gitlab Markdown
+%h3.page_title Gitlab Flavored Markdown
 .back_link
   = link_to help_path do 
     &larr; 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 <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 @@
           = 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
@@ -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"
@@ -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
@@ -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
1	-- bash_lexer = Pygments::Lexer[:bash]
2	-%h3.page_title Gitlab Markdown	1	+%h3.page_title Gitlab Flavored Markdown
3	.back_link	2	.back_link
4	= link_to help_path do	3	= link_to help_path do
5	← to index	4	← to index
6	%hr	5	%hr
7		6
8	-%p.slead We extend Markdown with some GITLAB specific syntax. It allows you to link to:	7	+.row
		8	+ .span8
		9	+ %p
		10	+ For Gitlab we developed something we call "Gitlab Flavored Markdown" (GFM).
		11	+ It extends the standard Markdown in a few significant ways adds some useful functionality.
9		12
10	-%ul
11	- %li issues (#123)
12	- %li merge request (!123)
13	- %li commits (1234567)
14	- %li team members (@foo)
15	- %li snippets ($123)	13	+ %p You can use GFM in:
		14	+ %ul
		15	+ %li commit messages
		16	+ %li comments
		17	+ %li wall posts
		18	+ %li issues
		19	+ %li merge requests
		20	+ %li milestones
		21	+ %li wiki pages
16		22
17	-%p.slead in	23	+ %h3 Differences from traditional Markdown
18		24
19	-%ul
20	- %li commit messages
21	- %li notes/comments/wall posts
22	- %li issues
23	- %li merge requests
24	- %li milestones
25	- %li wiki pages	25	+ %h4 Newlines
		26	+
		27	+ %p
		28	+ The biggest difference that GFM introduces is in the handling of linebreaks.
		29	+ 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.
		30	+ GFM treats newlines in paragraph-like content as real line breaks, which is probably what you intended.
		31	+
		32	+
		33	+ %p The next paragraph contains two phrases separated by a single newline character:
		34	+ %pre= "Roses are red\nViolets are blue"
		35	+ %p becomes
		36	+ = markdown "Roses are red\nViolets are blue"
		37	+
		38	+ %h4 Multiple underscores in words
		39	+
		40	+ %p
		41	+ 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.
		42	+ Therefore, GFM ignores multiple underscores in words.
		43	+
		44	+ %pre= "perform_complicated_task\ndo_this_and_do_that_and_another_thing"
		45	+ %p becomes
		46	+ = markdown "perform_complicated_task\ndo_this_and_do_that_and_another_thing"
		47	+
		48	+ %h4 URL autolinking
		49	+
		50	+ %p
		51	+ GFM will autolink standard URLs you copy and paste into your text.
		52	+ 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.
		53	+
		54	+ %h4 Fenced code blocks
		55	+
		56	+ %p
		57	+ Markdown converts text with four spaces at the front of each line to code blocks.
		58	+ GFM supports that, but we also support fenced blocks.
		59	+ Just wrap your code blocks in <code>```</code> and you won't need to indent manually to trigger a code block.
		60	+
		61	+ %pre= %Q{```ruby\nrequire 'redcarpet'\nmarkdown = Redcarpet.new("Hello World!")\nputs markdown.to_html\n```}
		62	+ %p becomes
		63	+ = markdown %Q{```ruby\nrequire 'redcarpet'\nmarkdown = Redcarpet.new("Hello World!")\nputs markdown.to_html\n```}
		64	+
		65	+ %h4 Special Gitlab references
		66	+
		67	+ %p
		68	+ GFM recognizes special references.
		69	+ You can easily reference e.g. a team member, an issue or a commit within a project.
		70	+ GFM will turn that reference into a link so you can navigate between them easily.
		71	+
		72	+ %p GFM will recognize the following references:
		73	+ %ul
		74	+ %li
		75	+ %code @foo
		76	+ for team members
		77	+ %li
		78	+ %code #123
		79	+ for issues
		80	+ %li
		81	+ %code !123
		82	+ for merge request
		83	+ %li
		84	+ %code $123
		85	+ for snippets
		86	+ %li
		87	+ %code 1234567
		88	+ for commits
		89	+
		90	+ -# this example will only be shown if the user has a project with at least one issue
		91	+ - if @project = current_user.projects.first
		92	+ - if issue = @project.issues.first
		93	+ %p For example in your #{link_to @project.name, project_path(@project)} project something like
		94	+ %pre= "This is related to ##{issue.id}. @#{current_user.name} is working on solving it."
		95	+ %p becomes
		96	+ = markdown "This is related to ##{issue.id}. @#{current_user.name} is working on solving it."
		97	+
		98	+
		99	+
		100	+ .span4.right
		101	+ .alert.alert-info
		102	+ %p
		103	+ If you're not already familiar with Markdown, you should spend 15 minutes and go over the excellent
		104	+ %strong= link_to "Markdown Syntax Guide", "http://daringfireball.net/projects/markdown/syntax"
		105	+ at Daring Fireball.
	@@ -38,7 +38,7 @@		@@ -38,7 +38,7 @@
38	= f.label :description, "Details"	38	= f.label :description, "Details"
39	.input	39	.input
40	= f.text_area :description, maxlength: 2000, class: "xxlarge", rows: 14	40	= f.text_area :description, maxlength: 2000, class: "xxlarge", rows: 14
41	- %p.hint Markdown is enabled.	41	+ %p.hint Issues are parsed with #{link_to "Gitlab Flavored Markdown", help_markdown_path, target: '_blank'}.
42		42
43		43
44	.actions	44	.actions
	@@ -22,7 +22,7 @@		@@ -22,7 +22,7 @@
22	= f.label :description, "Description", class: "control-label"	22	= f.label :description, "Description", class: "control-label"
23	.controls	23	.controls
24	= f.text_area :description, maxlength: 2000, class: "input-xlarge", rows: 10	24	= f.text_area :description, maxlength: 2000, class: "input-xlarge", rows: 10
25	- %p.hint Markdown is enabled.	25	+ %p.hint Milestones are parsed with #{link_to "Gitlab Flavored Markdown", help_markdown_path, target: '_blank'}.
26	.span6	26	.span6
27	.control-group	27	.control-group
28	= f.label :due_date, "Due Date", class: "control-label"	28	= f.label :due_date, "Due Date", class: "control-label"