Open hukkin opened 3 years ago
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.
[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.
blii [blaa]: blipblop
if someone removes the initial blii
then suddenly we have a link reference definition and all text disappears when rendered
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
+ ]
):
used_ref
(a link label used in a valid link or image):
or (
I'll put a plus one on fixing this.
FWIW, the ability to disable escaping altogether is next on my list of configurations to implement in my fork commit https://github.com/jamesquilty/mdformat/commit/2404bb0ee6728270c5b7f266ff5a44e0973024a4 adds a configuration option escape_square_brackets
which simply (or simple-mindedly) disables square bracket escaping.
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.
Thanks @mdeweerd! That's not related to square bracket escapes so I moved it to a separate issue.
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?
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)
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.
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.
@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.
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 `(`
mdformat
should support:
Remaining TODOs:
- [ ] Add cookies dialog
It instead escapes it as: - \[ \] ...
There is no way to fix this using current options. I would consider this a bug.
mdformat
should support:Remaining TODOs: - [ ] Add cookies dialog
It instead escapes it as:
- \[ \] ...
There is no way to fix this using current options. I would consider this a bug.
Found a fix that works for me:
- repo: local
hooks:
- id: mdformat
name: mdformat
entry: mdformat
language: python
additional_dependencies:
- mdformat-toc
- mdformat-gfm # <--- This is the fix for me
args: ["--wrap", "120", "--number", "--end-of-line", "lf"]
types: [markdown]
files: .
Linked issue https://github.com/executablebooks/mdformat/issues/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.