5 ms·

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

by jorams 10y ago

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/ https://guides.github.com/features/mastering-markdown/ [2]: https://help.github.com/articles/basic-writing-and-formatting-syntax/ https://help.github.com/articles/basic-writing-and-formattin...

deleted 10y ago
[deleted]
y0ghur7_xxx 10y ago
> 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 https://github.github.com/gfm/#hard-line-break So two spaces at the end of the line for a , and an empty line for .
- jorams 10y ago
 Right, but that's not what GFM does. GFM turns any single newline into a .
 - hashhar 10y ago
 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.
 - kivikakk 10y ago
 As of this announcement, file backed content _does_ use GFM (try a table!), but not the `hardbreaks` option.
kivikakk 10y ago
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.
- yuchi 10y ago
  This is a very important bit of information. Do you mind to make sure this is reflected in docs?
- tbrock 10y ago
  Good to know. Why is the setting different for issues than for blobs?
  - steveklabnik 10y ago
    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.
    - tbrock 10y ago
      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.
      - steveklabnik 10y ago
        Because using the new display format with a non-normalized source would break the display.

by jorams 10y ago

deleted 10y ago

[deleted]

y0ghur7_xxx 10y ago

> 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 https://github.github.com/gfm/#hard-line-break So two spaces at the end of the line for a , and an empty line for .

jorams 10y ago
Right, but that's not what GFM does. GFM turns any single newline into a .
- hashhar 10y ago
 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.
 - kivikakk 10y ago
 As of this announcement, file backed content _does_ use GFM (try a table!), but not the `hardbreaks` option.

kivikakk 10y ago

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.

yuchi 10y ago
This is a very important bit of information. Do you mind to make sure this is reflected in docs?
tbrock 10y ago
Good to know. Why is the setting different for issues than for blobs?
- steveklabnik 10y ago
  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.
  - tbrock 10y ago
    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.
    - steveklabnik 10y ago
      Because using the new display format with a non-normalized source would break the display.