CommonMark and Live Previews

Spec
1

Relevant part of the spec:

http://jgm.github.io/stmd/spec.html#emphasis-and-strong-emphasis

My biggest bugbear with the current implementations of markdown (beyond the lack of a spec) has been the interpretation of the rules around emphasis. Here’s the original spec:

Markdown treats asterisks (*) and underscores (_) as indicators of emphasis. Text wrapped with one * or _ will be wrapped with an HTML tag; double *’s or _’s will be wrapped with an HTML tag.

The original spec makes no mention of how spaces should be handled here, but clarifies further on with:

But if you surround an * or _ with spaces, it’ll be treated as a literal asterisk or underscore.

Therefore, implementations of Markdown treat spaces next to an emphasis delimiter as breaking emphasis and the new StandardMarkdown spec has clarified that this should be the case.

So examples 265 to 272 specifically declare that **this ** is not emphasis.

This means that if you’re typing between two emphasis delimiters into a live preview (like the one I’m writing in right now to type this post, or Ghost’s editor which I work on and all the others out there like StackEdit, EpicEditor, MouApp, MarkdownPad to name a few) then the live preview flickers between emphasis and no emphasis as you type a word, then a space, then a word, then a space. If you’re writing a large block of emphasized text, the preview can jump around (at Ghost we say: ‘like a monkey on crack’), providing a very uncomfortable user experience.

Split-Screen Markdown editors have become a very common, and perhaps unexpected use case since the original spec, and I think there is value in any Standard spec for markdown considering the extra requirements that this imposes on the syntax.

I realise that in order to gain adoption, this attempt to standardise needs to change as little as possible, but the original spec did not state that spaces should break emphasis, only that a single asterisk or underscore surrounded by spaces should be treated as the literal character.

These two rules definitely cause a conflict, but I think it’s worth investigating better ways to resolve the rules, rather than just having spaces kill all emphasis.

For example, *this * might not be emphasis, but why is **this ** also not emphasis? There is no asterisk surrounded by spaces. I imagine this has been done for consistency of behaviour between *, **, _ and __, which I think is sensible.

Another way to resolve this would be to keep 265-268 as not emphasis, but change 269-272 to be considered as emphasis. i.e. the closing delimiter CAN be proceeded by a space. The presence of an opening delimiter, which we know opens emphasis, can determine that the next delimiter closes emphasis regardless of whether it is proceeded by a space or not. If you need to put a delimiter inside the pair, then escaping can be used:

*Some text with \* in the middle *

This doesn’t really break either rule from the original spec, it only clarifies that the second rule:

But if you surround an * or _ with spaces, it’ll be treated as a literal asterisk or underscore.

Only applies if you haven’t already opened emphasis.

I realise that this is quite a big departure from the markdown implementations that are out there, and I am not sure if I’ve done enough to convince anyone that there’s value in this change, but I’d love to start a discussion around how markdown can better serve the now very common live previews.
6 Likes
2

+++ ErisDS [Sep 04 14 09:42 ]:

Another way to resolve this would be to keep 265-268 as not emphasis, but change 269-272 to be considered as emphasis. i.e. the closing delimiter CAN be proceeded by a space. The presence of an opening delimiter, which we know opens emphasis, can determine that the next delimiter closes emphasis regardless of whether it is proceeded by a space or not.

It’s very nice to be able to do

*A Treatise on Homer's *Iliad**

as you might get in a bibliography. Also, things like

*I'm emphasizing the * character*

These both read fairly unambiguously to a human, I think. I think
there’s MUCH to be said for the rule as it is (and in fact, this was one
of the most complex parts of the spec to work out in a satisfactory way;
we went through many iterations).

It seems to me that the flickering problem could perhaps be solved with
some clever programming?

3

Something along the lines of:

if cursor is before emphasis marker
    and they just typed a space
then
  delay the live preview update by 500ms

Seems like it could be satisfactory to me. @ErisDS what do you think of that?

2 Likes
4 
if cursor is before emphasis marker
    and they just typed a space
then
  delay the live preview update by 500ms

Rather than just delaying rendering by an arbitrary time, perhaps it’d be better to do something like

if cursor is before emphasis marker
    and they just typed a space
then
  delay the live preview update until the cursor moves outside the * *

In other words, wait until the input is unambiguous before updating the preview.

(FWIW, I modified my personal Ghost blog implementation to introduce a small delay before rendering anyway, as I think it improves the experience generally.)

1 Like
5

I wrote that under the assumption that the user would keep typing, and a non-space character would effectively undo the delay.