more thoroughly document the noborder role on block images

3 files changed, 17 insertions, 0 deletions

diff --git a/docs/modules/ROOT/pages/roles.adoc b/docs/modules/ROOT/pages/roles.adoc
index e5ffe07a..99dbeda0 100644
--- a/docs/modules/ROOT/pages/roles.adoc
+++ b/docs/modules/ROOT/pages/roles.adoc
@@ -20,6 +20,10 @@ The sign spelled out [.big]#WELCOME# in glowing neon lights.
 When text is enclosed in a pair of single or double hash symbols (`#`) and has at least one role, the role(s) will be applied to that text without adding any other implicit formatting.
 That is, the text won't be highlighted.
 
+Roles are sometimes used to control behavior.
+For example, if the `noborder` role is present on a block image, the border will not be drawn even if configured on the `image` category in the theme.
+The `noborder` role cannot be redefined.
+
 [#custom]
 == Use a custom role
 
diff --git a/docs/modules/theme/pages/block-image.adoc b/docs/modules/theme/pages/block-image.adoc
index 1f1b5092..6e266352 100644
--- a/docs/modules/theme/pages/block-image.adoc
+++ b/docs/modules/theme/pages/block-image.adoc
@@ -69,6 +69,15 @@ image:
   width: 100%
 |===
 
+=== noborder role
+
+If the `noborder` role is present on a block image, the border is not drawn on that image even if the border-related keys are defined on the `image` category in the theme.
+
+[,asciidoc]
+----
+image::image-without-border.png[role=noborder]
+----
+
 [#border-color]
 === border-color
 
diff --git a/docs/modules/theme/pages/role.adoc b/docs/modules/theme/pages/role.adoc
index 5d73b5f8..5ebc7c99 100644
--- a/docs/modules/theme/pages/role.adoc
+++ b/docs/modules/theme/pages/role.adoc
@@ -165,6 +165,10 @@ line-through:: The `line-through` role adds the strikethrough decoration.
 subtitle:: The `subtitle` role is used to configure the font properties of the subtitle of a section title.
 // end::user-formatting[]
 unresolved:: The `unresolved` role is applied automatically to the text of an unresolved footnote reference.
+(Only recognizes the `font-color` theme key).
+noborder:: Only applies to block images.
+If this role is present on the block image, the border will not be added.
+This role cannot be redefined.
 
 NOTE: The color roles (e.g., `blue`), which you may be familiar with from the HTML converter, are not mapped by default.
 You'll need to define these color roles as xref:custom-role.adoc[custom roles] in your theme if you'd like to make use of them when converting to PDF.