I believe that #heading should render as <h1>heading</h1>, but it is resulting just as #heading. Users need to put an extra space character (like # heading) to output headings. Is this intentional, or a bug? Am I missing something here??
1 Like
+++ Arpit [Oct 17 14 15:34 ]:
I believe that
#headingshould render as<h1>heading</h1>, but it is resulting just as#heading. Users need to put an extraspacecharacter (like# heading) to output headings. Is this intentional, or a bug? Am I missing something here??
It is intentional. See the spec for ATX headers, which explicitly discusses this.
3 Likes
Related question: why does # heading require a space after the #, but >blockquote not require a space after the >?
1 Like
Related question: why does # heading require a space after the #, but
blockquote not require a space after the >?
The main reason for requiring a space after the # is that it is not uncommon to have things like #15 in text, and we don’t want these to be inadvertently treated as headers. (Also, aesthetically the space is nicer.)
The same consideration doesn’t apply to blockquotes, as a line is very unlikely to start with (say) >5 for any other reason. One might, of course, have something like:
Consider an integer x, where x> 0 and x
<15.
But requiring a space would not help with this particular problem, as the following is even more likely:
Consider an integer x, where x > 0 and x
< 15.
The case could be made for not allowing block quotes to interrupt paragraphs, but that is another issue entirely and should not be discussed in this thread.
One good reason for not requiring the space after > in block quotes is that, in ordinary email quoting, it is often omitted.
3 Likes
So no space ensure that hashes are treated as hashes when needed, and encourages headers to be in a nicer visual form. In summery:
tl;dr: Feature, not bug.
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. 
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:
- How often do people put hashtags at the start of a line?
- 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.