From 58a581782b99b55ea3d516dca8c63511c6fbe3f3 Mon Sep 17 00:00:00 2001 From: Riyad Preukschas Date: Fri, 24 Aug 2012 17:35:21 +0200 Subject: [PATCH 1/3] Update forms to show consistent link to GFM. --- app/assets/stylesheets/sections/notes.scss | 4 ++++ app/views/issues/_form.html.haml | 2 +- app/views/milestones/_form.html.haml | 2 +- app/views/notes/_form.html.haml | 5 ++--- app/views/wikis/_form.html.haml | 5 +++-- 5 files changed, 11 insertions(+), 7 deletions(-) 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/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 From 806695f491a8853a66d6dbde58b9e9d3eee1a72a Mon Sep 17 00:00:00 2001 From: Riyad Preukschas Date: Mon, 27 Aug 2012 21:20:13 +0200 Subject: [PATCH 2/3] Split and reformat markdown options and add refs to their docs. Also add hard_wrap option. --- app/helpers/gitlab_markdown_helper.rb | 29 +++++++++++++++++---------- 1 file changed, 18 insertions(+), 11 deletions(-) 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 From 1f1ce5fbd47a8a9966323caf6b5b59672c74007a Mon Sep 17 00:00:00 2001 From: Riyad Preukschas Date: Fri, 24 Aug 2012 17:44:47 +0200 Subject: [PATCH 3/3] Revamp GFM user docs. --- app/views/help/markdown.html.haml | 114 +++++++++++++++++++++++++----- 1 file changed, 97 insertions(+), 17 deletions(-) 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.