How to make a styled Markdown admonition box in a GitHub Gist?

Question

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"></i>
        </div>
        <div class="col-xs-11">
                <strong>Error:</strong>                   
        </div>   
    </div> 
</div>

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

The closed [github issue on admonitions](https://github.com/github/markup/issues/68). — toraritte, Sep 29 '19 at 15:49
[Related question](https://stackoverflow.com/questions/25654845/how-can-i-create-a-text-box-for-a-note-in-markdown). — young_souvlaki, Jan 26 '22 at 17:41
This is somewhat [supported in 2022 by GitHub GFM](https://stackoverflow.com/a/72327818/6309). — VonC, May 21 '22 at 08:19

Tiago Mendes · Answer 1 · 2019-10-14T19:24:19.703

291

Use emoji to call the user attention

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

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

edited Oct 14 '19 at 19:24

answered Jul 19 '19 at 19:48

Tiago Mendes

4,572
1
29
35

4

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: `⚠️`). – anthonyrisinger Sep 24 '19 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 '19 at 15:41
2

@Swivel Thank you for the suggetion, I had change my answer to have that github markdown. – Tiago Mendes Oct 14 '19 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 05 '21 at 18:51
Can you please add reference to other `:code:` so that we can refer. – Rajesh Swarnkar Feb 16 '22 at 07:16
1

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 '22 at 08:57
@toastal I think you may have misunderstood the question. This question is not in regards to Markdown, but GitHub.com specifically. Unfortunately, until GitHub adds support for admonitions, there aren't many alternatives. Alternatives like AsciiDoc, reStructured, and others aren't supported. In fact the OP references Python Markdown, which supports admonitions. Currently, there is no _semantic_ way of displaying an Admonition. The function, however, is to bring attention, which most of these do. – Swivel Jul 19 '22 at 04:32
Here is a Gist on github.com with admonitions rendered via AsciiDoc and reStructuredText https://gist.github.com/toastal/0a3ea8d0fcc882df90bbc906b6437f1c Is the render pretty? Not really, but that's GitHub's fault for doing a bad job with CSS. As a user you can choose to host your code elsewhere that *does* better support admonitions with styling. And with the alternatives being open source, you can submit a patch to fix the styling if it's missing and the devs would likely welcome the contribution. – toastal Jul 20 '22 at 06:16
@toastal That's great! I'm sure your suggestions would be a welcome alternative as an answer. Unfortunately, not everyone has that choice, but at least its an option. Obviously, continuing to petition Github for these sorts of features is probably the best option, rather than downvoting those who are trying to make due with what potentially may be dictated by their circumstances. For those that do have the option to choose, you seem to have a plethora of advice that would be very well suited for an answer. I say post it! :+1: – Swivel Jul 30 '22 at 04:40
1

⚠️here the unicode char to copy, if `:warning:` does not work for you :) – Hannes Schneidermayer Jan 31 '23 at 14:56

VonC · Answer 2 · 2023-07-27T08:26:20.233

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:

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:

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.

You need to add `
` after the `**Warning**` to have it on two lines. — Ramtin, Nov 18 '22 at 07:25
@Ramtin If it follows the markdown convention, adding two trailing spaces after Warning should enable the br. — VonC, Nov 18 '22 at 07:28
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 '23 at 08:04
@scode Thank you for this feedback and update. I have edited the answer to include the new syntax and new keywords. — VonC, Jul 27 '23 at 08:27

score 98 · Answer 3 · answered May 26 '18 at 23:55

98

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:

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.

answered May 26 '18 at 23:55

ash

5,139
2
27
39

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 02 '19 at 13:54
1

A single cell table with an emoji "icon" looks great, e.g. `
:warning: Don't do that!
` is straightforward and looks good. You can also include regular markdown inside. – patricksurry Sep 25 '22 at 13:25

score 71 · Answer 4 · edited Jun 02 '21 at 15:04

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:

edited Jun 02 '21 at 15:04

Sergio Tulentsev

226,338
43
373
367

answered Apr 25 '19 at 13:33

Swivel

3,020
26
36

This isn't semantic markup and should be avoided. – toastal Jul 16 '22 at 08: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 '22 at 06: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 '22 at 19:25

score 33 · Answer 5 · answered Oct 08 '20 at 00:40

33

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.

answered Oct 08 '20 at 00:40

Greemo

449
4
3

NOTE: Looking good ≠ semantic – toastal Jul 18 '22 at 03:19

score 8 · Answer 6 · answered May 26 '18 at 22:46

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

answered May 26 '18 at 22:46

ChrisGPT was on strike

127,765
105
273
257

score 6 · Answer 7 · answered Jan 16 '23 at 06:45

6

Easiest way:

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

Will result in:

This project was moved and hosted on Render.

answered Jan 16 '23 at 06:45

Vidarshan Rathnayake

484
1
10
20

Xamrix · Answer 8 · 2023-07-24T15:18:29.873

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|

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
>

score 1 · Answer 9 · answered Mar 27 '23 at 20:18

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

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.

score -1 · Answer 10 · edited Jun 01 '22 at 15:32

-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

edited Jun 01 '22 at 15:32

boj

10,935
5
38
57

answered Oct 20 '21 at 22:04

ufukcam

93
6

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](/review/late-answers/30133797) – alparslan mimaroğlu Oct 21 '21 at 11:22
2

The link points to documentation for mkdocs-material, not for GitHub Flavored Markdown. – Adrian Schmidt Nov 05 '21 at 12:26
But I using like this in markdown file and working :::tip INFO Lorem Ipsum is simply dummy text :::: – ufukcam Nov 06 '21 at 15:24
It is related to MkDocs but according to ufukcam's comment I decided to preserve this post. – boj Jun 01 '22 at 15:34

score -18 · Answer 11 · edited May 26 '20 at 19:26

-18

A simple highlighted warning can be achieved like this:

>[!WARNING]
>This is a warning

This is what it looks like:

edited May 26 '20 at 19:26

ByteHamster

4,884
9
38
53

answered Nov 12 '19 at 14:16

T.Harms

43
4

12

In GitHub this looks nothing like the picture you linked to. – cueedee Apr 09 '20 at 08:15
1

I don't even know which website has this styling for warnings... Is it custom CSS? – RafazZ Jul 08 '20 at 00:49
4

^ https://learn.microsoft.com/en-us/contribute/markdown-reference – Rohit Mistry Sep 15 '20 at 11:30

How to make a styled Markdown admonition box in a GitHub Gist?

11 Answers11

Using table

Using quote

Linked

Related