You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
88 lines
2.7 KiB
88 lines
2.7 KiB
4 years ago
|
////
|
||
|
|
Included in:
|
||
|
|
|
||
|
|
- user-manual: Admonition
|
||
|
|
- writers-guide: admonition
|
||
|
|
////
|
||
|
|
|
||
|
|
// tag::intro[]
|
||
|
|
There are certain statements you may want to draw attention to by taking them out of the content's flow and labeling them with a priority.
|
||
|
|
These are called admonitions.
|
||
|
|
It's rendered style is determined by the assigned label (i.e., value).
|
||
|
|
Asciidoctor provides five admonition style labels:
|
||
|
|
|
||
|
|
* `NOTE`
|
||
|
|
* `TIP`
|
||
|
|
* `IMPORTANT`
|
||
|
|
* `CAUTION`
|
||
|
|
* `WARNING`
|
||
|
|
|
||
|
|
.Caution vs. Warning
|
||
|
|
****
|
||
|
|
When choosing the admonition type, you may find yourself getting confused between "caution" and "warning" as these words are often used interchangeably.
|
||
|
|
Here's a simple rule to help you differentiate the two:
|
||
|
|
|
||
|
|
* Use *CAUTION* to advise the reader to _act_ carefully (i.e., exercise care).
|
||
|
|
* Use *WARNING* to inform the reader of danger, harm, or consequences that exist.
|
||
|
|
|
||
|
|
To find a deeper analysis, see https://www.differencebetween.com/difference-between-caution-and-vs-warning/.
|
||
|
|
****
|
||
|
|
|
||
|
|
When you want to call attention to a single paragraph, start the first line of the paragraph with the label you want to use.
|
||
|
|
The label must be uppercase and followed by a colon (`:`).
|
||
|
|
|
||
|
|
.Admonition paragraph syntax
|
||
|
|
[source]
|
||
|
|
----
|
||
|
|
include::ex-admon.adoc[tag=para-c]
|
||
|
|
----
|
||
|
|
<1> The label must be uppercase and immediately followed by a colon (`:`).
|
||
|
|
<2> Separate the first line of the paragraph from the label by a single space.
|
||
|
|
// end::intro[]
|
||
|
|
|
||
|
|
:icons!:
|
||
|
|
// tag::icon[]
|
||
|
|
.Result: Admonition paragraph
|
||
|
|
====
|
||
|
|
include::ex-admon.adoc[tag=para]
|
||
|
|
====
|
||
|
|
// end::icon[]
|
||
|
|
:icons: font
|
||
|
|
|
||
|
|
When you want to apply an admonition to complex content, set the label as a style attribute on a block.
|
||
|
|
As seen in the next example, admonition labels are commonly set on example blocks.
|
||
|
|
This behavior is referred to as *masquerading*.
|
||
|
|
The label must be uppercase when set as an attribute on a block.
|
||
|
|
|
||
|
|
.Admonition block syntax
|
||
|
|
[source]
|
||
|
|
----
|
||
|
|
include::ex-admon.adoc[tag=bl-c]
|
||
|
|
----
|
||
|
|
<1> Set the label in an attribute list on a delimited block. The label must be uppercase.
|
||
|
|
<2> Admonition styles are commonly set on example blocks. Example blocks are delimited by four equal signs (`====`).
|
||
|
|
|
||
|
|
:icons!:
|
||
|
|
.Result: Admonition block
|
||
|
|
====
|
||
|
|
include::ex-admon.adoc[tag=bl-nest]
|
||
|
|
====
|
||
|
|
:icons: font
|
||
|
|
|
||
|
|
In the examples above, the admonition is rendered in a callout box with the style label in the gutter.
|
||
|
|
You can replace the textual labels with icons by setting the `icons` attribute on the document.
|
||
|
|
This is how the WARNING admonition paragraph renders when icons is set and assigned the `font` value.
|
||
|
|
|
||
|
|
.Admonition paragraph with icons set
|
||
|
|
[source]
|
||
|
|
----
|
||
|
|
include::ex-admon.adoc[tag=para]
|
||
|
|
----
|
||
|
|
|
||
|
|
.Result: Admonition paragraph with icons set
|
||
|
|
====
|
||
|
|
include::ex-admon.adoc[tag=para]
|
||
|
|
====
|
||
|
|
|
||
|
|
Learn more about using Font Awesome or custom icons with admonitions in the <<user-manual#icons,icons>> section.
|