search

hukkin / mdformat-gfm

Mdformat plugin for GitHub Flavored Markdown compatibility
MIT License
13 stars 2 forks source link

Add proper support for GH notice boxes (highlight using blockquote) #29

Closed michalfita closed 10 months ago

michalfita commented 10 months ago

Problem

GitHub now supports notice boxes as per https://github.com/orgs/community/discussions/16925 using special formatting of blockquotes, however mdformat-gfm escapes square brackets used in them:

Original:

> ![TIP]
> In above commands **`latest`** can also be replaced via e.g. **`1.0.3`** to get a specific container version.

Changed:

> !\[TIP\]
> In above commands **`latest`** can also be replaced via e.g. **`1.0.3`** to get a specific container version.

This breaks our Markdown documents in pre-commit (michalfita/packer-plugin-cross#12)

Suggestion

Add support to not escape square brackets if prepend with exclamation mark.

dbast commented 10 months ago

The solution here is to write [!TIP] (! inside the []), which is formatted by mdformat to \[!TIP\] and rendered correctly by GitHub.

michalfita commented 10 months ago

OK, I'm surprised this works that way... however, I think mdformat shouldn't touch these brackets in such case - the result is much less pleasant to deal with in raw Markdown.

hukkin commented 10 months ago

Thanks for the issue!

This plugin formats Markdown that follows the GFM spec (rendered text here https://github.github.com/gfm/ and source text here https://github.com/github/cmark-gfm/blob/master/test/spec.txt). The GFM spec does not include some Markdown features supported by github.com (very notably frontmatter and footnotes), and the notice box syntax falls in the same category.

In the current state, a separate plugin for the notice box syntax needs to be created (or alternatively a mdformat-github or similar that aims to keep up with Github's syntax updates.

I'm closing the issue here seeing that this isn't a concern for the mdformat-gfm plugin.