@dipree can you please update the summary to mention that preview and mobile aren't yet implemented so that people don't have to read through 183 comments / 479 replies to discover this?

We should take into consideration that there are existing solutions outside of Github that already support the syntax that @laserlemon mentioned:

> [!QUESTION] Consider this…
> How do we invalidate the cache?

Right now, Markdown files with this syntax are broken when viewed in Github.

It would be great to see this custom text feature. Long awaited! 🎉

I stumbled upon this discussion while looking for a way to customize the label.

Because I regularly miss a > [!EXAMPLE] alert.

Currently, I'm doing:

But it's really not great.

So, being able to do > [!NOTE] Example would be a great addition.

I'm currently running into this issue in a repo. It would be really nice if the label was customisable.

Yes! I agree. It would be nice to have [!EXAMPLE] or it would be even better if I can use something like below!

> [!<EMOJI>] Custom note
> Message to the reader

great

Except that AsciiDoc has had native admonitions since forever (in the standard, not a GitHub-flavored AsciiDoc fork) but GitHub has never supported styling them at all.

Except that AsciiDoc has had native admonitions since forever (in the standard, not a GitHub-flavored AsciiDoc fork) but GitHub has never supported styling them at all.

Same with reStructuredText, it has extensive support for admonitions both specific and generic (admonition) in the baseline language, but that gets rendered as essentially garbage.

It turns out you can use this new admonitions hack in reStructuredText as well by just using the 4-space block quote syntax. And you can even indent it using the pull-quote directive.

#. List item
   .. code:: bash

      Do something

   .. pull-quote::
      **Warning**
      **NB:** Something to be aware of

Still, I don't understand why GitHub still refuses to allow these with the built-in admonition directives in these languages.

👍🏻

@toastal From your link it seems AsciiDoctor only supports icons in the HTML rendering, not in the source plain text.

AsciiDoc รองรับชื่อภาษาไทย แต่ต้อง compile ใน terminal

😑

You say “backwards-compatible syntax”; I say “spec-breaking & semantic-breaking syntax”

use html text with css

Check
This is OK

@YusukeHirao:

HTML Standard says:

The blockquote element represents a section that is quoted from another source.

Agreed that the generated HTML should not use <blockquote>. GitHub can easily have it rendered as a <div> with a warning class.

@tom-sherman:

I don't like the idea of overloading the blockquote semantics to mean something more than a quote.

But since we are defining new syntax, we get to define the semantics. We are specifically saying that > **Warning** is the syntax for a semantic Warning admonition. > in all other cases has block quotation semantics.

I looked at the HTML GitHub is rendering it with, and they are not using a div+class as they should:

<blockquote>
<p><span class="color-fg-attention"><svg>...</svg>Warning</span><br>
This is a warning</p>
</blockquote>

This should be fixed. It not only violates HTML semantics, it's going to make it less accessible. I'm not an expert, but there is probably a proper ARIA way to do this.

I find the conversation around markdown grammar interesting and I think when you consider the design of the markdown syntax it backs up my point even more.

We are specifically saying that > **Warning** is the syntax for a semantic Warning admonition. > in all other cases has block quotation semantics.

Firstly this violates the principle of least surprise - it's not totally clear why that renders a warning aside or callout and not a blockquoted "Warning" in bold.

Secondly, how do I now quote someone that has actually said "** Warning"? It would require escaping. Going a step further, how do I quote someone else's warning callout? Overloading the blockquote markdown introduces new decisions that need to be made, this is bad design overall.

And finally, the proposed syntax changes GithHub Flavored Markdown in such a way that it adds more context to the grammar. I believe this to be the root cause of the two symptoms above.

Could use a pipe symbol (|) instead of a greater than (>) for admonitions, blockquote does not seem ideal.

This syntax can be quite confusing, especially when writing in an IDE.

Hi, I like the idea but I would like to propose alternative syntax.

GitHub Flavored Markdown is a superset of CommonMark and thus ideally it stays close to that if possible. The generic directives proposal for CM is already used in the ecosystem, take for instance remark-directive or how it's implemented in the very popular Docusaurus and VuePress.

This is how it would look:

:::note
This is a note
:::

Maybe add a 1-line tip (alert, notice, warning etc.) feature to this syntax will be better, as this:
code:

:::TIP some tip with quoting code `code`:::

or

:::!TIP some tip with quoting code `code`:::

or

:::[!TIP] some tip with quoting code `code`:::

render as:

As @pboling pointed out earlier, I would be wary of providing Markdown authors with syntax specifically to accommodate their Octicon symbol name as it may contribute to vendor lock-in. I do, though, wonder whether this feature is only expected to offer users a couple of options (the fundamentals) or whether we should be expecting more choices in the future? If we have one admonition for warnings, we should be given at least one more for the danger zone/error prone/high severity callout content as well.

With the two current choices of note and warning, I doubt additional syntax for specifying particular Octicon symbol names would really be necessary (or even preferable). In the current rendition of this beta feature, the GitHub Web UI may have implemented these callouts using Octicons, but with the limited subset we were given — only a couple of key choices — I think we can probably do better here.

I don't think it is a good choice.

But opening up a space for users to pick the best color would be better.

Too rich colors can cause visual fatigue for users。

CM deals with parsing. GFM inherits that property.
Breaks (and mentions, gemoji, much much more) do not happen when parsing, they are added later by transforming the HTML.
The recent addition of math is similar: it also transforms the HTML (I believe this to be bad and that is should happen in the parser).
I definitely agree there is a lot of room for improvement of explaining this situation.

You could argue that GFM is not compliant to CM, because it adds onto it.
I understand this point, that comments are not GFM compliant, as similar: I instead see comments as GFM compliant, and CM compliant, but adding more things.

There isn't really a reason why markdown in issues, Pull requests and discussions can't be GFM. It's just a slightly modified one.

And why it behaves so differently in terms of line breaks should be obvious here: Not everyone who files an issue or posts a discussion knows the ins and outs of Markdown, let alone GFM, so not having to deal with that two spaces thing for line-breaks makes it easier for those new people.

We could argue about the semantics, backwards compatibility, etc. of GFM with CommonMark until the heat-death of the universe. In the end does it not matter here. When adding new stuff is GitHub most likely thinking about how it is the easiest and most convenient to use for the end-users, which may not always be programmers or people with vast CommonMark knowledge.

I mean some other features of GFM are barely known such as that when writing a HEX colour inside an inline-code block, it renders a small icon in that colour: #aabbcc

The behaviour of:

Seems like...

> **Note**
> Text

...is currently rendered on the same line in readme files, instead of two separate lines like it does here in discussion comments:

How it's rendered here:

Note
Text

How it's rendered in readme:

Has changed:

@see7e Don't rely on these features too much. They're great when they work, but they're beta. And basically abandoned from having any further development, sadly.

I had never heard of Obsidian before seeing it mentioned here. Other than Obsidian Publish, are other services using Obsidian-Flavored Markdown? I would be curious to know how portable the syntax is.

NOTE, TIP, and CAUTION types would be awesome to have! 😍

Colors, more colores, yes

I agree to everything

I think this design format would make for a more readable and visible readme file.
Hopefully this will become true in the near future.

I have long earnestly desired!!!!!!!!!!!

Happy time!

This is, unfortunately, intentional

Update - 14 November 2023

• Prevent alerts from being nested within other elements.

It's been discussed multiple times above and has frustrated many people. Maybe Github will finally undo this change but it seems extremely unlikely at this point _{(just linking for a record)}

• comment-7618439, comment-7574895, comment-7868288, comment-7936248, comment-7888245, comment-8148855, comment-8383959, comment-8494315, comment-8542131, comment-8590818, comment-8804836, comment-9156825, comment-9538837, comment-10195289, comment-10575676, comment-10620802, comment-10949202, comment-11812784, comment-12029106, comment-12491256, comment-12649051

@sinsukehlab has made a really nice example page that shows the ways notes render (and don't render) for various situations including "nesting" example if you wanna see a more thorough example

None of these seem to work within <details></details collapsibles 🤷

Indeed...

No. This question has been asked and answered many times. It used to be a feature, and it was removed intentionally. Using this feature for anything serious is probably a bad idea.

Been a little while since a new one of these comments popped up but alas nothing has changed. Two and a half years since they first removed support. So here's to more trying to keep GH accountable for ignoring their community

Update - 14 November 2023

• Prevent alerts from being nested within other elements.

It's been discussed multiple times above and has frustrated many people. Maybe Github will finally undo this change but I wouldn't get your hopes up. _{(just linking for a record)}

• comment-7618439, comment-7574895, comment-7868288, comment-7936248, comment-7888245, comment-8148855, comment-8383959, comment-8494315, comment-8542131, comment-8590818, comment-8804836, comment-9156825, comment-9538837, comment-10195289, comment-10575676, comment-10620802, comment-10949202, comment-11812784, comment-12029106, comment-12491256, comment-12649051, comment-14721543

@sinsukehlab has made a really nice example page that shows the ways notes render (and don't render) for various situations including "nesting" example if you wanna see a more thorough example

bro xD

Honestly? Words of appreciation are really nice and encouraging :)
If it was just about me then I would probably just stop giving fucks about at this point, but seeing some other people do actually enjoy it even in current state, makes me feel like now I have to give a damn, fix damn bugs, and keep improving the damn thing untill I myself could say "Decent"

So that's exactly what gonna happen :)

I cannot promise it soon coz im super busy irl, but I can promise not to forget that <3

If you guys have any suggestions or would like to have some features in it, then im all ears now :)

@theherk I'll never not be upset that giant corporations can drop a steaming pile, have it infect the entire internet, wreaking havoc far into the future, and then just walk away. Why are any of us ok with this?
@serainox420 I love that you put effort into a solution! I'll post back here when I've got some use cases implemented.

pretty neat

@theherk I'll never not be upset that giant corporations can drop a steaming pile, have it infect the entire internet, wreaking havoc far into the future, and then just walk away. Why are any of us ok with this? @serainox420 I love that you put effort into a solution! I'll post back here when I've got some use cases implemented.

I'm not even programmer or developer, I write and document small personal scripts, and comment in OSS or game modding project repos that I use, and even I find it frustrating. I can't even imagine being forced to deal with this garbage everyday for work. People are right to call them MICROSLOP.

Looks promising to me!