fdp-primer: reduce confusion around section levels

Approved by:           carlavilla
Differential revision: https://reviews.freebsd.org/D37572

1 files changed, 10 insertions, 3 deletions

diff --git a/documentation/content/en/books/fdp-primer/structure/_index.adoc b/documentation/content/en/books/fdp-primer/structure/_index.adoc
index d92af964e1..b35fb23373 100644
--- a/documentation/content/en/books/fdp-primer/structure/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/structure/_index.adoc
@@ -147,9 +147,16 @@ This section contains specific notes about particular documents managed by the F
 
 The books are written in AsciiDoc.
 
-The books are organized as an AsciiDoc `book`.
-The books are divided into ``part``s, each of which contains several ``chapter``s.
-``chapter``s are further subdivided into sections (`=`) and subsections (`==`, `===`) and so on.
+For each FreeBSD book, the AsciiDoc document type (aka doctype) is `book`.
+Books have ``part``s, each of which contains several ``chapter``s.
+
+When the document is converted to HTML 5 (using the built-in `html5` backend):
+
+* AsciiDoc section level 0 (`=`) at the beginning of a ``chapter`` of a `book` will be `<h1>`
+* AsciiDoc section level 1 (`==`) must be used for the first logical section of a chapter, and will be `<h2>`
+* AsciiDoc section level 2 (`===`) must be used for the first logical subsection, and will be `<h3>`
+
+– and so on. Reference: link:https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/[Section Titles and Levels | Asciidoctor Docs].
 
 [[structure-document-books-physical]]
 === Physical Organization