340

I am writing a document in markdown. I am using the wonderful pandoc to create docx and tex files from the markdown source. I would like to have a textbox for tips and notes to readers the way programming books often do. I cannot figure out how to do this in markdown. Can you help?

3
  • Microsoft uses their own syntax for this in their documentation, but it isn't likely to work in your environment. Included here for completeness and comparison to the answers below. github.com/MicrosoftDocs/PowerShell-Docs/blob/staging/… Commented Nov 29, 2019 at 20:06
  • Related question. Commented Jan 26, 2022 at 17:42
  • also see github's alerts Commented Jan 21 at 8:24

17 Answers 17

429

With GitHub, I usually insert a blockquote.

> **_NOTE:_**  The note content.

becomes...

NOTE: The note content.

Of course, there is always plain HTML...

Sign up to request clarification or add additional context in comments.

9 Comments

I prefer this universal solution. I also enjoy using Unicode emojis to prefix the note, such as > ℹ️ This is an information or > ⚠️ This is a warning.
This and the table kludge are the only answers portably solving this question. The hard rule kludge proposed by the top answer fails to show a box and thus fails to solve this question. Indeed, this answer coupled with @pierre_loic's Unicode icons mod mostly replicates reStructuredText notes.
Strictly speaking, this is also not a "box". I think the "only" answer would be plain HTML as @Vlad mentioned. Visually, I prefer the "quoting" solution. However, contextually it may not be consistent with the other parts of the document. The gray horizontal line is associated with quoting in the document. What if I quote a note from somewhere else...
How can we have an ordered list (steps) inside this Note?
Add ⓘ to render the info icon. So > **ⓘ** The note text
|
249

What I usually do for putting alert box (e.g. Note or Warning) in markdown texts (not only when using pandoc but also every where that markdown is supported) is surrounding the content with two horizontal lines:

---
**NOTE**

It works with almost all markdown flavours (the below blank line matters).

---

which would be something like this:


NOTE

It works with all markdown flavours (the below blank line matters).


The good thing is that you don't need to worry about which markdown flavour is supported or which extension is installed or enabled.

EDIT: As @filups21 has mentioned in the comments, it seems that a horizontal line is represented by *** in RMarkdown. So, the solution mentioned before does not work with all markdown flavours as it was originally claimed.

3 Comments

This is useful, but it doesn't work with RMarkdown/Rstduio/Knitr
bjw - a horizontal line in rmarkdown is *** preceded by a blank line. Alternatively, you can put the note in a blockquote by starting the line with > (also preceded by a blank line).
I like this the best, but with **NOTE:** on the same line as the text. Adding a preceding > boxes the note in on 3 sides, but also grays the font.
54

I usually insert a blockquote and add a Unicode character(memo📝 which is(U+1F4DD)) inside it.

📝 ...

Syntax Demo
> 📝 bla bla ...

📝bla bla ...

> ``📝`` bla bla

📝 bla bla

> *📝* bla bla

📝 bla bla


Emoji

Of course, if you do not like 📝 you can search you like. I am sure there will be one in it is your satisfaction!

  • find more emoji: https://emojipedia.org/

    just search you like icon and copy-paste then done(since it is a character, so it suitable for every device)

  • find Code

    If you don't like copy paste and want to type yourself, you can consider searching the Unicode.

    !


p.s. You can also pay attention to the emoji version (usually it is the same as the Unicode version), and more icons may appear in the future to your satisfaction.

Optional Reading

The following content is optional to read

  • GitHub Alerts
  • Neovim ga
  • Nerd Fonts

GitHub Alerts

If you're using it for markdown files on GitHub, these work quite well:

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

enter image description here

reference:

Neovim ga

If you want to find Unicode code points and you're using the neovim,

You can simply use ga in normal mode to see decimal, hexadecimal, and octal results, saving you from having to look up Unicode code points.

📝U+1f4dd

enter image description here

Nerd Fonts

If you're looking for a font with many icons, consider: Nerd Fonts

https://github.com/ryanoasis/nerd-fonts/releases/download/v3.3.0/FiraCode.zip

For example, using: FiraCodeNerdFontMono-Retina.ttf

2 Comments

This works well until you have to generate a PDF and the font you are using doesn't include this emoji ([WARNING] Missing character: There is no 📝 (U+1F4DD) in font DejaVu Sans/OT:script=latn;language=df)
In case anyone doesn't know, the raw text should be: 📝
28

The following methods work on GitHub, on GitLab... and on Stackoverflow, which now uses CommonMark!


> One-Line Box made with Blockquote

One-Line Box made with Blockquote


`One-Line Box made with Backticks`

One-Line Box made with Backticks


```
Box made with Triple Backticks
```

Box made with Triple Backticks  


~ ~ ~
Box made with Triple Tildes
(remove the spaces between the tildes to make this work)
~ ~ ~

Box made with Triple Tildes


Box made with Four Spaces at the start of each line:

    “Sometimes we must let go of our pride and do what is requested of us.”
    Padmé Amidala


... or use horizontal lines?

Three dashes (---) make a horizontal line:


Note: “ Your focus determines your reality.” – Qui-Gon Jinn.


For more configurations, I strongly advise the excellent GitLab Markdown Guide.
You can also check the less detailed GitHub basic formatting syntax.
You can compare Markdown implementations using Babelmark.

Useful hints :

  • to force a newline, put two spaces at the end of the line;

  • to escape special characters, use \.

1 Comment

"backtick boxes" use a mono font, which is of course what you want for a code block, but not for an "info box"
26

As of Sept 2021 :
Here's one way of building a text box in markdown using html div tag and class 'warning'. It works beautifully in Jupyter Notebook and Typora. You can modify the background and font colors.

<div class="warning" style='padding:0.1em; background-color:#E9D8FD; color:#69337A'>
<span>
<p style='margin-top:1em; text-align:center'>
<b>On the importance of sentence length</b></p>
<p style='margin-left:1em;'>
This sentence has five words. Here are five more words. Five-word sentences are fine. But several together bocome monotonous. Listen to what is happening. The writing is getting boring. The sound of it drones. It's like a stuck record. The ear demands some variety.<br><br>
    Now listen. I vary the sentence length, and I create music. Music. The writing sings. It has a pleasent rhythm, a lilt, a harmony. I use short sentences. And I use sentences of medium length. And sometimes when I am certain the reader is rested, I will engage him with a sentence of considerable length, a sentence that burns with energy and builds with all the impetus of a crescendo, the roll of the drums, the crash of the cymbals -- sounds that say listen to this, it is important.
</p>
<p style='margin-bottom:1em; margin-right:1em; text-align:right; font-family:Georgia'> <b>- Gary Provost</b> <i>(100 Ways to Improve Your Writing, 1985)</i>
</p></span>
</div>

enter image description here

OR (adding a bit more to the design - rounded corners and border)

<div class="warning" style='background-color:#E9D8FD; color: #69337A; border-left: solid #805AD5 4px; border-radius: 4px; padding:0.7em;'>
<span>
<p style='margin-top:1em; text-align:center'>
<b>On the importance of sentence length</b></p>
<p style='margin-left:1em;'>
This sentence has five words. Here are five more words. Five-word sentences are fine. But several together bocome monotonous. Listen to what is happening. The writing is getting boring. The sound of it drones. It's like a stuck record. The ear demands some variety.<br><br>
    Now listen. I vary the sentence length, and I create music. Music. The writing sings. It has a pleasent rhythm, a lilt, a harmony. I use short sentences. And I use sentences of medium length. And sometimes when I am certain the reader is rested, I will engage him with a sentence of considerable length, a sentence that burns with energy and builds with all the impetus of a crescendo, the roll of the drums, the crash of the cymbals -- sounds that say listen to this, it is important.
</p>
<p style='margin-bottom:1em; margin-right:1em; text-align:right; font-family:Georgia'> <b>- Gary Provost</b> <i>(100 Ways to Improve Your Writing, 1985)</i>
</p></span>
</div>

enter image description here

4 Comments

Totally off-topic: this quote form Gary Provost is amazing!
This is technically correct, since markdown basic syntax allows the use of raw HTML... but you are suggesting to make a markdown infobox by not using markdown at all XD XD
Hi! This works wonderfully with html, but if I knit it to word, the colours and formatting disappear! Do you have any suggestions on how to make it work?
Feels like an aside tag would be a better fit than div IMHO
23

The simplest solution I've found to the exact same problem is to use a multiple line table with one row and no header (there is an image in the first column and the text in the second):

----------------------- ------------------------------------
![Tip](images/tip.png)\ Table multiline text bla bla bla bla
                        bla bla bla bla bla bla bla ... the
                        blank line below is important 

----------------------------------------------------------------

Another approach that might work (for PDF) is to use Latex default fbox directive :

 \fbox{My text!}

Or FancyBox module for more advanced features (and better looking boxes) : http://www.ctan.org/tex-archive/macros/latex/contrib/fancybox.

1 Comment

Do you know if it is possible to define how the pandoc-markdown note will look like inside the pandoc template file? For example, editing ~/.pandoc/templates/default.latex ?
21

I didn't see the below format listed here yet. It works both in github and obsidian. Looks also pretty =)

> [!EXAMPLE]
> this is an example
> [!NOTE]
> This is a note

Example where it works in github: https://github.com/tasmota/docs-7.1/blob/master/Commands.md

2 Comments

Thank you! This syntax is buried in the various docs, and clearly not well known given the makeup of the answers here.
Do you know if this is still working? at least for me, it fails to work since a couple of weeks and I am not sure why. Cannot find any docs on it.
19

Use the admonition extension. For mkdocs, it can be configured in the mkdocs.yml file:

markdown_extensions:
    - admonition

Then insert the note in your md files as follows:

!!! note

     This is a note.

See an example here.

Comments

9

Here's a simple latex-based example.

---
header-includes:
    - \usepackage[most]{tcolorbox}
    - \definecolor{light-yellow}{rgb}{1, 0.95, 0.7}
    - \newtcolorbox{myquote}{colback=light-yellow,grow to right by=-10mm,grow to left by=-10mm, boxrule=0pt,boxsep=0pt,breakable}
    - \newcommand{\todo}[1]{\begin{myquote} \textbf{TODO:} \emph{#1} \end{myquote}}
---

blah blah

\todo{something}

blah

which results in: enter image description here

Unfortunately because this is latex, you can no-longer include markdown inside the TODO box (which is not a huge problem, usually), and it won't work when converting to formats other than PDF (e.g. html).

Comments

9

Have you tried using double tabs? To make a box:

Start on a fresh line
Hit tab twice, type up the content
Your content should appear in a box

It works for me in a regular Rmarkdown document with html output. The double-tabbed portion should appear in a rounded rectangular light grey box.

2 Comments

Works on VS Code and GitHub too!
Two tabs does not "make a box" per se, it is for "preformatted text": stackoverflow.com/editing-help#code
9

Similar to Etienne's solution, a simple table formats nicely:

| | |
|-|-|
|`NOTE` | This is something I want you to notice. It has a lot of text, and I want that text to wrap within a cell to the right of the `NOTE`, instead of under it.|

Another alternative (which comes with more emphasis), is to make the content the header of a body-less table:

|`NOTE` | This is something I want you to notice. It has a lot of text, and I want that text to wrap within a cell to the right of the `NOTE`, instead of under it.|
|-|-|

Finally, you can include a horizontal line (thematic break) to create a closed box (although the line style is a little different than the header line in the table):

| | |
|-|-|
|`NOTE` | This is something I want you to notice. It has a lot of text, and I want that text to wrap within a cell to the right of the `NOTE`, instead of under it.|

---

Note the empty line after the text.

1 Comment

I like this solution a lot, but when I convert this via pandoc and xelatex to pdf, it seems that it allocates 50% for the "NOTE" column, and 50% for the other one; one can use multiline tables as per stackoverflow.com/questions/27219629 - but then there are other formatting problems.
6

You may also use https://www.npmjs.com/package/markdown-it-container

::: warning
*here be dragons*
:::

Will then render as:

<div class="warning">
   <em>here be dragons</em>
</div>

1 Comment

pandoc supports customised div now, see Divs and Spans, pandoc
5

Another solution is to use CSS adjacency and use h4 (or higher):

#### note

This is the note content
h4 {
  display: none; /* hide */
}

h4 + p {
  /* style the note however you want */
}

Comments

5

single line

> hello
> world

hello world

multi line

method a

> hello
> 
> world (new line)

hello

world (new line)

method b

> ```shell
> echo hello
> echo world
> ```

echo hello
echo world

Comments

3

Here is a haskell filter for warning and tips.

Useful for latex and PDF output.

#!/usr/bin/env runhaskell
{-# LANGUAGE OverloadedStrings #-}
import Text.Pandoc.JSON
import Data.Text

latex::Format
latex = Format "latex"

highlight :: Block -> IO Block
highlight cb@(Div (id, (cls:_), _) (contents:_)) =
   case (unpack cls) of "warn" -> return $ Div ("", [], []) ((RawBlock latex "\\begin{tcolorbox}[colframe=yellow!90!white, colback=yellow!20!white]Warning: ") : contents : (RawBlock latex "\\end{tcolorbox}") : [])
                        "tips" -> return $ Div ("", [], []) ((RawBlock latex "\\begin{tcolorbox}[colframe=blue!20!white, colback=blue!10!white]Tips: ") : contents : (RawBlock latex "\\end{tcolorbox}") : [])
                        _ -> return cb

highlight x = return x

main :: IO ()
main = toJSONFilter highlight

and a header-included file H.tex

\usepackage{tcolorbox}

markdown file example.md

## How to write warning in pandoc

::: warn
deprecated, do not use.
:::

::: tips
usefull tips for writing markdown
:::

compile

pandoc example.md --filter f.hs -o book.pdf -s -H H.tex

Here is HTML filter

#!/usr/bin/env runhaskell
{-# LANGUAGE OverloadedStrings #-}
import Text.Pandoc.JSON
import Data.Text

html::Format
html = Format "html"

highlight :: Block -> IO Block
highlight cb@(Div (id, (cls:_), _) (contents:_)) =
   case (unpack cls) of "warn" -> return $ Div ("", [], []) ((RawBlock html "<div class=\"warn\">⚠warning:") : contents : (RawBlock html "</div>") : [])
                        "tips" -> return $ Div ("", [], []) ((RawBlock html "<div class=\"tips\">📝Tips:") : contents : (RawBlock html "</div>") : [])
                        _ -> return cb

highlight x = return x

main :: IO ()
main = toJSONFilter highlight

header-include file H.html

<style>
div.warn {
    background-color: yellow;
    font-family: monospace;
    border-radius: 5pt;
}
div.tips {
    background-color: lightblue;
    font-family: monospace;
    border-radius: 5pt;
}
</style> 

1 Comment

Hello @ianfun, can you see and answer my question about admonition? My admonition is different of yours, but I do not know if your code in Haskell is very similar to mine in Lua. Here is the link: stackoverflow.com/questions/73049303/…
3

> __Note__:

That will show note word with icon check result here => Note in md file

1 Comment

Nope, no icon..
1

I also use the 'table' method from general Markdown language.
Just using the header field only. I feel it's the simplest way to go.

| **Note** : `Some stuff goes here` |
| ----------------------------------|

Looks like this :

Note : Some stuff goes here

Comments

Your Answer

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

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.