Adding a new format is not completely straightforward. We face many challenges:
- Continuation of the support of existing formats
- Conversion from one format to another
- UX clumssyness: having 3 formats for each textarea / comment makes the interface too fat
- Bring people to the new format. In 2020, most people (at least developers) expects to write markdown but if it's not the default they might falsly assume that the feature doesn't exist even if it is. We know by experience that the WYSIWYG use is not widespread because not by default.
In an ideal world there would be only one format supported for formatting messages, markdown and it would be possible to either have a wysiwyg editor that saves in markdown or to edit the markdown manually. That's the overall objective and we should aim to that. However, this story is a first step toward this objective.
In this story we will:
- Introduce the support of markdown in textarea, static rich text fields & follow-up comments as well as tracker "submit" and "edit" descriptions.
- Spike how the overall objective can be managed (wyiswyg markdown & related features).
Add support of markdown
No feature flag seems required as markdown is an improvement of text in 95% of the cases.
"Markdown" is used as label (instead of CommonMark). The documentation will refer to CommonMark for those who want the nifty details.
When Markdown is used, there is a small help with mostly used formatting preferences.
- Markdown (common mark flavor) is added in the list of supported formats in:
- Follow-up comments
- Textearea fields
- Steps fields
- test management comments (on executed test)
- Markdown is rendered in
- Artifact view
- All modals
- Card fields (cardwall, cardwall renderer, kanban)
- Test management
- There is a "Design Check" to ensure that the possibilities unlocked by markdown renders well
- Existing comments & textarea that are in text or HTML cannot be switch to markdown (yet)
- Existing comments that are in markdown cannot be converted to HTML or Text (yet)
-
REST API should prevent a breakage about unsupported format (first of in all Tuleap JS app) so:
- Format is advertised as HTML and the output associated is markdown rendered as HTML
- a new entry "additional info" is added with the format "commonmark" and the actual source.
Markdown replace text
- Wherever markdown can be used, the user can ask for a preview of the markdown she is editing (Mockups Required):
- Follow-up comments
- Textearea fields
- Steps fields
- test management comments
- "Text" format is no longer available for new comments & fields
- In user preferences, one can choose "markdown" as default format
- Users with "Text" preference are upgraded to Markdown
- Existing comments that are in "Text" format can stay text or switch to "Markdown" or "HTML"
- Existing conversion is fixed to deal with spaces & line break.
- As soon as another format is selected, it's no longer possible to switch back to "Text".
- If the conversion is not what user intended, there is a way to "Cancel" the conversion and revert to the original content in "Text".
- Existing comments that are in "HTML" can be converted to "Markdown"
- Existing comments that are in "Markdown" can be converted to "HTML"
- Via a rendering of Markdown to HTML
Complete markdown support in trackers
- Support of markdown is added in
- Static Rich Text Field (same REST API trick is required)
- Tracker header for Edition
- Tracker header for Submit
Efficient markdown
- Add support of drag'n drop or copy/paste of images inside markdown (as it's done for HTML counterpart)
- Spike CKEDITOR 5 (or another editor) support of markdown for wysiwyg