be more clear about the two options for defining front matter data

README.adoc

@@ -124,10 +124,10 @@ Here's a sample AsciiDoc file that meets these criteria:
 [listing]
 ....
 ---
+layout: page
+permalink: /page/
 ---
 = Sample Page
-:page-layout: page
-:page-permalink: /page/
 
 This is a sample page composed in AsciiDoc.
 Jekyll converts it to HTML using {uri-asciidoctor}[Asciidoctor].
@@ -138,6 +138,21 @@ puts "Hello, World!"
 ----
 ....
 
+Alternatively, you can define the front matter data directly in the AsciiDoc header:
+
+.sample.adoc
+[listing]
+....
+---
+---
+= Sample Page
+:page-layout: page
+:page-permalink: /page/
+
+This is a sample page composed in AsciiDoc.
+...
+....
+
 AsciiDoc attributes defined in the document header whose names begin with `page-` are promoted to Jekyll front matter.
 The part of the name after the `page-` prefix is used as the entry's key (e.g., page-layout becomes layout).
 The value is parsed as https://en.wikipedia.org/wiki/YAML[YAML] data (that which can be expressed in a single line).
@@ -155,6 +170,8 @@ If the file begins with whitespace or a Byte Order Mark (BOM), then the front ma
 
 TIP: You can use an empty front matter header, as shown above.
 In this case, you define all the document metadata (e.g., layout) using AsciiDoc attributes instead of in the front matter.
+You can also use a combination of both.
+In this case, the attributes defined in the AsciiDoc header take precedence.
 
 You can now build your site using: