Markdown [...](...) syntax does not play well with sphinx.ext.autosectionlabel

[jeanas]

Describe the bug

The MyST documentation states that the [...](...) syntax is a superset of the any role. Yet, [...](...) does not appear to work for referring to section labels defined implicitly using sphinx.ext.autosectionlabel, whereas the any syntax does.

Reproduce the bug

index.md:

# Document title

Look at {ref}`the title <Document title>`.

Look at {any}`the title <Document title>`.

Look at [the title](Document title).

conf.py:

extensions = ["myst_parser", "sphinx.ext.autosectionlabel"]

Screenshot of output:

List your environment

MyST-parser master, Sphinx master. Also reproduced with Sphinx 4.5.

[jeanas]

From further experimentation it looks like this problem shows up when the title contains spaces.

[jeanas]

Oh, actually, I see now that markdown_it doesn't even recognize that syntax as a link. Reading the CommonMark spec, I see that I should have written [the title](<Document title>). Sorry for the wrong issue.

I do think this could use a note in the documentation.

[jeanas]

I am starting to wonder if it would be appropriate for MyST not to require these brackets after all. For context, what triggered me to move my projects to MyST was this:

https://github.com/sphinx-contrib/sphinx-lint/issues/4#issuecomment-1109372243

Namely, quirks in reST linking syntax, which don't result in any warning ("errors should never pass silently"), and don't show the intended output. Now, I have to remember similar quirks with MyST as well :-(

So how about doing an extension to standard (CommonMark) Markdown to allow spaces and newlines in the target, even without pointy brackets <>?

[chrisjsewell]

So how about doing an extension to standard (CommonMark) Markdown to allow spaces and newlines in the target, even without pointy brackets <>?

Ah but that is standard commonmark, specifically: https://spec.commonmark.org/0.30/#example-487

[chrisjsewell]

This is not really an extension to commonmark, it would be effectively breaking it. So I'm afraid even it is possible, it's highly unlikely to happen

[jeanas]

OK. Too bad, but I understand.

Some possibilities remain not explored, though, e.g. this sort of mix between reST role with target syntax and Markdown doesn't look totally unconceivable to me:

{ref}[the title](Document title)

or (in a fashion less similar to CommonMark, so it shouldn't classify as "breaking" the spec):

{ref}`The title`<Document title>

Or something. At any rate, like the folks in #548, I wish MyST had a brainless way of doing cross-references. The usual problem with {ref}`Text <target>` is that there must be a space before the <, which everyone forgets about…