#heading Not working

Just FYI this came up today on bbs.boingboing.org@jgm your decision was correct here, in the sense that it removes a common (and increasing thanks to Twitter) point of confusion:

4 Likes

Thanks for clarifying. :slight_smile:

I would like to bring this back up for reconsideration.

I am currently testing CommonMark on a fairly big body of existing documents, specifically questions and answers on Meta Stack Exchange. Requiring the space after the # impacts about 1.5% out of the 200,000 tested posts (and in those impacted posts, an average of about two ATX headers).

I consider this a pretty big impact, given CommonMark’s declared goal of as much backwards compatibility as possible.

Regarding the relevant discussion in the spec: Whether the original ATX required the space or not doesn’t seem to matter much given that almost no Markdown implementation except for CommonMark does. The “#5 bolt” argument in the spec is also rather small, I’d say, especially considering that a very similar argument in the original Markdown “spec” regarding numbered lists was explicitly discarded for CommonMark.

I can somewhat see the point about hashtags, but I have to wonder how often a hashtag would appear at the beginning of a line, and whether that warrants breaking a huge amount of existing posts and existing Markdown users’ flows.

Quoting a user’s comment on the matter,

It’s not the old posts but old posters’ habits that have to be changed. The ATX headers change (space after #) was the first behavioral barrier for me when I started using CommonMark-based renderers. A bit of unlearning is in order, I’m afraid.

3 Likes

1.5% would warrant a sed replacement and be done with that IMHO.

Yeah, you can fix up old documents fairly easily, that’s not my concern. It’s about the fact that the space being optional is obviously a feature that gets used a lot.

Once the people using it notice it does not work it the problem disappears by itself.

@balpha, you are right that this usage (no space after ATX header tags) is fairly common. I have seen it a lot. I think it is supported by most renderers not because it’s a good idea, but because Markdown.pl happened to allow it.

I find this a hard issue. I could be persuaded to allow #Ugly headers, probably. I know that the issue with hashtags has come up on the pandoc list, and @codinghorror has another example above where it came up. Of course, with commonmark’s behavior people will complain that #Ugly headers don’t work. So I don’t know.

Every single Discourse site we launch, someone complains that “hashtags” render in a weird way. Hashtags, as popularized by little services you probably have never heard of like Instagram and Twitter…

Users expect to type

#breakup

and not get, well, ↑↑↑ that. They expect to see #breakup. This is because hashtags have entered the public consciousness.

It comes up a lot. Enough that I think the default is a bad default and should be changed – the space should be required.

2 Likes

Does it come up enough to outweigh the downside? Remember that Stack Exchange and Discourse are both instances less likely to use titles in their platforms that things like blog posts. Anecdotally, this would break every blog post I have. This includes links to sections which wouldn’t have titles or generated id attributes for hash links as well.

With due respect to those chiming in so far here, I think there’s a disproportionately narrow view of the negative impact this has on other types of applications - like blog posts or in general anything that is far more substantial in length. I don’t agree this change is worth the negative tradeoff of impact to existing content.

For example, my case: when changing to CommonMark, anything generated by this would (silently) break anyone in the same situation with their blog generated via Jekyll - this includes a ton of other users hosting via GitHub pages as well.

@NickCraver It’s certainly a hard question: Do you break backwards compatibility in order to avoid pain points in the future? In the case of your blog posts, a fairly simple one-time automatic replacement could fix all the headers without spaces. Still, that’s asking a lot of users, and for some reason many people have gotten into the habit of omitting the space, so the pain would be widespread.

It would be good to get feedback here from github people. I know that github uses #1533 and the like for mentioning issues. I’m curious how that interacts with headers as they interpret Markdown.

1 Like

Some relevant questions:

  1. How often do people put hashtags at the start of a line?
  2. What is more common, creating a first level header or putting a hashtag at the start of a line?

We require a space after the # to interpret it as an h1: https://github.com/gjtorikian/testing/issues/20

We had an idea in the past that never shipped to do something with the hashtag notation.

Two of my humble opinions:

  • I think most everything should require a space, for legibility: *, >, etc.
  • I think backwards compatibility for something like this should not be considered. If you run a blog (or a website) and you’re thinking of switching to CommonMark, consider it a major version bump from the Markdown engine you’re already using. Things will be different. Things might break. It’s up to you, the person in charge of performing the upgrade, to determine what’s worth fixing and what isn’t. It’s not up to the spec to try to set a standard with “you can do this or this” clauses everywhere. Implementors should be well aware of the risks and trade-offs.

Another choice would be to add a new OPT for toggling this, similar to hard and soft linebreaks.

1 Like

Requiring a space before headings is a huge usability win considering the #hashtag and #17 cases, and # Heading is more readable than #Heading anyways. Anyone who uses reddit sees the #hashtag interpreted contrary to the user’s intent every day.

Enforcing the space for all such syntax features (> and #) for those reasons and for consistency is the best way to go, in my opinion.

I think that lists/blockquotes vs ATX headers are different here. I’ve seen multiple people writing Discourse markdown fail to create a list because they didn’t end their paragraph,

  • like this. (example of incorrect user guess)
    -This is clearly not rendered as a list, though it’s pretty obvious they wanted it to be one.

I think that spaces should be required for ATX headers and optional for blockquotes and lists.

And even then, users can self-remedy! When CommonMark does something you don’t want it to do with the character you typed, you (usually) can pull out your handy backslash and slap it in front and get on with your day. That happens to be true in this case too.

Given that hashtags aren’t something that is guaranteed to be appropriate in all places that CommonMark might be used, I don’t know if we can rely on that user expectation to set a baseline. As such, I’m in favour of maintaining backwards compatibility with the non-required-space approach, given that users have more freedom to pick their desired output.

The issue as I see it is not that some one would start a sentence with a hashtag as much as it might end up at the beginning of a line from hard wrapping.

Also, it seems far nicer to require the space just from a readability perspective.

So what are our test cases here:

#heading
# heading
#hashtag
#15 number
#1533 github issue

Did I miss any?

When I arrived at this discussion I was in favor of allowing no space for backwards compatibility, but after reading through the thread and considering the different cases I think I’m converted to requiring the space.

I’ve felt the pain of manually editing lots of markdown files to include the space in headers due to moving between blog engines. As far as I can tell, there’s no simple way around it.

2 Likes

@balpha, how many comments or posts in chat do begin with an hash?

Personally I think that space after hash will only really break existing M******n users who bothered to read the docs, and those are the most likely to be able to adapt to the new behaviour — and then we should know better than to use h1 tags in post bodies :slight_smile:

The easier way out would be to explicitly assign #this special semantics. Shorter post contexts like reddit and discourse probably want hashtags. Longer form posting like SE and blogs probably want anchoring for intra-article links. (Github has issue numbers, though those are numbers so #this remains ambiguous.)

If you don’t want to use extensions though and you really want to automagically do the right thing, at least for most languages, disambiguate on the character immediately following the # sign. If that character is uppercase, it’s a title, otherwise it’s an hashtag. (Define uppercase as x == x.upper(), so “1”, " (" and “本” would count as uppercase.) This renders #swag and #ifdef verbatim, it leaves #Loud noises loud and goes with backwards compatibility with the rest of the cases.

As one of the #noobs who contributed to this always leaves out the space, sorry.

I see the point of changing this, I know Github does require the space (which incidentally catches me out all the time)

It is important to note this only affects people who want to put a #hastag at the start of the line (which i guess is a fairly common use case).

In a chat-like application that uses hashtags, the “line starts with a hashtag” is an extremely common use case. Often a chat message can be just a single hashtag. Adding barriers like having to escape them in this case (starting a line) vs. everywhere else would be really confusing and a major pain point. In a chat application, the pace of communication is easily a lot faster than when writing blog posts or comments, so breaking that workflow is in my opinion also more harmful.

1 Like