How to create a good-looking notification or warning box in Github Flavoured Markdown?

Question

I am looking for something simple like triple backticks, but that still allows other markdown syntax inside.
This is not the case for triple backticks, since it is used for code blocks:

**NOTE:**
Find the docs [here](http://example.com/).

Everything inside is taken literally, so it is not possible to use other markdown features inside, like links or bold text ...

Is there any syntax or feature in markdown that enables such notification boxes?

Answer 1

GitHub has a specific syntax to create warning boxes. See the Github Discussion Page for more information.

> [!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.

Answer 2

As Waylan mentions in his answer, Github strips script and style tags from the markdown before displaying it. This means the only possibilities for notification boxes that will render on Github are those provided by native markdown or html.

After some searching and experimenting, I discovered it is possible to (ab)use the tables syntax,
and combine it with Github emoji markdown.

For example:

• Boxes from a single cell table:

  | :exclamation:  This is very important   |
  |-----------------------------------------|
  
  
  | :zap:        Ignore at your own risk!   |
  |-----------------------------------------|
  

  

• Boxes from a single row table with 2 cells:

  | :memo:        | Take note of this       |
  |---------------|:------------------------|
  
  
  | :point_up:    | Remember to not forget! |
  |---------------|:------------------------|
  

  

• Boxes from a 2 row table:

  | :warning: WARNING          |
  |:---------------------------|
  | I should warn you ...      |
  
  
  | :boom: DANGER              |
  |:---------------------------|
  | Will explode when clicked! |
  

  

Note that markdown tables do not allow newlines, so you should use <br /> tags if you need multiple lines inside the box. In this case it might be simpler to directly use the html <table> tag, since it doesn't have this newline restriction. It also allows getting rid of the bold styling of the table header <thead> by replacing its <th> tags with <td> tags:

<table>
  <thead>
    <tr>
      <td align="left">
        :information_source: Information
      </td>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <ul>
          <li>Tis not true.</li>
          <li>I won't explode.</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

Answer 3

Is there any syntax or feature in markdown that enables such notification boxes?

Yes, you can use raw HTML. As the original rules explain:

HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

Therefore, styling a warning box around some text is out-of-scope for Markdown as that is a publishing concern, not a writing concern. However, as the ruled continue:

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself.

An as you are using Github Flavored Markdown, you get the added benefit that when formatted properly, you can still have Markdown processed within the block level raw HTML tags (so long as the parser you are using is compliant with the spec). As the spec explains, Markdown is processed within a raw HTML block after the first blank line. So simply include a blank line after the opening raw HTML tag and you won't have any issues.

<div class="warning">

**NOTE:**
Find the docs [here](http://example.com/).

</div>

Of course, you will also need to define what your warning block looks like. In the above example, I assigned the warning class to the wrapping <div> tag. Some CSS would also need to be defined within the document (in a <style> tag) to style any <div> which has the warning class.

Alternatively, if you only have one warning box in your document, you could define the styles in an inline style attribute: <div style="..."> (replacing ... with the actual CSS rules).

Warning!

A word of caution though. If you plan to have your document rendered and hosted on github.com, this will not work. While GitHub's Markdown parser will work as described above, GitHub also does some postprocessing for security reasons (as documented at github/markup). The sanitation filter they use will strip out all styles (inline or not). In that case, there is no option available. The same applies here on StackOverflow.