improved site mojo documentation in README

README.adoc

@@ -397,11 +397,15 @@ IMPORTANT: Maven v3.2.1 or above required, and since asciidoctor-maven-plugin v1
 </build>
 -----
 
-All of your AsciiDoc-based files should be placed in [.path]_src/site/asciidoc_ with an extension of `.adoc`.
+The Asciidoctor Doxia module follows the maven-site-plugin conventions for file location, and delegates all resource management to it.
+
+First, all of your AsciiDoc-based files should be placed in [.path]_src/site/asciidoc_ with an extension of `.adoc`.
 These files will be rendered into the [.path]_target/site_ directory.
 For example, the file [.path]_src/site/asciidoc/usage.adoc_ will be rendered into [.path]_target/site/usage.html_.
 
-The Asciidoctor base directory (i.e., document root) is configured as [.path]_src/site/asciidoc_ by default, though this can be overridden.
+Then, all resources (images, css, etc.) should be placed in [.path]_src/site/resources_.
+These will be automatically copied into [.path]_target/site_.
+
 Also note that AsciiDoc files are converted to embeddable HTML and inserted into the site's page layout.
 This disables certain features such as a the sidebar toc.
 
@@ -421,12 +425,13 @@ Make sure you add a `menu` item for each page so you can access it from the site
 === Configuration
 
 As of version 1.5.3 of the plugin, you can configure Asciidoctor by specifying configuration properties in the plugin declaration, just like with the main plugin goal.
-There is one important difference, however.
-All the configuration for Asciidoctor in the site integration must be nested inside an `<asciidoc>` element.
-This is necessary since the `<configuration>` element is used to configure more than just the Asciidoctor integration.
+There are two important differences, however.
 
+. All the configuration for Asciidoctor in the site integration must be nested inside an `<asciidoc>` element.
+This is necessary since the `<configuration>` element is used to configure more than just the Asciidoctor integration.
++
 Here's an example that shows how to set options, attributes and ignore partial AsciiDoc files (i.e., files that begin with an underscore).
-
++
 [source,xml]
 .Maven site integration with Asciidoctor configuration
 ----
@@ -460,18 +465,45 @@ Here's an example that shows how to set options, attributes and ignore partial A
     </dependencies>
 </plugin>
 ----
-
-IMPORTANT: The Asciidoctor base directory (i.e., document root) is configured as [.path]_src/site/asciidoc_ by default, though this can be overridden using the `baseDir` configuration option.
-
-You'll notice that excludes have been added for certain AsciiDoc files.
++
+[IMPORTANT]
+====
+The Asciidoctor base directory (i.e., document root) is configured as [.path]_src/site/asciidoc_ by default, though this can be overridden.
+To do so, you can use either maven-site-plugin `siteDirectory` or Asciidoctor `baseDir` configuration options.
+Note that the first will affect the default resources directory also.
+====
++
+You'll notice in the example that excludes have been added for certain AsciiDoc files.
 This prevents the site integration from processing partial files (i.e., includes) as individual pages.
 You can tune this pattern to your liking.
 There's currently no way (that we can tell) to configure this automatically.
 
-We've also activated the built-in template converter by specifying a templates directory (i.e., `templatesDir`).
+. For simplicity and the fact that resources are managed by maven-site-plugin, not all options found in the asciidoctor-maven-plugin are available in the `<asciidoc>` element.
++
+The supported ones are:
+
+baseDir::
+Sames as the plugin's `baseDir`.
+Sets the root path for resources.
+Not set by default, AsciiDoc documents will be searched in [.path]_src/site/asciidoc_.
+External resources should be located in [.path]_src/site/resources_.
++
+NOTE: Consider using maven-site-plugin's `siteDirectory` instead for better integration with the site functions (ie. resource copying).
+
+templatesDir (also template_dir)::
+Built-in template are supported by specifying a templates directory (i.e., `templatesDir`).
 This feature enables you to provide a custom template for converting any node in the tree (e.g., document, section, listing, etc).
 Custom templates can be extremely helpful when trying to customize the appearance of your site.
 
+templatesDirs (also template_dirs)::
+Allows to set multiple templates.
+Note that each one should be enclosed in a `<dir>` element.
+
+requires::
+Sames as the plugin's `requires`.
+Specifies additional Ruby libraries not packaged in AsciidoctorJ, `empty` by default.
+
+
 // == Watching for changes
 
 // TODO