search

MacDownApp / macdown

Open source Markdown editor for macOS.
https://macdown.uranusjr.com/
9.44k stars 1.09k forks source link

Update header parser for apparent changes to GitHub #791

Open ZevEisenberg opened 7 years ago

ZevEisenberg commented 7 years ago

Headers in Markdown are specified like this:

##This is an H2

This should render like so in GitHub:

This in an H2

However, I've recently noticed that headers specified without a space between the # and the first character are rendering as ##This is an H2 on GitHub pages. I'm not sure if this is intentional, but MacDown should match GitHub's behavior.

Here's a test H2 without the space, so we can see if GitHub has changed their behavior:

This is an H2 without a space

ZevEisenberg commented 7 years ago

Oh hey, apparently GitHub-flavored markdown now has a spec and reference implementation: https://github.com/blog/2333-a-formal-spec-for-github-flavored-markdown

uranusjr commented 7 years ago

Yes, GitHub recently switched to CommonMark (plus extensions), which is stricter than the original Markdown spec in several ways. This is one of them.

In MacDown (more precisely, Hoedown), this behaviour can be activated by setting HOEDOWN_EXT_SPACE_HEADERS. But since MacDown is used by people who want to conform to other syntax rules. I’m not sure what is the best way moving forward.

  1. Continue to allow the more permissive syntax. This changes nothing.
  2. Force the new syntax, breaking existing documents. This makes MacDown follow CommonMark more closely, which is arguably the best standard moving forward. Users who like the old syntax (and do not care about CommonMark) would not be happy though.
  3. Add a switch in the preferences to toggle between 1. and 2. This seems like a good idea at first glance, but in reality only delays the problem when we eventually adapt CommonMark. CommonMark explicitly disallows the ##text syntax, and we will be forced to break this existing feature if we add the toggle now.
ZevEisenberg commented 7 years ago

Any easy way to offer users to migrate their documents when they open them?

FranklinYu commented 7 years ago

Fun fact: vmg, the one writing the blog @ZevEisenberg mentioned (a GitHub staff of course), is also the author of Sundown; Hoedown is a fork of Sundown. From that I see how developers converge to CommonMark.

jshier commented 7 years ago

Perhaps, similar to how many text editors allow on-the-fly switching of the parsing language, MacDown could allow switching Markdown renderings on the fly? It's additional complexity for users, but given the fragmented nature of Markdown specs and the ability of organizations like GitHub to extend even the most common specs for their own use, it seems like the best solution available. It could also allow users to choose between, say, CommonMark and CommonMark (GitHub extensions).

Barring such an engineering expenditure though, I think using CommonMark OOTB is probably fine, given GitHub's findings. Unfortunately, supporting GitHub's CommonMark implementation with their extensions would require switching from Hoedown to GitHub's cmark fork, which doesn't product HTML natively (I'm assuming that's what MacDown uses, I haven't looked), so unless Hoedown will be updated, that may be a transition that has to happen anyway.

It's not too important, but we've run into a few rendering issues in Alamofire's various bits of documentation due to these differences, so this is a visible issue if you're using MacDown to edit documents on GitHub.

Jmuccigr commented 3 years ago

Presumably nothing further has happened on this?