One of the biggest frustrations in using what you see is what you get (WYSIWYG) editors when coming from knowing Markdown is how they deal with inline code. This is something that I do very often in writing technical documents, and in Markdown this is super easy, you simply wrap a word in back-ticks (e.g. `code`). In many ways, the other “marks”, like bold, italic, underline are all easier in applications like Word, Google Docs, Notion, Confluence, etc. because almost everyone knows the shortcut to make something stop being bold/italic/underlined. This is not the case for inline code, which are similar but no one knows the shortcut to stop something from looking like code. Additionally, every editor application does something subtly different.
This is frustrating to no end.
If you are using Slack or Notion, try creating a code block and then adding something to the start or end after it is created. The behaviour is completely unintuitive, you have no idea if the next character you type will be inside or outside of the code-mark, and in Notion, for example, this changes based on if you hit backspace.
Figure 1:Will the next character you type be inside or outside the code-mark? Are you feeling lucky?!
In Slack, if you start a message with code, there is literally no way to exit the code at the start without using your mouse, deleting the code-mark completely, or knowing the keyboard shortcut. In Slack, the right arrow key also mysteriously turns into a spacebar at the end of the code-mark or feels like it skips one character ahead.
Figure 2:Editing a code-mark in Slack will mean you have to get out your mouse.
The ambiguity of whether the next thing that you type will be “marked” is something that we tolerate for bold/italics/underline — because we all know the escape hatch and don’t have to leave our keyboards. But if you learn the keyboard shortcut for code in Slack, you might be surprised when you use it in Notion that the developer tools in Chrome pop up. Or say you learn the shortcut in Confluence, and jump over to Slack you will open your Mentions — in Notion, it creates a comment! Notion as far as I can tell, doesn’t even have a shortcut for a code-mark.
There are so many other quirks in these applications with regard to how the spacebar, or arrow-keys work, how to deal with one-character of code. I have yet to see a WYSIWYG editor actually do it “right”. Our goal at Curvenote is to make a best-in-class editing experience for technical content, and these are the types of details you either never notice because it just works, or they make people tear their hair out.
Can you make this a good experience?!¶
I have tested 20 or so WYSIWYG editors to excruciating detail in this area, but each of these details I have been surprised at in using them in real, non-contrived settings. In the following analysis, I am just showing Notion, Slack, Confluence, and Curvenote, many other editors fall into these same traps. I have included little diagrams to show where a cursor (|) is and whether the next character you type will be “marked” `code|`, or be “unmarked” `code`|. If you have one of these editors open, try to play along and get annoyed with me!
Inline Code Creation¶
Can create code with markdown syntax while typing! `code| → `code`|
- Notion: ✅, Slack: ✅, Confluence: ✅, Curvenote: ✅
Can create code with markdown syntax, in reverse order (e.g. last, then first): code`| → `|code`
- Notion: 😵, Slack: ✅, Confluence: 😵, Curvenote: ✅
Entering and Exiting a Code Mark¶
You can exit a code mark at the end of a line using the RIGHT arrow key: `code|` → `code`|
- Notion: 😵, Slack: ✅, Confluence: ✅, Curvenote: ✅
- Slack has (seemingly) different behaviour if you are at the end of the line or not 🙁 turning your arrow key into a spacebar for some reason, but we will give it to them.
You can exit a code mark easily using the LEFT arrow key: `|code` → |`code`
- Notion: 😵, Slack: 😵, Confluence: ✅, Curvenote: ✅
You can exit a code mark easily using the left arrow key even at the start of a line:
- Notion: 😵, Slack: 😵, Confluence: 😵, Curvenote: ✅
Never insert a space when you press an arrow key to visually cheat above: `code`| vs `code` |
- Notion: ✅, Slack: 😵, Confluence: ✅, Curvenote: ✅
Don’t use the spacebar to sometimes exit the code mark:`code|` → `code |`
- Notion: 😵, Slack: ✅, Confluence: ✅, Curvenote: ✅
You should be always be able to use arrow modifiers to jump between words, select words, and/or jump to the start/end of the line. (i.e. ctrl-a/e, cmd-left/right, cmd-shift-left/right, alt-left/right)
- Notion: ✅, Slack: ✅, Confluence: 😵, Curvenote: ✅
- Confluence takes over the arrow key functionality if you are directly before/after a code-mark, and does special, unexpected things.
No Surprises for Next Character Insertion¶
You should be able to visually see if the next character that you type will be inside or outside of the code mark: `code|` vs `code`|, this should happen on both sides of the code, essentially pretending that it is wrapped in backticks.
Color
- Notion: 😵, Slack: ✅, Confluence: 😵, Curvenote: ✅
Position:
- Notion: 😵, Slack: 🤔, Confluence: 🤔, Curvenote: ✅
- Confluence did do this in 2019, but has regressed when testing their editor in 2021, which honestly is even more confusing.
- Slack gets half marks here because it almost always do what you expect, but try putting an explanation mark after
code!
For those keeping arbitrary score on this minuscule detail:
- Notion: 3/10
- Slack: 6.5/10
- Confluence: 5.2/10
- Curvenote: 💯 🎉 🥳
There are plenty of other details that we need to polish on the Curvenote editor, but on this one thing, I think it is best in class. I am hoping for the sake of writing technical content on the internet, that by discussing this, creating a requirements list, and open-sourcing our solution — maybe these other editors will up their game in this area! These are some of the things that give WYSIWYG a bad-taste and make them frustrating to use when doing the simplest tiny things.
Related Posts
Other resources from Curvenote
A panel discussion with Lorena Barba, Rowan Cockett, Karthik Ram and Arfon Smith explores how open source software practices can reshape the way we communicate scientific discoveries. Adopting open source tools and processes could drastically improve scientific communication, especially with the growing complexity and interconnectedness of research data.
The ability to build upon existing knowledge is fundamental to the process of science. Yet, despite the rapid advancement of science, the methods for citing and referencing content have remained surprisingly static. Curvenote is introducing new tools in MyST Markdown to create rich references and embed open-access content.
Introducing a lightweight templating engine, jtex, that provides a simple command line interface (CLI).
At JupyterCon 2020 we introduce Curvenote, allowing you to sync content between Jupyter Notebooks and a web-based, collaborative document editor.
In today's fast-paced scientific environment, the gap between code development and scholarly communication is widening. While scientists increasingly rely on code for analysis and modeling, traditional methods of sharing results—like static PDFs—fail to capture the dynamic and interactive nature of modern research.
At FORCE11 2024 Curvenote presented on our vision of Continuous Science, where the principles of continuous integration and deployment, well-known in software development, can be applied to scientific publishing to improve speed, reproducibility, and feedback loops.
