[Proposal] Live Preview tab for comment editor

[jackHay22]

Feature Description

The issue and PR comment editing UI should be redesigned to have a "Live Preview" WYSIWYG tab and a "Source" tab for raw markdown.

Reasoning

Since Gitea is in the process of redesigning this feature, it is a good time to carefully consider the user experience. I propose that we deviate from the Github interface. Their approach (a markdown tab and a preview tab) has various shortcomings from the perspective of user experience. For example, users must switch to the preview tab to view images. It would be better to view images inline by default but have the option to switch to pure markdown if desired. This would resemble tools like Slack and Obsidian which allow users to toggle whether markdown is shown in a live preview editor. The combination of a "Live Preview" tab and a "Source" tab will give users an improved editing experience as well as access to pure markdown. This is more intuitive than a partially rendered tab (like EasyMDE) and a fully rendered preview. Ideally, we would include a user setting for enabling or disabling this feature in favor of a native textarea.

Design Considerations

There are some important practical considerations to address. Primarily, the "Live Preview" tab will almost certainly need to be rendered by the client. Currently, markdown is rendered server-side when the user toggles to the preview tab. To avoid maintaining two parallel markdown implementations, we would need to render markdown on the client-side only and the WYSIWYG library would need support for non-interactive rendering. This would also ensure that the "Live Preview" rendered markdown matches the final rendered markdown in a published comment. We will want to use comprehensive testing to ensure the consistency of rendered markdown before and after this change.

Screenshots

No response

[delvh]

Well, my problem with this approach is the following:

WYSIWYG

Why was EasyMDE (and SimpleMDE before it) removed? The answer is simple: There's no such thing as an "easy and error-free" WYSIWYG editor. Furthermore, these editors aren't even perfect WYSIWYG but pseudo-WYSIWYG instead. All approaches there are error-prone with a myriad of possible issues. First of all, accessibility.

Why does GitHub not implement this? They probably haven't found a good implementation either. Why don't we implement it ourselves? Hard no. That's a maintenance burden that would basically kill the entire project. Unless you happen to find an error-free feature-complete WYSIWYG MD editor library, this proposal sounds as probable to me as dragons and unicorns. That's why I'm against it.

[silverwind]

Both GitHub and GitLab rely on a textarea because it is the only way to edit text on the web in an accessible manner that works everywhere, especially on mobile where WYSIWYG editors always break in interesting ways.

As a user, I like a textarea because it does not get in my way and it is predicable in behaviour, which is something that can not be said of the various WYSIWYG editors which all have their own "weird" behaviours because WYSIWYG text editing is a hard if not impossible problem to solve.

[wxiaoguang]

The good thing is now Gitea has the ability to switch editors. So if there is a better markdown editor, I think maybe the legacy EasyMDE could be replaced by a new one. Then the native textarea still works everywhere, and the new markdown editor could satisfy many users who like WYSIWYG.

[KN4CK3R]

From a developer point of view I dislike WYSIWYG because often not every feature the underlying language provides is implemented. So you end up with a mix of styled but unfunctional markup. Then it's not what I get what I see. The minimalistic "just markdown code" works better for me.

[jtran]

I'd like to give a little more context for the motivation as to why this proposal is being made.

As a developer, I prefer plaintext markdown for most things. I like GitHub's textarea UI. But there are times when writing a long issue or PR description that I need to flip back and forth between writing and previewing, which is not ideal.

There are also less tech-savvy users such as reviewers and other project stakeholders who aren't necessarily writing code, but who interact with issues and pull requests. These non-developer users look at markdown, see it as code, and they just can't handle it. This isn't my opinion; we regularly talk to users who complain about this. I've also seen a similar thing play out several times over the years, across several apps, where developers and their managers thought they could reduce work by allowing end users to edit a "human readable" format. It was always a point of friction with non-developers.

Non-developers also don't care about having the markdown format. Many benefits, like the fact that it can be mirrored in other platforms or copied and pasted to almost any other web editor, they have no interest in, are unaware of the benefits, or are unable to articulate it as a desire for a standard format. Thus, they see fewer downsides to WYSIWYG.

Don't shoot the messenger, i.e. me, for typing the above.

All that said, I never want to give up plaintext completely. When I use Slack, the first thing I do when I join a new community is disable the WYSIWYG editor, and I think many developers are the same. This is why the proposal contains the user setting, which is a critical piece, as the level of comfort with working with markdown is different for every person. It cannot be an instance-wide setting.

No one said it wouldn't be challenging. Mobile editing is important. It would need to recognize issue and PR links, @-mentions, task list checkboxes, and footnotes. It would need to render mermaid diagrams. And it's all client-side to reduce latency, increase privacy, and avoid having multiple implementations. This proposal is an attempt to set the vision for where we want to end up, not something that will happen overnight.

[KN4CK3R]

Related https://github.com/ckeditor/github-writer Related https://github.com/ckeditor/github-writer/issues?q=is%3Aissue+is%3Aopen+label%3Abug 😏

[silverwind]

The problem of maintaining two editors is that every feature needs to be implemented twice, hindering new feature development. That is why I'd like to remove EasyMDE in an upcoming release, likely for 1.21.

I do understand concerns from non-technical people who prefer WYSIWYG, but I don't see us realistically supporting it, at least not with all features that the textarea editor has and will have in the future.

[xan2622]

Respectfully, I think that some of the persons who replied to @jackHay22's post might have misunderstood his suggestion. I don't think what he meant is to replace easyMDE with another WYSIWYG text editor.

By "Live Preview", he probably meant to let the user type text in the simple textarea (like we currently do) while another area shows a live preview of the final message, pretty much similar to what Discourse forums feature:

Click the image to watch the demo video:

Here is a live demo if you want to test this live preview, located on the right side of their text editor: https://try.discourse.org/

---

IMO, the easyMDE text editor is redundant and should be removed. I share the same feeling as others about WYSIWYG text editors. I've never felt comfortable using them.

I prefer the current simple textarea + a few buttons above the textarea that everyone (developers and non-technical people) can use to quickly format their words/sentences + still the possibility to use the markdown syntax.

A live preview area, as suggested by @jackHay22 would be very convenient.

[delvh]

Agreed. That would also solve the problem of #30474. The only problem that would need to be tackled is how to avoid DDOSing the server with requests to preview the markdown on every single change. Probably something like send a request every <configurable timeout, default 2s or 3s> if something changed would be the best compromise both from a user and the server perspective.

[delvh]

Alternatively, but more complicated to implement:

send a request <x> ms after the user finished typing

[xan2622]

Agreed. That would also solve the problem of #30474. The only problem that would need to be tackled is how to avoid DDOSing the server with requests to preview the markdown on every single change.

As jackHay22 suggested in his original post, the "live preview" would most likely have to be rendered locally, mimicking what the final result will look like when the message is posted.

[delvh]

The problem with that is: That is an enormous maintenance burden. I don't think this burden is worth it. After all, from time to time, new features are added to the Markdown parser. I can foresee a lot of disconnects between the local parsing and the remote one. Additionally, even implementing a first draft will already be a huge amount of work in and of itself: For example, does the client then need any single language definition we support to adequately pre-render codeblocks?

There is a reason why we offer an API route to render markdown text.

[delvh]

The server based rendering would keep this feature down to perhaps a one-time 100 line change. Client based rendering is in my first estimate probably rather ~10000 lines minimum.