diff --git a/docs/modules/theme/pages/apply-theme.adoc b/docs/modules/theme/pages/apply-theme.adoc
index c7ca24327..66a611945 100644
--- a/docs/modules/theme/pages/apply-theme.adoc
+++ b/docs/modules/theme/pages/apply-theme.adoc
@@ -19,6 +19,9 @@ If the value of the `pdf-theme` attribute doesn't end with `.yml` (e.g., `base`)
 The value is then treated as a relative path (even if it's absolute) and resolved starting from the value of the `pdf-themesdir` attribute.
 If the `pdf-themesdir` is not specified, the built-in themes directory is used as the starting point instead (rather than the current working directory).
 +
+IMPORTANT: The theme file *must* end in .yml, not .yaml.
+When the theme path specified does not end in .yml, Asciidoctor PDF appends the suffix `-theme.yml` and looks for the resulting file.
++
 You can use the `+{docdir}+` token as the first path segment in the name to build an absolute path starting from the directory of the source document.
 +
 The theme name or file path can be specified using the `--theme` CLI option as a shorthand.
diff --git a/docs/modules/theme/pages/create-theme.adoc b/docs/modules/theme/pages/create-theme.adoc
index 275e2df14..512061e2f 100644
--- a/docs/modules/theme/pages/create-theme.adoc
+++ b/docs/modules/theme/pages/create-theme.adoc
@@ -15,6 +15,10 @@ An Asciidoctor PDF theme is defined using a YAML data file that ends with `-them
 No keys are actually required.
 Each key you specify will customize the styling in some way that differs from the intrinsic defaults.
 
+IMPORTANT: The theme file *must* end in .yml, not .yaml.
+When the theme path specified does not end in .yml, Asciidoctor PDF appends the suffix `-theme.yml` and looks for the resulting file.
+Thus, the `-theme` segment is optional if you include the .yml file extension when specifying the theme path.
+
 For example, you can define a theme to set the page size to Letter (which differs from the default, which is A4).
 
 .my-theme.yml