gitlabhq/gitlabhq — pull request #6356 by cirosantilli (2014-02-19 16:27:00+00:00)
Title: Add markdown preview to issue, MR and milestone descriptions.

Fixes both feedbacks [5409046](http://feedback.gitlab.com/forums/176466-general/suggestions/5409046-markdown-preview-for-creating-issues) and [5209446](http://feedback.gitlab.com/forums/176466-general/suggestions/5209446-markdown-preview-on-merge-requests).

Before this MR, markdown could only be previewed on notes (comments on issues, MR, MR diff notes, commits, snippets).

Now it can also be previewed for descriptions at creation and edit of:

- issues
- merge requests
- milestones

It is still *not* possible to preview it for:

- wiki (gfm / rdoc)
- readme / blob (any format possible)

since in those cases the situation is a bit more complicated because there can be multiple possible formats of input markup, so I decided then to leave those for a future MR.

As a reference to what is feasible, GitHub only has a single wiki format, and handles file previews somewhat intelligently based on extension.

For the custom merge request commit messages, see doubts below.

**Screenshots**

The preview button is disabled if the input is empty:

![screenshot from 2014-02-18 14 29 10 button deactivate](https://f.cloud.github.com/assets/1429315/2208499/896629a6-9980-11e3-8835-e519a8d9ff93.png)

In the past, it was invisible, but I felt this behavior was better because:

- it matches that of the submit button
- you always know where the button is, so it is less surprising

Input not empty:

![screenshot from 2014-02-14 12 05 23 issue before preview](https://f.cloud.github.com/assets/1429315/2208391/87cac530-997f-11e3-9fb4-547da252955a.png)

New issue preview:

![screenshot from 2014-02-14 15 06 11 issue preview](https://f.cloud.github.com/assets/1429315/2208394/9269abf0-997f-11e3-82f9-f957c38c83f3.png)

Header anchors appear only if the displayed markdown will have them also.

The situation is exactly analogous for MR and Milestone descriptions.

Comments and diff notes preview behave like before, but their style now matches that of the description inputs:

![screenshot from 2014-02-14 15 16 05 comment and diff comment](https://f.cloud.github.com/assets/1429315/2208516/c7cfc04e-9980-11e3-9e8c-085130fd8140.png)

![screenshot from 2014-02-14 15 13 51 diff note](https://f.cloud.github.com/assets/1429315/2208517/cfbf4964-9980-11e3-94b0-3d70fd488f75.png)

The preview for comments has no header anchors.

**Doubts**

1) Where should I put the default `.gfm-input-and-preview` CSS? For now I left it at `generic/forms` for lack of better place, but I also see the following possibilities:

- `common`
- `typography`
- a new file named `generic/markup-preview` or something

2) On `stylesheets/generic/forms.scss`, I had to add the lines:

background-color: white;
border: 1px solid rgb(204, 204, 204);
border-radius: 4px;
color: rgb(51, 51, 51);

whose only objective is to restore the default format set by Twitter Bootstrap for site when inside other divs.

For example, inside the green merge request div the preview would be green.

How to do that without resetting every single property manually?

I asked it on [StackOverflow]( http://stackoverflow.com/questions/21764595/restore-bootstrap-defaults-in-div) to no avail so far.

3) Shall I document the markdown rendering as part of the REST API? [GitHub does](https://developer.github.com/v3/markdown/).

If yes, what should be the response status in case of invalid values, e.g. `tru` instead of `true`? Microsoft says 400:

4) should we preview merge request custom commit messages or not? Shall we make them render exactly like issue descriptions, or not?

Reasons for no:

- the first line is special as it is the title line, and will be rendered in the commit message box with a different highlighted style

- the following lines are rendered on a different format, that uses only some features of markdow such as `@user`, but not most of the features such as lists and headers, as shown on the screenshot below.

Reasons for yes:

- parts of markdown are rendered (the @user on the screenshot below)

I suggest that in a future MR that we make a separate input box for the title (first commit line), as this might allow to preview properly, and indicate the the different 52 char limit more easily for the first line.

5) What is the correct place to put integration tests, `spec/features`, `features`, or both are OK?

Having both is bad because it requires developers to look into both to see it tests already exist or not.

**Implementation notes**

1) The functionality was essentially extracted from the existing notes preview under `javacripts/notes.js` and `view/project/notes/_form.html.haml`, encapsulated into `javascripts/markup_preview.js` and `views/shared/_markup_input_and_preview.html.haml`, and used uniformly on all implemented previews.

2) Removed `.js-notify-commit-author` CSS class since it is not used in any view anymore.

3) Removed duplicate of method `setupNoteForm`, which was absolutely identical to the other one once `js-notify-commit-author` was removed.

4) Extracted `GitLab.GfmAutoComplete.setup()` from `setupNoteForm` into `setupDiscussionNoteForm`, since it was only being called from two places:

- `setupMainTargetNoteForm`, which is only called once for the page, call which will be made by the extracted `new MarkupPreview` call.
- `setupDiscussionNoteForm`, to where it was extracted.

5) Removed class `js-gfm-input` from:

- group create and edit forms on group and admin pages
- wall
- merge request edit commit message, since it is not possible to preview it, and it does not really render like normal gfm.

since those inputs are currently never rendered as markdown.

Removed `.note_text_and_preview` CSS class from wall since it has *no* preview. This was the last occurrence of that class, so removed it from existence and ported its style from `notes.css` to `wall.css` with new name `new-wall-note`. The appearance and behavior of the wall are untouched.

6) Modified `_commit_box_html.haml` to use the `markdown` method instead of `gfm`, like every other place that renders markdown.

7) Modified file view to use a single technique for the reserved space for the header anchor links: `.wiki` inside a container with padding.

8) Renamed `no_header_anchors` option to `header_anchors`.

9) Corrected some always passing tests which assumed that `visible: false` does not target visible elements: it actually targets both visible *and* invisible elements: . Those tests need `should_not visible:true` instead.