resolves asciidoctor#63 allow layout to be disabled

- false or unset disables layout, enables standalone output
- nil disables layout, does not enable standalone output
- not specified, empty string or _auto uses default (inherited) layout

README.adoc

@@ -111,7 +111,7 @@ NOTE: If the [path]_{empty}_plugins_ directory does not exist, you need to first
 
 == Creating pages
 
-This plugin converts eligible AsciiDoc files found in the source directory (which defaults to the project root) to pages in the generated site.
+This plugin converts eligible AsciiDoc files found inside the source directory (which defaults to the project root) to pages in the generated site.
 There are a few conditions that must be met for an AsciiDoc file to be qualified:
 
 . The file must have an AsciiDoc file extension (see <<configuration>>).
@@ -156,11 +156,26 @@ Jekyll converts it to HTML using {uri-asciidoctor}[Asciidoctor].
 ...
 ....
 
-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).
+AsciiDoc attributes defined in the document header whose names begin with `page-` get 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) and the value is parsed as https://en.wikipedia.org/wiki/YAML[YAML] data (that which can be expressed in a single line).
+
+The most commonly defined page variable is layout, which determines which layout is used to wrap the generated content.
+Jekyll will look for a file inside the [path]_{empty}_layouts_ folder whose root name matches the name of the layout.
+For example, if the layout variable has the value `page`, Jekyll might resolve a layout named [path]_page.html_.
+
+If the layout is empty, the default layout is used, `default` for pages and `posts` for posts.
+If the layout is unset or `false`, the AsciiDoc processor will generate a standalone document (`header_footer: true`).
+In this case, the page will appear like an HTML file that is generated by the AsciiDoc processor directly.
+If the layout is ~, no layout is applied.
+
+To review, here are the different ways to specify a layout using the AsciiDoc attribute page-layout:
+
+* `:page-layout: page` -- use the layout named `page` (e.g., [path]_page.html_)
+* _not specified_ or `:page-layout:` or `:page-layout: _auto` -- use the default layout (i.e., `default` for pages, `post` for posts)
+* `:!page-layout:` or `:page-layout: false` -- don't use a layout; instead, generate a standalone HTML document
+* `:page-layout: ~` -- don't use a layout (often results in an incomplete HTML file)
 
-In addition to these explicit page attributes, the following AsciiDoc attributes are also promoted to page data:
+In addition to page attributes defined explicitly, the following implicit AsciiDoc attributes are also promoted to page data:
 
 * doctitle (i.e., the document title) (becomes title)
 * author

lib/jekyll-asciidoc.rb

@@ -15,6 +15,7 @@ class AsciiDocConverter < Converter
         env=site env-site site-gen=jekyll site-gen-jekyll builder=jekyll builder-jekyll jekyll-version=#{Jekyll::VERSION}
       )
       HEADER_BOUNDARY_RE = /(?<=\p{Graph})\n\n/
+      STANDALONE_HEADER = %([%standalone]\n)
 
       safe true
 
@@ -67,7 +68,7 @@ def setup
           raise FatalException.new("Invalid AsciiDoc processor: #{@config['asciidoc']}")
         end
       end
-      
+
       def matches(ext)
         ext =~ @config['asciidoc_ext_re']
       end
@@ -79,9 +80,12 @@ def output_ext(ext)
       def convert(content)
         return content if content.empty?
         setup
+        if (standalone = content.start_with?(STANDALONE_HEADER))
+          content = content[STANDALONE_HEADER.length..-1]
+        end
         case @config['asciidoc']
         when 'asciidoctor'
-          Asciidoctor.convert(content, @config['asciidoctor'])
+          Asciidoctor.convert(content, @config['asciidoctor'].merge(header_footer: standalone))
         else
           warn 'Unknown AsciiDoc converter. Passing through unparsed content.'
           content
@@ -112,6 +116,9 @@ def render_with_liquid?
         end
       end
 
+      STANDALONE_HEADER = Converters::AsciiDocConverter::STANDALONE_HEADER
+      AUTO_PAGE_LAYOUT_LINE = %(:page-layout: _auto\n)
+
       def generate(site)
         asciidoc_converter = JEKYLL_MIN_VERSION_3 ?
             site.find_converter_instance(Jekyll::Converters::AsciiDocConverter) :
@@ -124,7 +131,8 @@ def generate(site)
 
         site.pages.each do |page|
           if asciidoc_converter.matches(page.ext)
-            next unless (doc = asciidoc_converter.load_header(page.content))
+            preamble = page.data.key?('layout') ? '' : AUTO_PAGE_LAYOUT_LINE
+            next unless (doc = asciidoc_converter.load_header(preamble + page.content))
 
             page.data['title'] = doc.doctitle if doc.header?
             page.data['author'] = doc.author if doc.author
@@ -135,15 +143,28 @@ def generate(site)
               page.data.update(SafeYAML.load(adoc_front_matter * "\n"))
             end
 
-            page.data['layout'] = 'default' unless page.data.key? 'layout'
+            case page.data['layout']
+            when nil
+              if page.data.key? 'layout'
+                page.data['layout'] = nil
+              else
+                page.content = STANDALONE_HEADER + page.content unless page.data.key? 'layout'
+              end
+            when '', '_auto'
+              page.data['layout'] = 'default'
+            when false
+              page.data.delete('layout')
+              page.content = STANDALONE_HEADER + page.content
+            end
 
             page.extend NoLiquid unless page.data['liquid']
           end
         end
 
         (JEKYLL_MIN_VERSION_3 ? site.posts.docs : site.posts).each do |post|
           if asciidoc_converter.matches(JEKYLL_MIN_VERSION_3 ? post.data['ext'] : post.ext)
-            next unless (doc = asciidoc_converter.load_header(post.content))
+            preamble = post.data.key?('layout') ? '' : AUTO_PAGE_LAYOUT_LINE
+            next unless (doc = asciidoc_converter.load_header(preamble + post.content))
 
             post.data['title'] = doc.doctitle if doc.header?
             post.data['author'] = doc.author if doc.author
@@ -155,7 +176,19 @@ def generate(site)
               post.data.update(SafeYAML.load(adoc_front_matter * "\n"))
             end
 
-            post.data['layout'] = 'post' unless post.data.key? 'layout'
+            case post.data['layout']
+            when nil
+              if post.data.key? 'layout'
+                post.data['layout'] = nil
+              else
+                post.content = STANDALONE_HEADER + post.content unless post.data.key? 'layout'
+              end
+            when '', '_auto'
+              post.data['layout'] = 'post'
+            when false
+              post.data.delete('layout')
+              post.content = STANDALONE_HEADER + post.content
+            end
 
             post.extend NoLiquid unless post.data['liquid']
           end