Explain that markdown internal links to documents cannot contain spaces

[choldgraf]

Describe the bug

context When somebody references a local document that has a space in the title, the reference does not properly resolve. So for example, [my text](./path/to/my doc.md will not resolve properly, but [my text](./path/to/my_doc.md) will be fine.

Reproduce the bug

• Create a sibling page called test file.md next to a pre-existing docs page. Give a title like # test

• In a pre-existing sibling page, paste this markdown:

  - [](test file.md)
  - [](test file)
  - {doc}`test file`
  

The first two links will not work, the third does. Here's how it looks on my screen:

List your environment

the above example was run via tox -e docs-live on master.

Resolution

I think we could resolve this either:

• By patching the code so that we know how to handle filename spaces
• By documenting that if somebody wants a space in their filename, they must directly use the {doc} role

ref: https://github.com/executablebooks/meta/discussions/654 where this was first reported

[chrisjsewell]

It's not valid common mark so there is no way to support it, unless you can find a way in http://markdown-it.github.io/

[choldgraf]

In that case, I think that we should just document it so that users know what to expect. I'll re-tag this as a docs improvement.

[chrisjsewell]

Cheers, it's unfortunate, but not much I can go in this matter, unless there is a common mark compliant solution I'm missing

[psychemedia]

Is a slash escaped space or space separated tokens "wrapped in quotes" also not handled?

[chrisjsewell]

Closing as now explained in https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#commonmark-link-format

i.e. you just need to wrap in <> like [](<test file.md>)