Escape square brackets less

[hukkin]

Linked issue #110

Prettier seems to do a better job at square bracket escaping. Mdformat currently always escapes square brackets (to not accidentally produce link label enclosures) whereas it seems that Prettier keeps escapes from the source text.

The token stream we get from the parser is mainly just abstract syntax, so we don't know if the escapes were there in the source or not. Thus doing exactly what Prettier does is not currently easy to implement.

Like with other escapes, we could try to come up with logic that detects cases where link label enclosure certainly will not be accidentally produced and not escape if that is the case.

Note that this approach when implemented well enough can actually be an improvement over simply sustaining escapes from source, as it will automatically remove needless escapes.

[hukkin]

I'm starting to think it might be better to leave this as won't fix due to readability and stability issues caused by unescaped square brackets.

• Square brackets connect with others even if they are not on the same line.
• Given markdown like

  [blaa]

  this is not a link. But if someone adds a link reference definition with the label blaa then suddenly it is a link.
  Also, for source readability it might be better to have the escape characters to be able to immediately tell that there is no link.
• Given markdown like

  blii [blaa]: blipblop

  if someone removes the initial blii then suddenly we have a link reference definition and all text disappears when rendered

[hukkin]

If this is not left as a won't fix, then the following heuristic could be useful:

Escape all square brackets unless all of the following are true for a closed pair of brackets ([ + text + ]):

• the brackets enclose a text containing no square brackets,
• the text is not a used_ref (a link label used in a valid link or image)
• the enclosure is not followed by : or (

[butler54]

I'll put a plus one on fixing this.

[jamesquilty]

FWIW, the ability to disable escaping altogether is next on my list of configurations to implement in my fork commit jamesquilty@2404bb0 adds a configuration option escape_square_brackets which simply (or simple-mindedly) disables square bracket escaping.

[mlschechter]

I think this issue also impacts using mdformat with Hugo cross-references.

The original content:

[company branding]({{< ref "company-branding.md" >}} "Branding Configuration")

And the formatted result

\[company branding\]({{\< ref "company-branding.md" >}} "Branding Configuration")

This will break the Hugo rendering; could you please let me know if there is a configuration parameter or plugin that will prevent this happening?

[sanzoghenzo]

This is also an issue with mkdocstrings cross-references when used in manually created markdowns (in my case the root README.md).

[`Object 1`][package.module.object1]

even an option to disable the escaping would be a huge improvement for my use case (we don't usually use reference links, so the likelihood to break things is really low)

[nschloe]

I just noticed another problem with escaping brackets: Gitea uses \[...\] for display math, so every naive [abc] block is converted to Gitea math by mdformat. It'd probably be useful to add a switch for disabling square bracket escaping altogether.

[afuetterer]

This is also an issue with mkdocstrings cross-references when used in manually created markdowns (in my case the root README.md).

[`Object 1`][package.module.object1]

even an option to disable the escaping would be a huge improvement for my use case (we don't usually use reference links, so the likelihood to break things is really low)

Anybody running into this, have a look at mdformat-mkdocs with the --ignore-missing-references flag. It solved the issue for me when using mkdocstrings.

[mdeweerd]

@afuetterer Thenk you for sharing - it reminds of the alternative: have an option to control the behavior. And it got me back to this page.

Personally I think that even a standalone [text] should be left untouched by default and just generate a warning message suggesting to escape the brackets or add the (equivalent of the) --ignore-missing-references argument or --escape-missing-references to have them automatically escaped.

Personally I am not into mdformat to have "everything" "fixed" (in some cases breaking it). There are also quite a few developers that do not want tools to make many "intrusive" changes.

My original issue occurred when I had two spacea after the markdown tickbox - [ ] and the tickbox was escaped.

[zubieta]

Hi everyone! I'm pretty interested in fixing this. I don't know the mdformat codebase, but I'll be willing to take a stab at implementing this (even if slowly), if someone is willing to point me in the right direction and hold my hand a little.

If this is not left as a won't fix, then the following heuristic could be useful:

Escape all square brackets unless all of the following are true for a closed pair of brackets ([ + text + ]):

* the brackets enclose a text containing no square brackets,

* the text is not a `used_ref` (a link label used in a valid link or image)

* the enclosure is not followed by `:` or `(`