Escape square brackets even less?

[nicolamori]

Context

Square brackets escape has been relaxed in #112 and in #464. However, for my use case (Gitlab flavored markdown) it still falls short because it screws the automatic generation of the ToC which is done by inserting the [[_TOC_]] token. Currently it gets formatted as \[\[_TOC_\]\] and this breaks the ToC generation on Gitlab.

Proposal

Either:

1. implementing #53
2. adding an additional heuristics ignoring double brackets for escape_square_brackets in src/mdformat/renderer/_util.py

could work. Proposal 1 would probably be the best since it would solve other issues and have no side effects, but being open since a long time I guess it might be hard to implement. Proposal 2 could be easier, but I'm not sure if it would work nor which side effects it could have.

[landure]

I'm confronted to a related issue, but with the inverse need.

with this markdown:

> some text \[…\]

- [My link \[some author name\]](http://link.com).

mdformat removes the \:

> some text […]

- [My link [some author name]](http://link.com).

This is an issue when used with markdownlint.

My version is:

mdformat 0.7.22 (mdformat_admon 2.1.1, mdformat-gfm 0.3.6, mdformat_tables 1.0.0, mdformat_footnote 0.1.1, mdformat_frontmatter 2.0.8, mdformat_mkdocs 4.3.0, mdformat_myst 0.2.1, mdformat_simple_breaks 0.0.1, mdformat_wikilink 0.2.0, mdformat-beautysh 0.1.1, mdformat-nix-alejandra 0.1.0)

My mdformat.toml is:

# .mdformat.toml
#
wrap = "keep"       # possible values: {"keep", "no", INTEGER}
number = true       # possible values: {false, true}
end_of_line = "lf"  # possible values: {"lf", "crlf", "keep"}
validate = true     # options: {false, true}

extensions = [      # options: a list of enabled extensions (default: all installed are enabled)
  # "admon",
  # "footnote",
  "frontmatter",
  "gfm",
  # "mkdocs",
  # "myst",
  # "simple-breaks",
  "tables",
  "wikilink",
]

# codeformatters = [  # options: a list of enabled code formatter languages (default: all installed are enabled)
#     "bash",
#     "json",
#     "nix",
#     "python",
# ]

exclude = []          # options: a list of file path pattern strings

[gaborbernat]

Perhaps we should make this a configuration, where we can allow the caller to control how strict or relaxed they want to be with this? I'm running into issues where custom links we're defining ([](magic:yeah this)) is getting escaped (this would be expanded via a mdformat plugin to [yeah this](https://magic.com/alpha%beta))🤔 .

For reference the escape code https://github.com/hukkin/mdformat/blob/master/src/mdformat/renderer/_util.py#L214

[hukkin]

I'm open to the idea of improving the heuristics used to escape square brackets. Someone needs to come up with a proposal that never breaks CommonMark, though. The current rules and implementing code can be found at the link provided by @gaborbernat.

This is an issue when used with markdownlint.

Markdownlint compatibility is not a goal of this project. I don't see an issue here.

Perhaps we should make this a configuration, where we can allow the caller to control how strict or relaxed they want to be with this? I'm running into issues where custom links we're defining ([](magic:yeah this)) is getting escaped (this would be expanded via a mdformat plugin to yeah this)🤔 .

I much prefer no configuration, especially such that can break CommonMark. The plugin you are using, however, should probably be improved. Optimally I think it probably needs a markdown-it-py (mdformat's parser) plugin to parse the magic link properly. An alternative low effort way could be to override the renderer for text tokens (this is where escape_square_brackets happens).