diff --git a/README.adoc b/README.adoc index 6d8e2f4..155e694 100644 --- a/README.adoc +++ b/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 <>). @@ -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 diff --git a/lib/jekyll-asciidoc.rb b/lib/jekyll-asciidoc.rb index 2eb28a3..55c7e88 100644 --- a/lib/jekyll-asciidoc.rb +++ b/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,7 +143,19 @@ 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 @@ -143,7 +163,8 @@ def generate(site) (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