README: revise the structure of the "Authoring pages" section.

1 files changed, 38 insertions, 14 deletions

diff --git a/README.org b/README.org
index 8870768..e8a3542 100644
--- a/README.org
+++ b/README.org
@@ -54,20 +54,28 @@ Those dependencies are:
 
 * Authoring pages
 
-Currently supported are Markdown (~.md~) and Org-mode (~.org~) files.
-Each of these format supports embedding metadata in the document
-(well, Markdown doesn't really, but the Pandoc syntax extension
-~yaml_metadata_block~ adds it).
+If you drop a file in the ~src/~ folder, the site generator will try
+to turn it into usable HTML.  The big caveat is that files *MUST* to
+be in all lower case (this is to efficiently handle the requirement
+that URLs be case-insensitive)!
 
-In Org-mode, this looks like
+Currently supported formats are:
 
-#+BEGIN_SRC
-#+KEY: value
+ - Markdown (~.md~) : converted with Pandoc
+ - Org-mode (~.org~) : converted with Pandoc
 
-...rest of document...
-#+END_SRC
+I don't need to tell you how to make these types of files.
 
-In Markdown, this looks like
+In addition to the raw content of the files, you'll want/need to set
+metadata about the page.  Each of these format supports embedding
+metadata in the document.
+
+** Setting metadata: Markdown
+
+Metadata for Markdown files can be set by adding a block of YAML at
+the beginning of the document, terminated with "---".  This isn't
+"standard" markdown, but is a common syntax extension (Pandoc calls it
+~yaml_metadata_block~).
 
 #+BEGIN_SRC
 ---
@@ -79,16 +87,32 @@ key2:
 ...rest of document...
 #+END_SRC
 
+Pandoc may make use of some of these metadata attributes internally
+when converting to HTML.  See the Pandoc documentation.
+
+** Setting metadata: Org-mode
+
+Metadata for Org-mode files can be set by adding ~#+KEY: value~ lines
+at the beginning of the document.
+
+#+BEGIN_SRC
+#+KEY: value
+
+...rest of document...
+#+END_SRC
+
+Pandoc may make use of some of these metadata attributes internally
+when converting to HTML.  See the Org-mode and Pandoc documentation.
+
 AFAIK, unfortunately Org-mode only has values as strings, no
 structured data.
 
-Pandoc may make use of some of these values internally when converting
-to HTML.  See the Org-mode and Pandoc documentation.
+** Metadata attributes that are handles specially
 
-However, there are some of these that are used specially by the site
+There are some metadata attributes that are used specially by the site
 generator:
 
-| attribute        | default                         | standard | format                                          |
+| attribute        | default value                   | standard | format                                          |
 |------------------+---------------------------------+----------+-------------------------------------------------|
 | title            | the first line of the file      | Pandoc   | string                                          |
 | author           | ~config.yaml:default_author~    | Pandoc   | string +or list+ [fn:1]                         |