Discussion: Markdown comment editor should not auto-format text as we type

[Weikardzaena]

TL;DR

Automatic formatting applied to plain-text Markdown editing is a trend in the wrong direction. Leave automatic formatting to a WYSIWYG editor, and remove the automatic formatting from the Markdown editor. Mashing WYSIWYG behavior into plain-text editing at best creates confusion, and at worst it creates frustration.

Intro

After using GitHub for years now, I have noticed a couple of small changes to the comment editor in the recent months that I think are trending in the wrong direction from a UX perspective.

The GitHub comment editor is -- at its core -- a plain-text editor which supports Markdown. There is no support for true rich text/WYSIWYG functionality. Even the helpful UI buttons above the editor don't do anything other than insert Markdown-formatted text where your cursor is.

Recently, however, it seems the editor is trying to act more like a rich text editor by automatically formatting plain text while the user types. I don't think this is a good design choice, and the prime example of why I think so follows below.

Numbered Lists

The Current Behavior

When you type 1. Something <RETURN> the editor automatically puts in a 2. on the next line and positions your cursor such that you can quickly enter a numbered list of items. This is akin to expected behavior of modern WYSIWYG editors you find all over the web.

The Issue

What I personally run into a lot is I make a list of items, but then I want to insert/delete an item into the middle of the list:

1. Foo
2. Bar
       <-- Try to add an item here
3. Baz
4. Hello
5. World

Because the editor is just adding in plain text numbering with no sort of backing data structure to automatically update the list, I am now forced to update every single item's numbering after the insertion/deletion point.

Discussion

The above example is the most obvious, but there are other auto-formatting behaviors too. For instance, bullets - are automatically inserted after pressing <RETURN>. This seems fine on paper, but to me this sets a concerning precedent where automatic alterations to a plain-text editor create unexpected behavior for the user.

Fighting Against the User

To me, these features degrade the experience of users who are trying to write in Markdown. Markdown was designed to enable ASCII / UTF-8 en-us characters to write formatted text with minimal syntax. To have a Markdown editor break away from basic Markdown syntax creates -- at best -- a confusing experience, and at worst it actively works against the user who is trying to type in Markdown, as seen above.

I say "confusing" because there are many people who use this website -- and other sites with Markdown support -- who will not be expecting this behavior. Automatic text formatting is to be found in rich text/WYSIWYG editors, and websites often give you the choice to use either the Markdown editor or the rich text editor. The latter usually supports a user experience more akin to typesetting applications like Microsoft Word, and the former leaves the formatting completely up to the user. There are pros and cons of both, and at the end of the day, whichever you use is a personal choice.

On the Merits of WYSIWYG

Just to be clear, I am not advocating against automatic text formatting in general.

WYSIWYG editing is powerful when implemented correctly. It saves the user a lot of time and effort by automatically formatting the text for you as you type, and -- most importantly -- it shows you exactly how it will look when rendered on a website before you submit it. Many people don't want to learn the syntax of a plain-text-only formatting standard just to (for instance) add bolded text to their content.

If it would make GitHub more accessible to more users, I welcome the addition of a WYSIWYG editor for comments. The key here is addition.

Is it Markdown or WYSIWYG?

All of this is to illustrate a point:

Markdown and WYSIWYG are two different things, and they should stay separate.

Automatically typesetting and formatting text is behavior found in a WYSIWYG editor. Letting the user have full control over the formatting and text input is what Markdown provides. Trying to take pieces of one and implement them in the other is nothing more than an arbitrary deviation from two distinct and well-known controls. It creates a sort of Frankenstein's Monster of functionality that is unique to GitHub, and I don't see the long-term benefit for it.

Conclusion

This post began with an example of a piece of functionality that I don't like and I think should be removed, but the long-term implications of this trend are what I wanted to address by writing all of this. What I concerns me is that arbitrary pieces of WYSIWYG functionality will be mashed into the Markdown editor, confusing both those who like automatic text formatting and those who prefer plain-text editing.

Something that tries to be good at many different things is never very good at any one thing, and I think that applies to these changes we're seeing to the Markdown editor in GitHub.

P.S.

Really, what triggered this post was me getting very annoyed at the automatic formatting of numbered lists in the comment editor because it creates more work for me to redo the list numbering if I insert or delete an item. If nothing else comes out of this discussion, please remove that feature. At the very least, change it to not auto-increment the numbers since Markdown rendering will format that anyway.

Thank you.

[erikr]

Agreed!

Related: I prefer to type numbered lists with all 1. s so I can rearrange lines, yet still render an appropriately numbered list, e.g.

1. content here
1. content here

However, when I hit return, this happens:

1. content here
1. content here
2. 

Expected and superior behavior would be:
However, when I hit return, this happens:

1. content here
1. content here
1. 

[vorburger]

#39057 created as a new more narrow and specific request focused on (only) this. (I've actually opened a ticket to GitHub support about it, and they replied suggesting to do this, quote: "We invite you to share your feedback in our official GitHub community discussions repositor, or by replying to the existing discussion you've already linked.")

[per1234]

I very much agree. I use lists a lot and I am constantly fighting this "feature". Not only for numbered lists, but for unordered and task lists. I simply don't see that having to add the minimal list markup manually or via the toolbar was a burden.

It seems to have been a change made simply for the sake of change. Done only because you could, rather than driven by the needs of the users. Exactly the sort of treatment I am accustomed to from Microsoft, but not at all what I expect from GitHub.

Please add an option to turn it off.

[steinybot]

One solution to this is to keep the current behaviour, at least for the second list item.

So typing:

1. a

Then pressing enter will result in:

1. a
2. 

However if this is changed to:

1. a
1. b 

Then pressing enter should result in:

1. a
1. b
1.  

So the algorithm should be:

• If there is only one item then pressing enter will insert the next number (as it works now),
• Otherwise compare the previous two items:
  • If the numbers are the same then insert that number again,
  • Otherwise insert the next number (as it works now)

[erikr]

Good idea

[moorepants]

I agree the auto lists are very frustrating and in almost every list I have to undo what the auto formatting does. Github also introduced this in February: https://github.blog/changelog/2022-02-02-paste-links-directly-in-markdown/ that auto formats copied text in the browser. This is also very frustrating and now I have to delete long urls and markdown formatting on pastes. If the text input boxes are for plain text, then no auto formatting should occur. Or there should be a configuration button for the user to disable auto formatting in Github text boxes for the entire website.

[vorburger]

FYI you can (now?) disable this on your https://github.com/settings/accessibility Editor settings URL paste behavior Formatted link ("Pasting a URL while having text selected will format to a Markdown link") VS Plain text ("Pasting a URL while having text selected will replace the text").

[moorepants]

Fantastic! Thanks for sharing.