Support (balanced) nested parentheses in link destinations

[kivikakk]

Hey @jgm!

This PR changes the spec and parser to allow any number of balanced nested parentheses in link destinations; this turns out to be a pretty common thing in e.g. URLs to graph services, and the single parenthesis-pair restriction currently present feels somewhat arbitrary.

/cc @vmg

[vmg]

@jgm: 👋

We're trying really hard to stick to the CommonMark spec, but while rolling the new parser to production, we've found there's an overwhelming amount of links that break when users paste them into a Markdown document.

These links mostly come from HTTP APIs that take parameters containing queries or math operations, and hence contain nested parentheses which are not escaped. This kind of links break when inserted into Markdown link syntax [link](url) because of the limitation on just one level on nesting.

The most frequent cases are Graphite query links and Mixpanel analytics links. Mixpanel, for instance, provides users directly with Markdown syntax to paste on their READMEs, and this syntax contains nested parenthesis, which now break in GitHub.

It's not feasible for us to reach out to all the services that generate Markdown and ask them to escape their parens in links. So that's why we'd like to propose this small change to spec, which we're already running in production. The code changes are minimal, and I think the resulting Markdown is significantly more user-friendly this way.

I'm not sure of what is the process to upstream the actual change to the Spec, but we've started with the change to the actual parser to prove its viability. Would you like me to propose the change on the Spec repo instead?

Thank you!

[jgm]

+++ Vicent Martí [Dec 01 16 01:36 ]:

***@***.***: 👋 We're trying really hard to stick to the CommonMark spec, but while rolling the new parser to production, we've found there's an overwhelming amount of links that break when users paste them into a Markdown document. These links mostly come from HTTP APIs that take parameters containing queries or math operations, and hence contain nested parentheses which are not escaped. This kind of links break when inserted into Markdown link syntax [link](url) because of the limitation on just one level on nesting.

OK, that sounds reasonable to me. Let me look into the PR.

[jgm]

This looks ok to me. I'll port it over to jgm/CommonMark, the spec itself.

[vmg]

🙇

Rebasing our fork now. Thank you so much @jgm!

[kivikakk]

Thank you! And sorry if my initial PR was overly lacking in context or description; thanks @vmg for taking the time to explain the motivation better.

[jgm]

I don't think there was any motivation for the original limitation to one level of nesting beyond my (lazy) desire to parse it with a regex. So this is a good change.