resolves #473 adds extra documentation on document structure and head…

…er (#474)

Co-authored-by: Guillaume Grossetie <ggrossetie@yuzutech.fr>
Co-authored-by: Dan Allen <dan.j.allen@gmail.com>

docs/modules/converter/pages/features.adoc

@@ -29,6 +29,11 @@ A Great Story
 In previous snippet we are creating a slide titled Slide One with bullets and another one titled Slide Two with centered text (reveal.js`' default behavior) with link:{url-revealjs-doc}#speaker-notes[speaker notes].
 Other syntax exists to create speaker notes, see `examples/speaker-notes.adoc`.
 
+IMPORTANT: In order to generate a proper presentation, the source file _must_ contain a proper AsciiDoc document structure.
+This is especially important when configuring how Asciidoctor reveal.js should convert the document.
+The document properties must be set on the title slide for them to work. 
+See xref:syntax/title.adoc[] for more information.
+
 Starting with reveal.js 3.5 speaker notes supports configurable layouts:
 image:https://cloud.githubusercontent.com/assets/629429/21808439/b941eb52-d743-11e6-9936-44ef80c60580.gif[]
 

docs/modules/converter/pages/syntax/title.adoc

@@ -1,16 +1,50 @@
-= Title Slide Customization
-:navtitle: Title Slide
+= Title Slide
 
-The title slide is customized via AsciiDoc attributes.
-These are the global variable assigned at the top of a document under the lead
-title that look like this: `:name: value`.
+The title slide is where customization for the generated presentation can be configured via AsciiDoc xref:asciidoc:attributes:document-attributes.adoc[document attributes].
+These are the document-scope variables assigned at the top of a document, as part of the document header as xref:asciidoc:attributes:attribute-entries.adoc[attribute entries].
 
-This converter supports changing the color, image, video, iframe and
-transitions of the title slide.
+[source,asciidoc]
+----
+= Title Slide
+:revealjs_theme: sky
+:source-highlighter: highlight.js
 
-Read link:{url-revealjs-doc}#slide-backgrounds[the relevant reveal.js documentation] to understand what attributes need to be set.
-Keep in mind that for title slides you must replace `data-` with `title-slide-`.
+== Slide One
 
-See link:{url-project-examples}/title-slide-image.adoc[title-slide-image.adoc].
+* Foo
+* Bar
+* World
+----
 
-The title slide is also added a `title` CSS class to help with template customization.
+In AsciiDoc terms, the first line is the document title and the variable definitions following it are part of the xref:asciidoc:document:header.adoc[document header].
+
+NOTE: Starting your document with a section title means AsciiDoc interprets your document header as empty.
+
+Any variables set will not be picked up by the converter and will not influence the resulting presentation.
+The next example shows this mistake:
+
+[source,asciidoc]
+----
+== This is not a document title
+// These settings are not interpreted as document attributes and will not be accessible to
+// the asciidoctor-revealjs converter.
+:revealjs_theme: sky
+:source-highlighter: highlight.js
+----
+
+NOTE: Even if you start a document with a level-1 section, you can still have a document header.
+The variables then need to be defined _above_ the section header.
+Another way to think of this is having a document header without a document title.
+
+== Customizing the Title Slide
+
+In addition to configuring document-wide settings, the title slide can also define visual customization that is only applied to the title slide.
+
+This converter supports changing the color, image, video, iframe and transitions of the title slide.
+
+Read {url-revealjs-doc}#slide-backgrounds[the reveal.js documentation] to understand what attributes can be set.
+Keep in mind that for a title slide, you must replace `data-` with `title-slide-` in the name of the attribute.
+
+See link:{url-project-examples}/title-slide-image.adoc[title-slide-image.adoc] for an example of using these attributes.
+
+The title slide also given an special `title` CSS class to help with template customization.