Awesome Boxes
Étienne Deparis
2019-07-27 v0.6
1 Introduction
Awesome Boxes is all about drawing admonition blocks around text to inform or alert
your readers about something particular. The specific aim of this package is to use
FontAwesome 5 icons to ease the illustration of these boxes.
The idea of admonition blocks comes from the ones you can easily do with AsciiDoc.
2 How to use it?
Just download this package and call it at the beginning of your document:
\usepackage{awesomebox}
3 Provided boxes
3.1 Inline boxes
The provided boxes follow the name convention of the admonition blocks from Asci-
iDoc.
\notebox{Lorem ipsum…}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam aliquet libero
quis lectus elementum fermentum.
Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at dictum
felis. Pellentesque tortor lacus, semper et neque vitae, egestas commodo
nisl.
1
\tipbox{Lorem ipsum…}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam aliquet libero
c quis lectus elementum fermentum.
Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at dictum
felis. Pellentesque tortor lacus, semper et neque vitae, egestas commodo
nisl.
\warningbox{Lorem ipsum…}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam aliquet libero
quis lectus elementum fermentum.
Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at dictum
felis. Pellentesque tortor lacus, semper et neque vitae, egestas commodo
nisl.
\cautionbox{Lorem ipsum…}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam aliquet libero
quis lectus elementum fermentum.
Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at dictum
felis. Pellentesque tortor lacus, semper et neque vitae, egestas commodo
nisl.
\importantbox{Lorem ipsum…}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam aliquet libero
quis lectus elementum fermentum.
Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at dictum
felis. Pellentesque tortor lacus, semper et neque vitae, egestas commodo
nisl.
3.2 Environments
You can also insert admonition blocks with an environment syntax. The same names
can be used, but with a block suffix.
\begin{noteblock}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam
2
aliquet libero quis lectus elementum fermentum.
\end{noteblock}
For the exactly same rendering:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam aliquet libero
quis lectus elementum fermentum.
Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at dictum
felis. Pellentesque tortor lacus, semper et neque vitae, egestas commodo
nisl.
4 How to add new icons?
This package use the FontAwesome5 package under the hood. In order to use your own
icons, just call the proper \faXxx command.
For example, if you want to add the rocket icon (Ģ), you just have to insert \faRocket.
5 How to create your own box?
5.1 Inline boxes
To create your own box, with your own icon and colour, your own vertical rule width
and colour, your own horizontal rules at the top and the bottom of your boxes, or a title,
you can use our meta command:
\awesomebox[vrulecolor][hrule][title]{vrulewidth}{icon}{iconcolor}{content}
Here are some examples of custom boxes:
\awesomebox{5pt}{\faCertificate}{magenta}{Lorem ipsum…}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam aliquet libero
½ quis lectus elementum fermentum.
Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at dictum
felis. Pellentesque tortor lacus, semper et neque vitae, egestas commodo
nisl.
3
\awesomebox{0pt}{\faCogs}{black}{Lorem ipsum…}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam aliquet libero
¯ quis lectus elementum fermentum.
Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at dictum
felis. Pellentesque tortor lacus, semper et neque vitae, egestas commodo
nisl.
\awesomebox[violet]{2pt}{\faRocket}{violet}{Lorem ipsum…}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam aliquet libero
Ģ quis lectus elementum fermentum.
Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at dictum
felis. Pellentesque tortor lacus, semper et neque vitae, egestas commodo
nisl.
\awesomebox[white][\abShortLine]{0pt}{\faGrinBeam[regular]}{black}{Lorem ipsum…}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam aliquet libero
 quis lectus elementum fermentum.
Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at dictum
felis. Pellentesque tortor lacus, semper et neque vitae, egestas commodo
nisl.
\awesomebox[white][\abLongLine][\textbf{Watch out}]{0pt}{\faBomb}{black}{Lorem…}
Watch out
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam aliquet libero
ų quis lectus elementum fermentum.
Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at dictum
felis. Pellentesque tortor lacus, semper et neque vitae, egestas commodo
nisl.
5.2 Environments
To create your own box, with your own icon and colour, your own vertical rule width
and colour, your own horizontal rules at the top and the bottom of your boxes, or a title,
you can use our meta command:
4
\begin{awesomeblock}[vrulecolor][hrule][title]{vrulewidth}{icon}{iconcolor}
your text content
\end{awesomeblock}
For example, we can rewrite the first previous example as:
\begin{awesomeblock}[magenta]{5pt}{\faCertificate}{magenta}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam aliquet
libero quis lectus elementum fermentum.
\end{awesomeblock}
Which will render this way:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam aliquet libero
½ quis lectus elementum fermentum.
Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at dictum
felis. Pellentesque tortor lacus, semper et neque vitae, egestas commodo
nisl.
6 Other options
Some internal options can be customized, in order to globally modify your awesome
boxes (either the default ones or your new ones).
6.1 Left margin
The left margin is the space left to display the icon before the vertical rule. You can
change it with the following command (0.12\linewidth is the default one):
\setlength{\aweboxleftmargin}{0.12\linewidth}.
You must declare you new length after the \begin{document} instruction, or your
custom length will be overriden by the default one.
6.2 Content width
The content width is the space used to insert the body of your admonition block. You
can change it with the following command (0.88\linewidth is the default one):
\setlength{\aweboxcontentwidth}{0.88\linewidth}.
You must declare you new length after the \begin{document} instruction, or your
custom length will be overriden by the default one.
5
6.3 Vertical skip
This space is used before and after the awesome box. You can change it with (5mm is
the default): \setlength{\aweboxvskip}{5mm}.
You can put your new length either in the header or in the body of your document.
6.4 Sign raise
This length is used to raise (or lower) the left icon. Its default value is -5mm and you
can change it with: \setlength{\aweboxsignraise}{-5mm}.
You can put your new length either in the header or in the body of your document.
6.5 Vertical rule width
This width is used for the vertical rule of our four default boxes. Its default value is 2pt
and you can change it with: \setlength{\aweboxrulewidth}{2pt}.
You can put your new length either in the header or in the body of your document.
6.6 Vertical rule default color
The vertical rule color is an optional argument passed to the commands or environments.
Its default value is the following (to match the one defined by AsciiDoctor) and you can
change it this way:
\definecolor{abvrulecolor}{RGB}{221,221,216}
7 With other environments
Awesome boxes may be used in any other environments, like in a list.
\begin{itemize}
\item My first item
\item Lorem ipsum… \notebox{Fusce aliquet…}
\item Last and finally
\end{itemize}
will give:
• My first item
6
• Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam aliquet libero quis
lectus elementum fermentum.
Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at dic-
tum felis. Pellentesque tortor lacus, semper et neque vitae, egestas
commodo nisl.
• Last and finally
It may contain other environments too, but in that case, you should prefer the envi-
ronment API (see Section 3.2):
\begin{importantblock}
\begin{itemize}
\item My first item
\item My second item with \notebox{A note box!}
\item Last and finally
\end{itemize}
\end{importantblock}
will give:
• My first item
• My second item with
A note box!
• Last and finally
Or with a more complex example with minted environment:
\begin{noteblock}
This could be written as:
\begin{minted}{c++}
std::cout << ”hello world!” << std::endl;
\end{minted}
\end{noteblock}
7
This could be written as:
std::cout << ”hello world!” << std::endl;
8 Breaking changes
8.1 Version 0.6
This version improved a lot block components rendering. Historically, awesome box
used fixed length to display icon and content. This leads to admonition block to overflow
or to be thinner than paragraphs around.
Please note that we change default block components width in purpose. It used
to be 0.08\linewidth for the margin and 0.92\linewidth for the content. It is now
0.12\linewidth for the margin and 0.88\linewidth for the content.
We now compute the default \aweboxleftmargin and \aweboxcontentwidth value in
a \AtBeginDocument command. Thus, to avoid your custom lengths to be overriden by
the default ones, you must declare them after the \begin{document} instruction.
8.2 Version 0.4
This version introduced a way to customize the rule color. Thus, the commands and
environments arguments have been reorganized to be in a more logical order.
Historically, the \awesomebox command used the following syntax:
\awesomebox{icon}{rulewidth}{iconcolor}{your text content}
This syntax now leads to compiling errors, as you must now write it as the following
example shows you (and as explained in the section 5 ”How to create your own box?”),
to avoid an alternate declaration of rule and icon options:
\awesomebox[rulecolor]{rulewidth}{icon}{iconcolor}{your text content}
If you only use the provided boxes and environments (the \notebox, \tipbox, \warn-
ingbox, \cautionbox, \importantbox commands or the noteblock, tipblock, caution-
block, warningblock, importantblock environments) you are not affected by this change
and your documents will work without any change.
Handcrafted with F from Nantes, France
Awesome Box is released under the WTFPL. A copy of this license is distributed in this package.
version of the Monday 29ᵗʰ July, 2019 — 18:45
