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.

[mdeweerd]

I am adding this kind of change to this ticket - it is related, not exactly the same, but also overly changing the source.

# From
- [Rénovateur de pannes](Rénovateur-de-pannes)
# To
- [Rénovateur de pannes](R%C3%A9novateur-de-pannes)

Changing the link character format is unneeded IHMO and makes the link less readable, less practical to correct if needed.

[hukkin]

Thanks @mdeweerd! That's not related to square bracket escapes so I moved it to a separate issue.