Hacker News Reader

Comment by jorams | Hacker News Reader

It's odd how neither this post, nor the spec, nor GitHub's "Mastering Markdown" help page[1], nor the more complete "Basic writing and formatting syntax" page[2], mentions the fact that GitHub treats every newline as a hard break.

CommonMark contains this little sentence to work around its specified behavior, which is left untouched in the GFM spec:

> A renderer may also provide an option to render soft line breaks as hard line breaks.

I'd say whether or not it does this is a rather important thing to mention. When I write Markdown documents for GitHub I have to change my editor settings, only because of this.

[1]: https://guides.github.com/features/mastering-markdown/

[2]: https://help.github.com/articles/basic-writing-and-formattin...

View on HN

GFM itself leaves that line unchanged because we don't actually change that option in our implementation — the reference implementation `cmark` (which we built upon) supplies the "hardbreaks" option, described as follows:

> --hardbreaks Treat newlines as hard line breaks

We turn this option on when rendering issues, issue comments and so on, but leave it off when rendering blobs (such as README.md). Both are GFM, one just uses this option to make it more conducive to communication.

This is a very important bit of information.

Do you mind to make sure this is reflected in docs?

Good to know. Why is the setting different for issues than for blobs?

This is covered in the post, no?

> There is a fundamental difference between these two kinds of content: the user comments are stored in our databases, which means their Markdown syntax can be normalized (e.g. by adding or removing whitespace, fixing the indentation, or inserting missing Markdown specifiers until they render properly). The Markdown documents stored in Git repositories, however, cannot be touched at all, as their contents are hashed as part of Git’s storage model.

Sure, but I'm still confused as to why the display format setting has anything to do with the on-disk format. To me they seem completely orthogonal.

In general people have come to expect that hitting return once in a comment field on GitHub will produce a newline, having been the case for many years, so we try to preserve that expectation. Hence not changing the option being used when rendering comments.

Conversely, they don't expect the same from Markdown files stored in their repository (e.g. I put each sentence in a paragraph on its own line for my blog, for easier diffing and editing). Additionally, we couldn't normalise these documents even if we wanted (to prevent everything breaking by being over-vertically spaced). Hence not changing the option being not used in this case!

Because using the new display format with a non-normalized source would break the display.

> It's odd how neither this post, nor the spec, nor GitHub's "Mastering Markdown" help page[1], nor the more complete "Basic writing and formatting syntax" page[2], mentions the fact that GitHub treats every newline as a hard break.

Well, actually it does say that "Hard line breaks are for separating inline content within a block."

https://github.github.com/gfm/#hard-line-break

So two spaces at the end of the line for a <br>, and an empty line for <p>.

Right, but that's not what GFM does. GFM turns any single newline into a <br>.

Depends on where you use it. All file backed content (ie. repo data) does not use it, while the communications systems (PRs and issues) use it.

As of this announcement, file backed content _does_ use GFM (try a table!), but not the `hardbreaks` option.

Reply on news.ycombinator.com