190

I am trying to make a Markdown admonition box such as note box, warning box for GitHub Gist. I do some search on Google I find Python markdown admonition but these admonitions don't seem to work on GitHub Gist.

I have tried following Python warning admonition But this markdown syntax doesn't work on GitHub Gist.

!!! Hello Admonition

I also tried bootstrap boxes like this but it does not have style as expected:

<div class="alert alert-danger" role="alert">
    <div class="row vertical-align">
        <div class="col-xs-1 text-center">
            <i class="fa fa-exclamation-triangle fa-2x"/>
        </div>
        <div class="col-xs-11">
            <strong>Error:</strong>
        </div>
    </div>
</div>

Is there any admonition syntax or HTML code method for GitHub Gist?

3

11 Answers 11

304

Use emoji to call the user attention

> :warning: **If you are using mobile browser**: Be very careful here!

Github example

Here is list of others emojis (just copy paste):

https://gist.github.com/roachhd/1f029bd4b50b8a524f3c

Or you can also use GitHub markdown:

https://gist.github.com/rxaviers/7360908

11
  • 5
    FWIW, to get the yellow / emoji version of the Unicode warning sign, follow it with the "variation selector-16" character (eg. via HTML entity refs: &#x26a0;&#xfe0f;). Sep 24, 2019 at 17:29
  • 9
    Rather than the tediousness required in finding, copying, and pasting the emoji character itself, you can simply use :warning:
    – Swivel
    Oct 14, 2019 at 15:41
  • 2
    @Swivel Thank you for the suggetion, I had change my answer to have that github markdown. Oct 14, 2019 at 19:28
  • 3
    @shamaseen This will only work with GitHub Markdown, iirc. If you're using a different Markdown processor that doesn't support GH emoji's, it might not work.
    – Swivel
    Aug 5, 2021 at 18:51
  • 2
    Don't do this. > is for blockquotes. "The blockquote element represents a section that is quoted from another source." according to W3C. Since you're not quoting anything, this is the wrong element. If you want admonitions, both AsciiDoc and reStructured Text support admonitions. There's also an open RFC for admonitions in CommonMark.
    – toastal
    Jul 16, 2022 at 8:57
121

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.

Note:
In Markdown files, a hard line break can be achieved with two spaces [!NOTE] , a backslash [!NOTE]\ or html [!NOTE]<br>

An example of all three types (with two spaces after the ] ):

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

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

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

Here is how they are displayed:

highlights


May 2022, original answer:

While not exactly an admonition, this is supported (beta tested) since May 2022, as reported by Diego Haz and described in discussion 16925

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.

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 and Warning / This is a warning

Warning: the syntax might still evolve and is debated in the discussion. For instance, Brenton M. Wiernik comments:

In addition to syntax issues and semantic web problems raised by others, I am also concerned about this introducing a major incompatibility between GitHub-Flavored Markdown and pandoc markdown or CommonMark.

A large number of R developers write READMEs and other documentation in RMarkdown, which is generally processed using pandoc.

This change would mean that users would be unable to get consistent rendering with the same syntax when their package documentation is displayed on GitHub vs elsewhere.

Overloading the blockquote in this way creates an opaque difference in the meaning of syntax across markdown flavors that is very difficult to write around for developers.


With VSCode, Ian Sanders proposes:

Here's some VSCode snippets to make it easier to remember

{
    "Note": {
        "prefix": "note",
        "body": [
            "> [!NOTE]",
            "> $1"
        ],
        "description": "GFM Note block"
    },
    "Important": {
        "prefix": "important",
        "body": [
            "> [!IMPORTANT]",
            "> $1"
        ],
        "description": "GFM Important block"
    },
    "Warning": {
        "prefix": "warning",
        "body": [
            "> [!WARNING]",
            "> $1"
        ],
        "description": "GFM Warning block"
    }
}
6
  • 1
    You need to add <br> after the **Warning** to have it on two lines.
    – Ramtin
    Nov 18, 2022 at 7:25
  • 4
    @Ramtin If it follows the markdown convention, adding two trailing spaces after Warning should enable the br.
    – VonC
    Nov 18, 2022 at 7:28
  • As of mid-July 2023, either of the above works.
    – Christian
    Jul 11 at 19:10
  • 1
    Note that they changed the syntax since the above was written. See the post for details. TLDR the new syntax is [!WARNING] (yes, those are two spaces after the closing bracket - they are required).
    – scode
    Jul 27 at 8:04
  • 1
    Note that the Warning box might not appear in the previewer when editing a markdown file. They only appeared in my README file after committing changes.
    – Prid
    Sep 21 at 22:36
100

You can make a box with some bold text in by using tables, like so:

| WARNING: be careful to baz the quux before initializing the retro encabulator! |
| --- |

This renders like this:

An image of a single-cell table, containing the text "WARNING: be careful to baz the quux before initializing the retro encabulator!"

It's a bit of an abuse of syntax, but it works. There's unfortunately no way to apply other formatting like colours, as Chris noted.

3
  • For some reason the amount of hyphens determines the width of my box! (so I spread many through and solved the issue) But still, why does this happen?
    – nilon
    Sep 2, 2019 at 13:54
  • 1
    A single cell table with an emoji "icon" looks great, e.g. <table><td>:warning: Don't do that!</td></table> is straightforward and looks good. You can also include regular markdown inside. Sep 25, 2022 at 13:25
  • Abuse of the Markdown syntax, but tables don’t have a lot of semantic meaning (remember when we used tables for everything pre-CSS?). The output HTML is fine enough. This is a good option if you must due to restrictions make due with Markdown and/or can’t control the platform’s CSS.
    – toastal
    Sep 5 at 9:44
71

Most repositories I've been a part of use the blockquote to simulate an admonition:

> **WARNING**: Be careful, or else!

Below is an example of it being used at the top, as well as inside, a section:

enter image description here

3
  • This isn't semantic markup and should be avoided.
    – toastal
    Jul 16, 2022 at 8:59
  • There are a few options worth considering: 1. use AsciiDoc or reStructuredText as both have admonition syntax built-in & if rendering on a forge/snippets is a requirement, both are supported on popular forges like Codeberg, GitLab, & GitHub—with Gitea being small config add & SourceHut can POST arbitrary HTML to a README so script a transformation. 2. all caps is fine (e.g. DANGER: text); bold if needed 3. if GitHub is going to ignore the CommonMark RFC for directives & roll out admonitions via unsemantic blockquotes in their flavor fork (no support outside GitHub), then don't use GitHub.
    – toastal
    Jul 20, 2022 at 6:07
  • 1
    The really annoying thing is that RST has admonitions, but GitHub doesn't render them as such. However, the beta feature does render these blockquote admonitions when entered in RST.
    – Nick K9
    Jul 29, 2022 at 19:25
34

In standard markdown using the UTF8 symbol this looks pretty good:

> **⚠ WARNING: Aliens are coming.**  
> A description of the colour, smell and dangerous behaviour of the aliens.

Which Renders like this:

⚠ WARNING: Aliens are coming.
A description of the colour, smell and dangerous behaviour of the aliens.

1
  • NOTE: Looking good ≠ semantic
    – toastal
    Jul 18, 2022 at 3:19
8

GitHub Flavored Markdown doesn't have anything like that and its HTML, generated or inline, is aggressively sanitized.

You'll likely have to make do with the basics, e.g.

_**Warning:** Be very careful here._

or

### Warning

Be very careful here
6

Easiest way:

| This project was moved and hosted on Render. |
|----------------------------------------------|

Will result in:

This project was moved and hosted on Render.
0
5

You can use tables or quotes (tested on Gitlab and Github only):

Using table

| ⚠️ Warning                               | 
|------------------------------------------|
| You shouldn't. This is irreversible!     |

| ❌ Error                                 | 
|------------------------------------------|
| Don't do that. This is irreversible!     |

| ℹ️ Information                           | 
|------------------------------------------|
| You can do that without problem.         |

| ✅ Success                               | 
|------------------------------------------|
| Don't hesitate to do that.               |

| 🦄 New line support                       | 
|-------------------------------------------|
| It supports new lines:<br/>.. simply use `<br/>` for new lines|

Abominations using tables

Using quote


> **⚠️ Warning**
>
> You shouldn't. This is irreversible!

> **❌ Error**
>
> Don't do that. This is irreversible!

> **ℹ️ Information**
>
> You can do that without problem.

> **✅ Success**
>
> Don't hesitate to do that.

> **🦄 New line support**
> 
> It supports new lines:
>
> .. simply use an empty `>` line
>

Abominations using quotes

1

You can use an SVG with the appropriate colored icon and text. For example, the code

> <picture>
>   <source media="(prefers-color-scheme: light)" srcset="https://github.com/Mqxx/GitHub-Markdown/blob/main/blockquotes/badge/light-theme/warning.svg">
>   <img alt="Warning" src="https://github.com/Mqxx/GitHub-Markdown/blob/main/blockquotes/badge/dark-theme/warning.svg">
> </picture><br>
>
> Warning

yields

enter image description here

Several more examples may be found here.

Compared to Github's beta solution, this solution won't break if Github walks back the proposed syntax. However, it will break if the repo goes down; though you could of course clone it. Also since it's an SVG, you can't ctrl + f and search for warning.

-1

Material for MkDocs provides several different types of admonitions and allows for the inclusion and nesting of arbitrary content.

First, you should configure:

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

Then, you can use admonitions in markdown:

!!! note

  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
  nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
  massa, nec semper lorem quam in massa.

Source: https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types

4
  • 1
    While this link may answer the question, it is better to include the essential parts of the answer here and provide the link for reference. Link-only answers can become invalid if the linked page changes. - From Review Oct 21, 2021 at 11:22
  • 2
    The link points to documentation for mkdocs-material, not for GitHub Flavored Markdown. Nov 5, 2021 at 12:26
  • But I using like this in markdown file and working :::tip INFO Lorem Ipsum is simply dummy text ::::
    – ufukcam
    Nov 6, 2021 at 15:24
  • It is related to MkDocs but according to ufukcam's comment I decided to preserve this post.
    – boj
    Jun 1, 2022 at 15:34
-19

A simple highlighted warning can be achieved like this:

>[!WARNING]
>This is a warning

This is what it looks like:

3

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.