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?
214 Answers
With GitHub, I usually insert a blockquote.
> **_NOTE:_** The note content. becomes...
NOTE: The note content.
Of course, there is always plain HTML...
6What 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.
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):
----------------------- ------------------------------------ \ 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) : .
1I usually insert a blockquote and add a Unicode character(memo📝 which is(U+1F4DD)) inside it.
📝 ...
| Syntax | Demo |
|---|---|
> 📝 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!
-
just search you like icon and copy-paste then done(since it is a character, so it suitable for every device)
-
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.
1The 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 \.
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.
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 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>
OR (adding a bit more to the design - rounded corners and border)
<div 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>
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:
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).
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.
1Have 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::: warning *here be dragons* ::: Will then render as:
<div> <em>here be dragons</em> </div> 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 */ } 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
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>
