[Markdown] An option to highlight a "Note" and "Warning" using blockquote (Beta)

[dipree]

Alerts are an extension of Markdown used to emphasize critical information. On GitHub, they are displayed with distinctive colors and icons to indicate the importance of the content.

An example of all five types:

> [!NOTE]  
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]  
> Crucial information necessary for users to succeed.

> [!WARNING]  
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

Here is how they are displayed:

Note

Highlights information that users should take into account, even when skimming.

Tip

Optional information to help a user be more successful.

Important

Crucial information necessary for users to succeed.

Warning

Critical content demanding immediate user attention due to potential risks.

Caution

Negative potential consequences of an action.

Update - 14 November 2023

• Add support for [!TIP] and [!CAUTION].
• Add support for alerts in Markdown files on GitHub Mobile apps. (pending a mobile app update)
• Add support for various Markdown extensions such as Math rendering, relative links, task lists, animated image player and footnotes.
• Prevent alerts from being nested within other elements.
• The initial syntax using e.g. **Note** isn't supported any longer.

Update - 12 October 2023

• Fix bug where alerts aren't rendered in Markdown file previews
• Add support for Wikis
• Fix various issues with nested blockquotes

Update - 28 July 2023

Thank you all once again for providing a ton of feedback. Few more changes based on that:

• Support for soft line break in Markdown files.
• Visual improvements to stand out better in content and render appropriately with different font-sizes (comments vs. docs)
• Minor bug fixes

Update - 26 July 2023

Thanks for all the comments, we are working on a handful of fixes. One of them is to support soft line breaks in Markdown documents, so it will work the same in comments versus docs.

Update - 21 July 2023

We've made several improvements in response to your feedback:

• The output will now render as a div instead of a blockquote.
• The text color has been changed to primary from the previous muted version.
• We've tightened our parsing rules to prevent conflicts with other Markdown or HTML on the allowed list.
• Consequently, a line break following the title is now required.
• We've introduced a new alert type IMPORTANT.
• A new syntax, [!NOTE], has been added, which will gradually replace the old one. However, the old syntax will continue to work for some time.

Thanks to all for your valuable input on this topic!

Initial - 10 May 2022

To better highlight and separate certain information from the rest in your documentation on GitHub, we now render a special and accessible note or warning blockquote in Markdown documents. We are using the existing syntax for blockquote and bold text.

Note
The first line must be exactly as shown below. The first letter is case sensitive. The second line can contain your content.

This input:

> **Note**
> This is a note

> **Warning**
> This is a warning

Becomes:

Note
This is a note

Warning
This is a warning

Let us know what you think and how this helps you provide better documentation. Please note that this is a beta feature that might be subject to change.

🐳

[Murderlon]

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
:::

:::warning
This is a warning
:::

This would mean:

• GH markdown is more compatible with other solutions.
• You aren't introducing yet another non-standard markdown feature
• It is more future proof. Directives are generic, future features could be added without inventing new syntax every time.

[colin-p-hill]

I'm wondering how everyone feels about the fact that it would potentially break backwards compatibility?

The currently implemented syntax results in Markdown files which are backwards incompatible with other/older renderers, while the alternatives suggested here do not.

As others have pointed out, using the <blockquote> element for this contradicts the semantic meaning of the element. GitHub can alter its implementation to instead use a <div> in this special case, but this does not solve the problem for renderers which do not implement this extension. They will continue to render the block as a <blockquote>, per Commonmark semantics.

That is, by choosing this syntax, GitHub will cause other renderers to yield semantically incorrect output. This is backwards incompatibility and a step away from interoperability. Reusing any existing syntax for semantically incompatible purposes is definitionally a breaking change.

The generic directive syntax, being wholly new, does not have this semantic incompatibility problem. Renderers which support the directive syntax but not this specific plugin will be able to fall back to a default <div>-based presentation which displays the name, attributes, and content without any particular semantics. Renderers which do not support the directive syntax will just show the colons, which is ugly, but which does not break any established semantics.

(And if you don't buy the argument that colons littering the text does not constitute backward incompatibility, consider this alternative argument: By adopting a generic syntax for extensions, GitHub would break backwards compatibility exactly once and then be able to reuse the feature for all future extensions. Under the current design, we get a backwards incompatibility from special-casing the meaning of the > syntax, and future extensions may still need to introduce further incompatibilities.)

The code block syntax, following Obsidian's conventions, is a dubious but defensible middle ground. Renderers which don't support the extension will just use <pre> and <code>, which respectively indicate "a block of preformatted text, in which structure is represented by typographic conventions rather than by elements"¹ and "a fragment of computer code"². Markdown content technically meets those definitions, but it's still a questionable use of the elements, because the author of a Markdown document intends the Markdown code inside the block to be rendered, not presented as code.

Footnotes

1. https://html.spec.whatwg.org/multipage/grouping-content.html#the-pre-element ↩

2. https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-code-element ↩

[spenserblack]

GitHub just made a blog post about the >[!NOTE] syntax and added it to their docs, so I guess the current syntax is here to stay 🤷

[meduzen]

I also made a blog post. 👼

[LuudJanssen]

We created a remark plugin to turn GitHub's syntax into the directive syntax: remark-github-admonitions-to-directives

This helped us reuse markdown files in Docusaurus docs.

[H0llyW00dzZ]

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

[lishid]

Would be cool if this can share the same syntax as Microsoft Docs "alerts" and Obsidian's "callouts".

MS Docs format [1]:
Supports types: NOTE, TIP, IMPORTANT, CAUTION, and WARNING.

> [!NOTE]
> This is a note. 

Obsidian format [2]:
Supported types: note, abstract, summary, tldr, info, todo, tip, hint, important, success, check, done, question, help, faq, warning, caution, attention, failure, fail, missing, danger, error, bug, example, quote, cite. Types are inspired from Material for MkDocs.

> [!Note] Callout can have an _optional_ title
> Callouts can also be nested:
> > [!Hint]- You can also create foldable callouts with `+` or `-`
> > This is hidden until unfolded.

[1]: https://docs.microsoft.com/en-us/contribute/markdown-reference#alerts-note-tip-important-caution-warning
[2]: https://help.obsidian.md/How+to/Use+callouts

[DerekNonGeneric]

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.

[klaudiagrz]

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

[HotCakeX]

Colors, more colores, yes

[okoyemmeso]

I agree to everything

[christopher3810]

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

[Andre601]

How about **Important** for very important information?
Could be useful in combination with Issue forms to get the attention of the user so that they know what to provide.

Edit: Also, to add to this, maybe extend this behaviour to other parts such as headers in block quotes? I like to use headers because of their larger font size, but right now are they not included in this.

[jsoref]

@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?

[MarcoSteinke]

@sinsukehlab

Just use a 2x1 table in wiki pages:

💡 Tip
I am a tip

⚠️ Warning
Do not read this.

[krystian3w]

Important

@RahulVerma989 (https://github.com/orgs/community/discussions/16925#discussioncomment-7024899) Changelog indicates that you can change the tables to quoting with a header at wiki if you do not nest them.

[krystian3w]

Screenshots for @sinsukehlab - works at wiki:

[sinsukehlab]

@krystian3w Yes, it also works at Wiki now.

Update - 12 October 2023

• Fix bug where alerts aren't rendered in Markdown file previews
• Add support for Wikis
• Fix various issues with nested blockquotes

[laymonage]

Thanks for this!

Any way to customize the text? It would be very useful for non-English documents.

[Wazbat]

I don't agree with using emojis instead of text as other suggest. I'd rather not have to go to google every time I want to type this if my device does not have a software emoji keyboard

[Crissov]

@Wazbat Since this is GFM, emoji shortcodes like :smile: are available as a workaround, although they – again – are English-only in many implementations. However, I’m not the only one who already mentioned ASCII art like <3 or classic emoticons like ;) and kaomoji like ^^ as a more international alternative.

[ljm12914]

Agreed strongly, from China.

[pboling]

@dipree said:

The idea is to take care of translation separately based on client preference.

This is an extremely bad idea. This isn't about client rendering. This is about forcing all authors of markdown on this platform to use English (and eventually all platforms, as whatever GFM implements will be adopted elsewhere). The feature is English-only, even if you translate on clients for readers.

PLEASE KILL THIS FEATURE.

[josevalim]

I don't believe the feature should be killed, it is an important feature (and clearly desired by many), but I agree with the concerns of it being English specific.

The original Markdown announcement said:

Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

With the current proposal, I can no longer write a document in Portuguese and use admonition blocks, without introducing English words such as TIP, CAUTION, etc. I'd say this goes directly against Markdown goals.

@dipree replied by saying (btw, thank you for leading this):

The idea is to take care of translation separately based on client preference.

The problem with this solution is that it brings complexity to Markdown rendering that does not exist today and it only solves half of the problem (rendering). It does not address the issue that the non-rendered Markdown document is now less expressive for non-English speakers.

@vassudanagunta already gave suggestions of how this could be tackled with Unicode, although such choice makes the document harder to write since you have to chase specific Unicode characters.

The most Markdown-like choice would be to choose specific characters for this, such as !!!:

> [!!!] Read this before continuing
>
> The flag `--danger` may wipe out your hard drive

One option, which has precedent in Markdown, is to rely on the number of characters to encode meaning, for example, ! means info, !! means warnings, and !!! means error. We could also explore different combinations of characters, such as !!! and ???.

I recognize it will be a challenge to find 5 different combinations with plain ASCII characters that are distinct and clear in meaning. We would need, at a bare minimum, to reduce the amount of styles to 3 or 4 (which would probably be enough anyway).

I am unsure what is the best answer here but we should at least discuss them. Enforcing English words in Markdown would be a regression. Thanks!

[YusukeHirao]

Why use the blockquote element?
The content is not always that is quoted from another source.

HTML Standard says:

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

[vassudanagunta]

@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.

[tom-sherman]

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.

[toastal]

The idea of GitHub-flavored Markdown changing the semantics of a <blockquote> is hilarious and also bad. This would mean your Markdown isn't supported elsewhere: CommonMark, GitLab-flavored Markdown, etc. Locking yourself into just GitHub will bite you in the future. This should not be done. > is for blockquotes and blockquotes quote content.

[Andre601]

Please Star this repo : https://github.com/shu6h4m/MicroSoft_Activator

Please do us a favour and don't shamelessly advertise your stuff nobody really has interest in.

[benjie]

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

[JonDouglas]

Would love to see more callouts too for different use-cases. These 5 below might be good to start with!

https://docs.microsoft.com/en-us/contribute/markdown-reference#alerts-note-tip-important-caution-warning

I'm not sure if this is only for documentation, but I would use it in general issues and other places supporting markdown. I would especially like to see one that is red in terms of "caution". That might be especially useful with enforcing a code of conduct when you've already provided a warning and would be generally helpful with RFCs(request for comments) about any major signs of caution.

[n1ckwhite]

👍🏻

[toastal]

Support any language

@vassudanagunta AsciiDoctor supports locales for the admonition labels

https://github.com/asciidoctor/asciidoctor/tree/main/data/locale

as well as icons

https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/#enable-admonition-icons

[vassudanagunta]

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

[toastal]

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

I don't know that you’d want icons in your plaintext as it could be ambiguous at times. Also given how many open bugs there are for CLI tools to remove the emoji from the terminal (it really does look out of place), maybe plaintext is the place to keep emojis out. 🤷

But maybe it could work …and has the advantage of being (somewhat) language agnostic. Some symbols like stop signs are more universal.

[toastal]

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

[eduardogerentklein]

How about Check for checked information?

[Kirtishukla2004]

use html text with css

[SleazeStiKs]

Tags like Important, Checked, Issue would be very useful. Having a tag for all states of progress

[Puckky66]

ควย

[Puckky66]

ควยปั๊ก

[Hezethegamer]

Check
This is OK

[carlocorradini]

The highlight stops working if it is indented (even if it is correctly identified as a quote).

Code:

### Build

1. Generate project

    > [!TIP]
    > Change build options' values as needed

Result:

[allejo]

I agree with the usage example in the OP; we do need alerts in bullets at the very least. Disabling alerts in all nested elements is a mistake; disabling them in some elements makes better sense.

[Snailedlt]

I don't see why it should be disabled inside any element tbh. GitHub flavored markdown shouldn't be so opinionated

[edeandrea]

I agree. Why would it be intentional?

[osslate]

As a technical writer by day, not allowing admonitions in lists is a giant usability let down both for me and for users. Moving a contextualized admonition out of the list item ruins the flow. See my comment here: https://github.com/orgs/community/discussions/16925#discussioncomment-9156825

Nesting admonitions this way is a common way to contextualize them within a procedure in docs. It'd be great if you could reconsider this limitation.

[Crissov]

GFM is build upon CommonMark and obviously breaks its Principle of Uniformity here:

if a chunk of text has a certain meaning, it will continue to have the same meaning when put into a container block (such as a list item or blockquote).

Therefore, this behavior is a bug, not a feature, even if intentional.

[Andrew6rant]

More customization is always nice. What if you could specify the Github's Octoicon, color, and text?

For example:

> **alert#9a6700;Warning**
> This is a warning

to render the alert octicon (https://primer.github.io/octicons/alert-16) with a hex color of #9a6700 and a text of "Warning":

Warning
This is a warning

[DerekNonGeneric]

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.

[NB-Dragon]

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。

[fearocanity]

Is it me? Or this isn't working inside the <details> tag? While back then is currently fine.

<details>
<summary>Click me!</summary>

> [!NOTE]
> Test

> [!WARNING]
> Test

> [!IMPORTANT]
> Test

</details>

Click me!

[!NOTE]
Test

[!WARNING]
Test

[!IMPORTANT]
Test

But works without the <details> tag

> [!NOTE]
> Test

> [!WARNING]
> Test

> [!IMPORTANT]
> Test

Note

Test

Warning

Test

Important

Test

---

Is GitHub cooking something disgusting again?

[sinsukehlab]

I'm afraid so.

[Puckky66]

Anek Patthaphong

[trusktr]

a bit of a bumpy road, but it'll be really great when this feature stabilizes!

[Hauteclere]

I, too, would really like to be able to use alerts nested inside other elements. A lot of the walkthroughs I write are quite long, and to avoid an intimidating wall of text I've been presenting substeps like so:

1.3.4 - Make The Commit

We are now ready to make our first commit! Here's the command:

git commit -m "initial commit"

[!NOTE]
The -m flag lets us add a "commit message" - a little explanation of what changes are in this commit. The text inside the quotation marks is the message. It's important to supply a message every time; try to be clear and succinct in your description.

In the meantime I'm going to have to revert to using emojis in regular blockquotes, which is... fine I guess 😞

@dipree I LOVE the admonition/alert syntax. I think you're moving in the right direction, and I will start using it as soon as nesting becomes possible!

[Hauteclere]

Side-note: just to be selfish for a second, the <details> blocks are awesome, but notice how when they're expanded you can't tell where they end? They would ascend to godly-tier if they had a slight background colour or border to indicate what is inside the expanded box and what is outside!!

[sinsukehlab]

Raw (syntax highlighting also has minor issues with "```")

## Update
- New types ([!TIP] and [!CAUTION] corresponding to the markdown renderer in Microsoft Learn) :rocket:

> [!TIP]
> This is a tip.

> [!CAUTION]
> This is a caution.

- MathJax expressions are now supported in alerts. :1234:

> [!NOTE]
> $\LaTeX$

- Code blocks nested in alerts can be copied now. :technologist:

> [!NOTE]
> ```
> git status
> ```

- Empty alerts are not allowed now.

> [!NOTE]<br>

- Alerts nested in blockquotes are not rendered now. :grimacing:

> This is a blockquote.
> > [!NOTE]
> > This is a note.

- Alerts nested in lists are not rendered now. :angry:
  > [!NOTE]
  > This is a note (broken).

- > [!NOTE]
  > This is a note (broken).

- No backward compatibility :rage:

> **Note**
> This syntax is deprecated now.

Update

• New types ([!TIP] and [!CAUTION] corresponding to the markdown renderer in Microsoft Learn) 🚀

Tip

This is a tip.

Caution

This is a caution.

• MathJax expressions are now supported in alerts. 🔢

Note

$\LaTeX$

• Code blocks nested in alerts can be copied now. 🧑‍💻

Note

git status

• Empty alerts are not allowed now.

[!NOTE]

• Alerts nested in blockquotes are not rendered now. 😬

This is a blockquote.

[!NOTE]
This is a note.

• Alerts nested in lists are not rendered now. 😠

  [!NOTE]
  This is a note (broken).

• [!NOTE]
  This is a note (broken).

• No backward compatibility 😡

Note
This syntax is deprecated now.

[andrewtavis]

You just need to remove the indentation to get it working, but I'd stress that it really would be great if we could stick with the current setup. These markers are helpful, but having to change them as much as I have has been an annoyance. Specifically when the task at hand is providing good documentation, something that already goes unnoticed, it would be great to not need to redo it so often.

[sinsukehlab]

I'm curious to hear what other GitHub staffs have to say about this update.
As far as I know, some Skills courses had used alerts in listed instructions before.

[sinsukehlab]

@dipree What prevents you from making the update process more democratic?

[oSumAtrIX]

Here is another example of how nested alerts are utilized heavily: https://github.com/ReVanced/revanced-cli/blob/main/docs/1_usage.md#-patch-an-app

[Snailedlt]

Would changing to a more common syntax (as exmplained in this comment) fix any issues for you guys?

For a new feature like this I feel like backwards compatability is less important than following a common standard. If that also helps you fix some bugs more easily I say go for it!

[lepture]

Bad design.

1. It is not semantic, block quote is not admonition
2. It is an English only feature.

Here is a RST example:

.. warning:: 注意

   This is the warning content, and 注意 is the caption.

[pboling]

Agree, it breaks semantic web, and is English-centric (Imperialist).

Additionally it snubs the existing Markdown RFC which would support this use case, and is already well on its way to becoming a standard.
#16925 (comment)

Breaking semantic web to add a feature is pretty abhorrent, and the more I think about it the worse this idea becomes...

[vassudanagunta]

Additionally it snubs the existing Markdown RFC

That is not an official RFC, but a user proposal made eight years ago on the CommonMark forum. Some of the ideas have been adopted or even predated by implementations such as Pandoc's fenced divs.

[PROxZIMA]

This syntax might hinder with what user actually wants to write

> **Note**
> This is a note

> **Warning**
> This is a warning

The user will expect this to be rendered as following because **text** is bold syntax.

Note
This is a note

Warning
This is a warning

Also is blockquote necessary here? It's more like overloading its basic functionality.

Others have proposed great alternatives like Microsoft Docs alerts and Obsidian's callouts in #16925 (comment) and remark-directive in #16925 (comment)

Here is my take on the syntax. Suggestions are welcomed.

--[!Note]
This is the subtext for Note
until line break, `<br>` occurs

--[!Warning] 
This is the subtext for Warning
until line break, `<br>` occurs

--[!Alert] 
This is the subtext for Alert
until line break, `<br>` occurs

[pboling]

There is a Markdown RFC for a standard that would support this already. Not sure why they didn't use it, but it would be better to collaborate with the Markdown spec than make GFM even more of a monster.
More: #16925 (comment)

[goyalyashpal]

i was thinking maybe (i) and /!\ can be used in some way too? to make it more strong and unambiguous - syntax wise

[Tyrrrz]

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:

[wooorm]

Soft breaks are not part of GFM. They work in comments/issues/prs/releases, but not in readmes/gists.
Comments/etc do use GFM, but they also add more, such as these softbreaks.

[borekb]

Well, if GFM says that linebreaks are parsed as soft line breaks but GitHub does something different in issues/PRs, I'd then argue that issues/PRs are not GFM-compliant.

The GFM spec (https://github.github.com/gfm/) is written by GitHub so they have every opportunity to clarify the situation but they don't, so in my eyes their rendering of comments/issues/PRs is just a different dialect of Markdown and not GFM, though it's close.

(BTW I know this discussion is purely academic 😄.)

[wooorm]

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.

[borekb]

I have to admit that I'm not as sure about the technical details or even terms like you are, but in laymen terms, if comments/issues/PRs started rendering two trailing spaces (line··) or a backslash (line\) as a soft line break, I'd say that they violate CommonMark / GFM. In my eyes, this is not an "addition" like the things you mentioned, this is a change in behavior.

But ok, it's the way it is, in the past I've spent quite some time browsing the "Writing on GitHub" section of their docs to find definitive answers but it's often quite fuzzy 🤷‍♂️.

I'm not entirely confident in their implementation either, for example, this new "Note" / "Warning" feature has a lot of strange rendering bugs like #123 not recognized within it, like if they didn't have tests around this or something which is very hard to believe.

[Andre601]

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

[ken-okabe]

Related to Murderlon on May 21

Check this out
https://www.npmjs.com/package/remark-admonitions

I also think for Markdown admonitions, the syntax:

:::keyword optional title
some content
::: 

:::tip pro tip
`remark-admonitions` is pretty great!
:::

is currently widely used in MDX, and I think it's a bad manner to overload blockquote syntax since it's against the fundamental design of HTML:

Definition and Usage

The <blockquote> tag specifies a section that is quoted from another source.

I believe the Google search engine also respects this principle.

Docusaurus(Facebook Open Source, and used for official FB docs) also adopts MDX with this syntax:

Version: 2.0.1 MDX and React
Admonitions

[pboling]

@dipree Please consider moving to this alternate approach ☝️

[blackace72]

This makes sense to avoid accessibility incompatibility.

[ken-okabe]

This thread is full of comments trying to GFM violating the standard HTML tag protocol, modern browswer behavior and search engines.

https://www.w3schools.com/html/html_quotation_elements.asp

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/q

@dipree

now render a special and accessible note or warning blockquote in Markdown documents. We are using the existing syntax for blockquote and bold text.

Does he or his team even understand what the "quote" means?

[ZanzyTHEbar]

Why does the rendering work here, but not on my github readme files? It used to work, now all of my readmes are not correctly rendering.

[Andre601]

https://github.com/orgs/community/discussions/16925#discussioncomment-6506860

[HotCakeX]

@dipree What would it take to make these 2 fundamental changes to admonitions?

1. Allow us to use custom colors using RGB code
2. Allow us to set any title for the admonitions

It will be perfect if you make these 2 changes and admonition will be feature complete without need for any further improvements because users will have freedom to choose any color and title they want.

[Andre601]

Given the reply here there seems to be some consideration for at least the custom title part.

The custom Colour one feels - at least for me - a bit out of place here...

[fearocanity]

Does it work when it is nested?

> [!NOTE]
> A Text
> > [!WARNING]\
> > hello

Output:

Note

A Text

[!WARNING]
hello

It appears that nesting is not supported.

[HotCakeX]

Was it supported before?

[sinsukehlab]

[!NOTE] nested in [!NOTE] has not been supported as far as I know. [!NOTE] nested in a quote was supported last week but is now out of support scope.

> [!NOTE]
> This is a note.
>> 
> [!NOTE]
> This will not be shown.

Note

This is a note.

[!NOTE]
This will not be shown.

[sinsukehlab]

It seems that this has recently been updated. Now shown.

[advaybot]

I wanted to say thanks for restoring the feature for now. I understand there are a variety of deficiencies, and I hope they are addressed as time goes by, but perfect is the enemy of good.

🎵 People throw rocks at things that shine 🎵

:)

[Yarakashi-Kikohshi]

proposal

The "ⓘ Note" displayed by [!note] is the same color as the text color of links. Even though attention is attracted by [!note], visual misinterpretation can occur because of color conflicts with links.

> **[ⓘ  Note](https://www.example.com)**
> This is NOT a Note!!

> [!note]
> This is a Note!

ⓘ Note
This is NOT a Note!!

Note

This is a Note!

I do not think this problem is solved by the different color of the vertical bar on the left side. I think you need to select different color than links.

[Andre601]

It still stands out for me, especially given the color on the left side is noticably brighter than the link colour.

At most people with issues in seeing certain colours could have a problem here, or maybe if you're using a different theme.

[Yarakashi-Kikohshi]

I am using uses "dark dimmed". The actual situation is as below.

It may be my personal problem that the difference is confusing, but even in this example I find the difference confusing. I would also like to wait for opinions of others.

[dipree]

Agreed that the colors are the same, however, the examples shown are far from reality I would say.

There is a completely different problem to links within text blocks. For accessibility reasons links must be visually distinguished from surrounding text through styling and not just color. For example, they could be underlined. We are looking into solutions to this problem.

[Yarakashi-Kikohshi]

@dipree, sorry for the delay in replying.

Certainly the example I gave was not realistic. However, I did not have an effective way to explain that the colors were similar and difficult to understand.
I am hoping that something will be changed so that there is a visual difference. 👀

[sinsukehlab]

Now all the links are underlined for A11Y.

[sinsukehlab]

https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts

[spikespaz]

Headings do not work inside these named blockquotes.

[!INFO]

List available modules

To see all the modules made available, run the command(s):

nix eval 'github:spikespaz/dotfiles#nixosModules' --apply 'builtins.attrNames'
# and
nix eval 'github:spikespaz/dotfiles#homeManagerModules' --apply 'builtins.attrNames'

[sinsukehlab]

[!INFO] is not supported.
Headings work in [!NOTE] quotes. "# > [!NOTE]" doesn't work.
The "# text" snippets are naturally considered to be comments in code blocks.

> [!NOTE]
> # This is an `<h1>` header.
> ## This is an `<h2>` header.
> ### This is an `<h3>` header.
> #### This is an `<h4>` header.
> ##### This is an `<h5>` header.
> ###### This is an `<h6>` header.
> This is a note.

Note

This is an <h1> header.

This is an <h2> header.

This is an <h3> header.

This is an <h4> header.

This is an <h5> header.

This is an <h6> header.

This is a note.

[spikespaz]

Not sure why I thought that, my mistake. Sorry!

[spikespaz]

Important

The primary reason I do this is because I want some of these notes to be referenced as a link,
or have an ID so that they can be used as a fragment specifier in the URL.

If there were another way to accomplish that, I'd care less about "naming" these notes with a heading.

Perhaps > [!NOTE](id-or-fragment-specifier) or similar.

Edit #3: Looks like linking is broken altogether inside these special blocks.

For stylized blockquotes with a heading, I would like to see the margin between the colored label and the heading be reduced. There is a very large gap.

> #[!NOTE]
> ### This is a Heading
>
> This is content

Produces something like:

And I think that this special case ought to be ignored when there is a hard break.

> #[!NOTE]
>
> ### This is a Heading
>
> This is content

---

Edit #4: I also would like to see [!TIP] which would be green instead of the blue [!NOTE].

[sinsukehlab]

> [!NOTE]
> ### This is a header.
> This is a content.

> [!NOTE]
> 
> ### This is a header.
> 
> This is a content.

> [!NOTE]\
> This is a note with `\` (outdated) and is rendered.\
> This is another line.

> [!NOTE]\
> ### When a header comes here, the highlight is not rendered.\
> This is a content.

> [!NOTE]  
> This is a note with double spaces (outdated) and is rendered.  
> This is another line.

> [!NOTE]  
> ### This is a header.  
> This is a content.

> [!NOTE]<br>
> This is a note with `<br>` (outdated) and is rendered with additional line breaks.<br>
> This is another line.

> [!NOTE]<br>
> ### This is a header.<br>
> This is a content.

Note

This is a header.

This is a content.

Note

This is a header.

This is a content.

Note

This is a note with \ (outdated) and is rendered.
This is another line.

[!NOTE]\

When a header comes here, the highlight is not rendered.\

This is a content.

Note

This is a note with double spaces (outdated) and is rendered.
This is another line.

Note

This is a header.

This is a content.

Note

This is a note with <br> (outdated) and is rendered with additional line breaks.

This is another line.

Note

This is a header.

This is a content.

[1chooo]

Important

Remember to synchronize and update your repository before starting to write code each time.

Does it only in the issue page or discussion page? Why not work in my README.md

[1chooo]

It work!
https://github.com/1chooo/ai-for-beginner

[sinsukehlab]

Has anyone tested the highlights in profile README.md?

[sinsukehlab]

mimic test

> [!NOTE]
> This is a note.

$\color{#0969da}\sf{Note}$
$\color{#0969da}\&#x24D8\sf{Note}$
$\color{#0969da}\bf{\&#x24D8}\sf{Note}$
$\color{#0969da}\bf{\&#x24D8}\kern{1 ex}\sf{Note}$
$\color{#0969da}{\large\bf{\&#x24D8}\kern{1 ex}}\sf{Note}$

- > [!NOTE]
  > $\color{#0969da}{\large\bf{\&#x24D8}\kern{1 ex}}\sf{Note}$

> $\color{#0969da}{\large\bf{\&#x24D8}\kern{1 ex}}\sf{Note}$
> This is a note.

Note

This is a note.

$\color{#0969da}\sf{Note}$
$\color{#0969da}&#x24D8\sf{Note}$
$\color{#0969da}\bf{&#x24D8}\sf{Note}$
$\color{#0969da}\bf{&#x24D8}\kern{1 ex}\sf{Note}$
$\color{#0969da}{\large\bf{&#x24D8}\kern{1 ex}}\sf{Note}$

• [!NOTE]
  $\color{#0969da}{\large\bf{&#x24D8}\kern{1 ex}}\sf{Note}$

$\color{#0969da}{\large\bf{&#x24D8}\kern{1 ex}}\sf{Note}$
This is a note.

[sinsukehlab]

> [!WARNING]
> This is a warning.

> $\color{#9a6700}{\large\bf{\&#x26A0}\kern{1 ex}}\sf{Warning}$
> This is a warning.

- > [!WARNING]
  > $\color{#9a6700}{\large\bf{\&#x26A0}\kern{1 ex}}\sf{Warning}$

Warning

This is a warning.

$\color{#9a6700}{\large\bf{&#x26A0}\kern{1 ex}}\sf{Warning}$
This is a warning.

• [!WARNING]
  $\color{#9a6700}{\large\bf{&#x26A0}\kern{1 ex}}\sf{Warning}$

[alexgwolff]

Important

This is a Important.

[sinsukehlab]

Now MathJax expressions are neither rendered in blockquotes unless nested in lists.

$\LaTeX$

> $\LaTeX$

> blockquote
> $\LaTeX$

- > $\LaTeX$

- > blockquote
  > $\LaTeX$

> [!NOTE]
> $\LaTeX$

- > [!NOTE]
  > $\LaTeX$

$\LaTeX$

$\LaTeX$

blockquote
$\LaTeX$

• $\LaTeX$

• blockquote
  $\LaTeX$

Note

$\LaTeX$

• [!NOTE]
  $\LaTeX$

[sinsukehlab]

• $\color{#9a6700}{\large\bf{&#x26A0}\kern{1 ex}}\sf{Warning}$
  GitHub is destroying Markdown!

[sinsukehlab]

Tip

tip

Caution

caution

[wojpawlik]

[!NOTE] Is the newline between the alert directive and the content required in Markdown files?

[sinsukehlab]

Yes, soft line breaks will suffice.

Note

This is a note.

[makbol]

When is it coming to Github Enterprise Server?

[jsoref]

Given that:

1. they still appear to be making dramatic changes to the syntax
2. there's no sign of documentation for this feature
3. they (apparently?) don't have it on the https://github.com/github/roadmap
   ... I'd hope not for a while.

[makbol]

Re: 2 - it’s mentioned in documentation https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts

[jsoref]

Hmm, then they really need to do some SEO? .. Sigh, ok. Filed: github/docs#27902

[jsoref]

As 3.10.0 was just released: https://docs.github.com/en/[email protected]/admin/release-notes#3.10.0 and doesn't appear to include this markdown feature: https://docs.github.com/en/[email protected]/admin/release-notes#markdown, i'd expect to see it in a 3.11 release. My naive guess would be November. This is based on the 3.*.0 releases on https://enterprise.github.com/releases.

[0333814695]

To better highlight and separate certain information from the rest in your documentation on GitHub, we now render a special and accessible note or warning blockquote in Markdown documents. We are using the existing syntax for blockquote and bold text.

Note
The first line must be exactly as shown below. The first letter is case sensitive. The second line can contain your content.

This input:

> **Note**
> This is a note

> **Warning**
> This is a warning

Becomes:

Note
This is a note

Warning
This is a warning

Let us know what you think and how this helps you provide better documentation. Please note that this is a beta feature that might be subject to change.

🐳

[kophyo1234]

Note
This is a note

Warning
This is a warning

[kubinka0505]

@sinsukehlab any way to color the left border color?

Important
<- this

[sinsukehlab]

You can't change the color.