Pandoc lua-filter that creates a box around some text.
Run this filter e.g. with pandoc sample.md --lua-filter=box.lua --output=sample.pdf
.
The simplest usage would be to wrap three colons :::
with the {.box}
attribute around some text. box
creates a box around it with the default border and fill color of tcolorbox
(see sample.pdf).
:::{.box}
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet
clita kasd gubergren.
:::
Resulting in
![](https://private-user-images.githubusercontent.com/3295340/260256624-71f1b8c1-dbfb-4e21-aeae-5a54468910ce.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjUwMzU5NjcsIm5iZiI6MTcyNTAzNTY2NywicGF0aCI6Ii8zMjk1MzQwLzI2MDI1NjYyNC03MWYxYjhjMS1kYmZiLTRlMjEtYWVhZS01YTU0NDY4OTEwY2UucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI0MDgzMCUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNDA4MzBUMTYzNDI3WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9NWFhNWRjMzE4MzM5Y2ExNjYyY2ExODhhM2IzOWQ2YzEwYmJlNzRmNjQ3ODI2OWI2YTQ0YzBlYjcxYmIwYTIzNyZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.izwVmGnkNqZTjhPS5y62l7PosBuFPxZRPX9ZR7B_NVs)
It is also possible to use predefined boxes aka. admonitions. All you need to do is to call the classes .important
, .info
, .danger
, .warning
and .plain
(see sample_types.md).
![](https://private-user-images.githubusercontent.com/3295340/260316026-21b49977-36c7-4fa8-b957-7703ab018df6.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjUwMzU5NjcsIm5iZiI6MTcyNTAzNTY2NywicGF0aCI6Ii8zMjk1MzQwLzI2MDMxNjAyNi0yMWI0OTk3Ny0zNmM3LTRmYTgtYjk1Ny03NzAzYWIwMThkZjYucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI0MDgzMCUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNDA4MzBUMTYzNDI3WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9MDFmNGY5MjEzOTU2MGIxMmVhMjliYzMzOGI1NDVhMWFiMTM4Zjg2OTgxYjVkMDBlYTY0Y2Q2ZWI5YjZlZGM5ZiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.wjhNlzqE4RsLooTaxa2nLe97POS_HSUExWI43rEz6FY)
You can add titles and define fill and border colors with
:::{.box fillcolor="#ababab" bordercolor="#000000"}
> Your title as a blockquote followed by an empty line
Your regular markdown content here such as
Here is some **Text** that you can *display* inside a Box!
You can also add your favorite markdown commands such as
> a nice blockquote
Maybe a table?!
| Here | Here|
|------|----:|
|Here | and here |
And some bullet points
- Some
- important
- bullet
- points
and enumerations
1. first
2. second
3. third
> The last line as a blockquote results in adding a lower part of the box.
:::
![](https://private-user-images.githubusercontent.com/3295340/260310991-03b9b880-d60d-4104-aa38-ccbe0a713e39.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjUwMzU5NjcsIm5iZiI6MTcyNTAzNTY2NywicGF0aCI6Ii8zMjk1MzQwLzI2MDMxMDk5MS0wM2I5Yjg4MC1kNjBkLTQxMDQtYWEzOC1jY2JlMGE3MTNlMzkucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI0MDgzMCUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNDA4MzBUMTYzNDI3WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9YjgwNWQ0ODIxYjkzMzc5ZWQ4NzEyZDNlOTA3MTMxMzdiZWNiZGYyNzFkMDU2MzczOTFmNGE5OWEwNzE0MTkyNSZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.s7oUr04pOL35difF5IHMykzuqbtXM4mDRivTsKqS__E)
This pandoc filter is basically wrapping a tcolorbox
around the text in markdown and provides the options:
- the title set by the first blockquote paragraph (see the important information below when you only want to put a quote inside the box)
- a lower part set by the last blockquote
- fillcolor: the background color of the box. Supports
HTML
(#...
) and latexxcolor
colors - bordercolor: the framecolor of the box. Supports
HTML
(#...
) and latexxcolor
colors
- So far the display of images with captions are not supported, since pandoc centers every image once it has a caption. Latex throws an error message
! LaTeX Error: Not in outer par mode.
See the LaTeX manual or LaTeX Companion for explanation.
Type H <return> for immediate help.
...
l.108 \centering
There are some semi optimal solutions to this, though.
- The
tcolorbox
package provides much more options than this filter. If you think that this filter should have more options, any PR redarding this issue is welcome.
- If you have your own
header-includes
file, you need to additionally importtcolorbox
with\usepackage{tcolorbox}
. - If you only want to put a quote
>
into a box consider adding an empty title and empty bottom quote like this:
:::{.box}
>
> I think therefore I am
>
:::
Resulting in this:
![](https://private-user-images.githubusercontent.com/3295340/260310949-2d646810-b750-44ce-ac17-873217f05d40.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjUwMzU5NjcsIm5iZiI6MTcyNTAzNTY2NywicGF0aCI6Ii8zMjk1MzQwLzI2MDMxMDk0OS0yZDY0NjgxMC1iNzUwLTQ0Y2UtYWMxNy04NzMyMTdmMDVkNDAucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI0MDgzMCUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNDA4MzBUMTYzNDI3WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9NDE0Njc2Yjk4ODM0ZTJiZTMzMzUwMDZhNDIzNDNhMzAwOWQ3MDU3ODI4NDY3MDc4ZDQ4YzZkMTIxZTE2ZGZiNSZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.RRVWpHLnI6sQ8rg1yF2hpeaRjNXtI9IbRZWlxdDo-PU)
- allow identification with
crossref