UX Case Study: Markdown Heading
Tags: markdown, ux, uxdesign
Published: 2024-04-27 09:11:23

To create a heading in [Markdown](https://en.wikipedia.org/wiki/Markdown), at the start of a line, you put a hash character **#** followed by a space:

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lgyt79878egp2uok4u1q.gif)

To create a second level heading, you put two hash characters, and so on:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/c2x3u5fwg5x44yhypw57.gif)



OK, all that's good to know, I guess. But so far I only see a bunch of weird characters floating around my texts that I was told would format them in a certain way. But I don't _actually see_ them.


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/df7f2zvj0wz1j2zfezwq.png)



Now, one way of showing them as what they really are is by highlighting the Markdown syntax characters **#** and **\***:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/t3gdbem22hn1jq9smy4c.png)



Now I can _see_ my italic text being...italic, but I still don't _see_ my H1 heading. Surely it can't be the same size as my body text, right?

Well, ..._drum roll..._

It's the split-pane!


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/bhd6k3znymh8vx3h1keo.gif)



With split-pane, I can finally see my big phat H1 heading!

Split-pane was(and is) everywhere:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5fe6zcjopwh56cy6a3b9.png)([Dillinger editor](https://dillinger.io/))



![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lq7kt0ors9mmzbnbezqc.png)([iA Writer](https://ia.net/writer/))



![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/q8kmp6cbnpwp2z2jbxhu.png)([Inkdrop](https://www.inkdrop.app/))



![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ulpl5alcoyh90lp4tcnh.png)(VSCode)


However, under this setup, I would have to shift my attention, from my editor on the left side, to the split-pane on the right side, and again. This would be exhausting.

What if we got rid of the split-pane, but we still could preview our stuff as we write? Sure we can!

A step in that direction can be seen in [TOAST UI editor](https://ui.toast.com/tui-editor):


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9mk63xb61rsosm3nspkq.gif)




![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/a6xwghz1pq7ovwznf2wc.gif)(Inkdrop)


You can literally add or delete the hash characters to get to your desired level of heading. And the coolest part is: you can see the heading's size adjusts right there in real-time!


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3rljigceq60pgdkqwt9f.gif)



Very nice!

Some editors don't seem to take this real-time visual feedback all the way though. Examples below show the italic text in the heading is formatted in the editor in real-time, but not the heading itself:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/kpiietddoj8lzjl6ew19.gif)(iA Writer)



![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ml69tt3ai0k5gf5hsex0.gif)(Notable)


Anyway, I can't help but notice the Markdown syntax characters **#** and **\*** are still sticking out even though technically we are already in preview mode while we write. In other words, we are not exactly WYSIWYG yet.

Now, let's take a look at a few editors that might take us there: writing Markdown in a strictly WYSIWYG fashion without a split-pane.

Here is how [Notion](https://www.notion.so) do it:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/bx6omvhexlumajpxphak.gif)



No more **#** and **\*** sticking out! We are finally in the realm of WYSIWYG!

Same thing in Atlassian's [Confluence](https://www.atlassian.com/software/confluence):


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/aiuzfqx8mo0hjdhuo47h.gif)



In both of them, users can easily create headings and italic texts by entering their respective Markdown syntax characters. This is a user flow and a mental model we have been accustomed to in every editor that's mentioned here so far.

But here is the thing: when it comes to editing, users are forced to switch to an entirely different flow and mental model.

For example, to change a heading's level in Notion, you have to double click to select a text in order to bring up a floating toolbar where you will find and select the type of heading you want:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/d9fgiw6r1cxg5eahcd3v.gif)



Similarly, in Confluence:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6njs9mcjl7v121m46ypr.gif)



Sure, keyboard shortcuts are available. But they are also an opposing user flow and mental model. They can complement the main flow but not replace it.

At this point, we can form a first principle for a Markdown editor: adding and deleting Markdown syntax characters is each a cause-and-effect that's inextricably linked to each other.

We can observe this principle in the split-pane world:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6hquc95gfpiz10ll9kc0.gif)



Entering and deleting characters has been a part and parcel in online writing and editing since the advent of personal computing. If it's possible to enter certain characters to create certain UI element, it should be possible as well to do the reverse - editing the characters that you have entered - to edit the said UI element.

As of this writing, there are only a handful of editors that seem to follow this principle. Let's take a look.

[Marktext](https://github.com/marktext/marktext) editor:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jgru4jya3fh4q2crr6ed.gif)



But the principle doesn't apply to the heading which can only be changed with keyboard shortcuts.

Here is [Typora](https://typora.io/) editor:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ezrpvewnwcp6hphrlwtf.gif)



Unlike the italic text, users don't get instant visual feedback when creating heading. And like Marktext, editing heading can be done only with keyboard shortcuts.

The closest editor that follows our first principle is [Obsidian](https://obsidian.md/) editor:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/onppkxu6g16i82xhza1t.gif)



That's what I'm talking about!

A minor thing to point out there is the body text becomes italic too when you delete the closing asterisk of the italic text in the heading.

And finally here is a [Markdown editor](https://zuunote.com) I'm working on:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/uyfxna8on4nuy27q013d.gif)



## Conclusion

All modern Markdown editors allow us to adopt a user flow and a mental model in which we can enter Markdown syntax to create UI elements such as headings and italic text. But, in almost all of them, the reverse is not possible - to edit the UI elements, you are forced to adopt an entirely different flow and model.

This post was a journey in search of my ideal editor: a place where visual feedback is immediate from an action as singular as entering and removing a character, and a place where you can see, and feel, every pulse of your written thoughts.