FDP: Add subsection about images and icons

PR:                     261847
Reviewed by:            bcr@
Differential Revision:  https://reviews.freebsd.org/D41775

1 files changed, 83 insertions, 0 deletions

diff --git a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
index 9638651e68..67420c7746 100644
--- a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
@@ -240,6 +240,89 @@ And this would be rendered as.
 +
 extref:{ipsec-must}[IPSec-Must article]
 
+[[asciidoctor-images-icons]]
+== Images and Icons
+
+Images and icons play a crucial role in enhancing the overall user experience.
+These visual elements are strategically integrated to convey information, clarify concepts, and provide a visually engaging interface.
+
+[[asciidoctor-images]]
+=== Images
+
+Images help illustrate complex concepts, making them more accessible to users.
+
+The first step will be to add the image in the images directory in the path:
+
+* [.filename]#~/website/static/images/# for the website.
+* [.filename]#~/documentation/static/images/# for the documentation.
+
+For example, to add a new image to the FreeBSD installation process, the image will be saved to the path [.filename]#~/documentation/static/images/books/handbook/bsdinstall/new-image3.png#.
+
+The next step will be to configure the Asciidoctor attributes `images-path` and `imagesdir`.
+
+We are going to use as an example the header of the extref:{freebsd-releng}[FreeBSD Release Engineering] article.
+
+[source,asciidoc]
+....
+= FreeBSD Release Engineering
+:doctype: article
+
+[...]
+
+:images-path: articles/freebsd-releng/ <1>
+
+ifdef::env-beastie[]
+ifdef::backend-html5[]
+
+[...]
+
+:imagesdir: ../../../images/{images-path} <2>
+endif::[]
+
+[...]
+
+....
+
+<.> Makes reference to the path inside [.filename]#/static/images# folder.
+<.> Makes reference to the Asciidoctor attribute.
+
+Once the image is in the correct path and the Asciidoctor attributes have been configured in the document, the `image` macro can be used.
+
+This is an example:
+
+....
+image::new-image3.png[New step in the FreeBSD install process]
+....
+
+[TIP]
+====
+To improve accessibility, it is mandatory to add descriptive text to each image.
+====
+
+[[asciidoctor-icons]]
+=== Icons
+
+Icons serve as intuitive symbols for quick recognition and navigation.
+
+The first step to use icons is to add the `icons` property to the Asciidoctor properties section, at the top of each document.
+
+....
+:icons: font
+....
+
+Once the Asciidoctor icon property has been set an icon supported by link:https://fontawesome.com/v4/icons/[Font Awesome] can be added.
+
+This is an example about how to use the `envelope` icon:
+
+....
+icon:envelope[link=mailto:test@example.com, title="contact"]
+....
+
+[TIP]
+====
+To improve the accessibility of the website, the `title` attribute is mandatory.
+====
+
 [[asciidoctor-conclusion]]
 == Conclusion