middleman-asciidoc 1.0.0.rc.2 → 1.0.0.rc.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 71184316832805aae751db8bbcb388ff1b31b737
-  data.tar.gz: efd5605cc5280b9c75372e4bc479d65112f21a21
+SHA256:
+  metadata.gz: d3d408ad1c5872270863cdc6e626014d24eec8eaa523ee4fee42b52ab910a85c
+  data.tar.gz: 245786b049319ca48ed1fba34e98a50419980c7e0b8eecd6e77556be1b341220
 SHA512:
-  metadata.gz: cb963a0acae39a624791b739ff7e596088913cb56a06f9befa8b25c3de096a9d0785c7662b25d2dd38ab72d627323174cca5bacbf032deac1a8c1219fe337a3f
-  data.tar.gz: 3320c78bbe08f681f07c252a9e7d3148e39c889faf843815ebc54fd1df77704e961d11cfb0ddf52b0f3d0c2cf3714ead81772a5ed8ad38f9b77c3f0d1455d8e1
+  metadata.gz: bda2d717b1d551dbc07433b580a6f34a9815725218aa19837515448b7605c1c54d7db41471d8a31a2588e9b8a3f1424588a3b18d4c13c94d60583c2c24a88555
+  data.tar.gz: 780f90f69d6bc617c9be0e52f3d970994eaedd4f28698ca43ab0a260d8e573dd32dd8479afc48ff26ceda6e1e2556df5dfc08c7d767fe66de8fb910de184320c

data/Gemfile

@@ -3,6 +3,12 @@ source 'https://rubygems.org'
 # Runtime dependencies are defined in middleman-asciidoc.gemspec
 gemspec
 
+if RUBY_ENGINE == 'jruby'
+  git 'https://github.com/mojavelinux/middleman.git', branch: 'no-fast-blank' do
+    gem 'middleman-core'
+  end
+end
+
 # Build and doc tools
 gem 'rake', '~> 10.3', require: false
 gem 'yard', '~> 0.8', require: false
@@ -13,7 +19,7 @@ gem 'aruba', '~> 0.7.4', require: false
 gem 'capybara', '~> 2.5.0', require: false
 
 # Code quality tools
-gem 'cane', platforms: [:mri_19, :mri_20], require: false
+gem 'cane', platforms: :mri, require: false
 
 # Middleman itself (use for testing against development version)
 #gem 'middleman-core', :github => 'middleman/middleman', :branch => 'master'

data/LICENSE.adoc

@@ -1,6 +1,6 @@
 .MIT License
 ....
-Copyright (C) 2014-2016 Dan Allen and the Asciidoctor Project
+Copyright (C) 2014-2017 Dan Allen and the Asciidoctor Project
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.adoc

@@ -1,6 +1,6 @@
 = AsciiDoc Extension for Middleman (powered by Asciidoctor)
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
-v1.0.0.rc.2, 2016-05-22
+v1.0.0.rc.3, 2017-11-25
 // Settings:
 :idprefix:
 :idseparator: -
@@ -48,23 +48,26 @@ Prior to Middleman 4, AsciiDoc support was part of Middleman core.
 
 == Installation
 
-If you're just getting started, install the Middleman gem:
+If you're just getting started, first install the Middleman gem.
 
- $ NOKOGIRI_USE_SYSTEM_LIBRARIES=1 gem install middleman
+ $ gem install middleman
 
-then generate a new project:
+Then, generate a new project:
 
  $ middleman init MY_PROJECT
 
+The project will be created in the MY_PROJECT directory.
+
 If you're working with an existing project, you can skip the previous steps.
 
 Next, add the gem for this extension to your project's [.path]_Gemfile_.
 
-```ruby
+[source,ruby]
+----
 gem 'middleman-asciidoc'
-```
+----
 
-Finally, run Bundler using the `bundle` command:
+Finally, run Bundler to install the dependencies using the `bundle` command:
 
  $ bundle
 
@@ -72,15 +75,20 @@ You're now ready to activate this extension and begin putting it to work.
 
 == Activation and Configuration
 
-```ruby
+To activate this extension, add the following line to the [.path]_config.rb_ file for your site:
+
+[source,ruby]
+----
 activate :asciidoc
-```
+----
 
-You can also pass AsciiDoc configuration options to the underlying Asciidoctor processor:
+You can also pass AsciiDoc configuration options to the underlying Asciidoctor processor as a Hash or Array.
+Here's an example of passing the attribute as an Array:
 
-```ruby
+[source,ruby]
+----
 activate :asciidoc, attributes: ['source-highlighter=coderay']
-```
+----
 
 The following option keys from the Asciidoctor API can be added to the Hash of the second argument to `activate`:
 
@@ -94,21 +102,26 @@ The following implicit attributes are automatically appended to this collection.
 * site-gen-middleman
 * builder=middleman
 * builder-middleman
-* middleman-version=(value of `::Middleman::VERSION` constant)
+* middleman-version=(value of `Middleman::VERSION` constant)
 * imagesdir=(value of http_prefix + images_dir in app config)@
-  - skipped if `!imagesdir` is defined as a custom attribute
-  - can be overridden in page (hence the trailing @)
+ ** skipped if `!imagesdir` is defined as a custom attribute
+ ** can be overridden in page (hence the trailing @)
 
 backend (type: Symbol, default: :html5)::
 The moniker for a converter, which determines the output format to generate.
 
-base_dir (type: String, default: nil)::
-The base directory to use for the current AsciiDoc document; if not specified, defaults to the document directory (i.e., docdir).
-To set the base directory to the source directory, use the value `app.source_dir.expand_path`.
+base_dir (type: String, default: :docdir)::
+The base directory to use for the current AsciiDoc document.
+If not specified, defaults to the document directory (i.e., `:docdir`).
+To set the base directory to the source directory, use the keyword `:source` or the expression `app.source_dir`.
+To leave the base directory undefined, use the value `nil`.
 
 safe (type: Symbol, default: :safe)::
 The safe mode level under which to run the AsciiDoc processor.
 
+layout (type: String or Symbol, default: nil)::
+The name of the default layout for AsciiDoc-based pages (pages processed by this extension, not including blog articles if a blog layout is specified).
+
 TIP: The full set of options can be seen on your preview server's config page at the path [.path]_/__middleman/config/_.
 
 == Creating Pages
@@ -122,7 +135,7 @@ NOTE: For details about how the file extension is substituted, see the discussio
 To add a page composed in AsciiDoc, simply add an AsciiDoc file that has one of the aforementioned AsciiDoc file extensions to the project source directory.
 
 .sample.adoc
-[listing]
+[source,asciidoc]
 ....
 = Sample Page
 :page-layout: page
@@ -147,35 +160,212 @@ In addition to these explicit page attributes, the following AsciiDoc attributes
 
 * doctitle (i.e., the document title) (becomes title)
 * author
+* authors (converted to an Array of String values)
 * email
-* revdate (becomes date; value is converted to a DateTime object)
+* revdate (becomes date; value is converted to a Time object)
+* keywords (left as a String value)
+* description
 
 TIP: You can continue to specify page data using the front matter header.
 The AsciiDoc `page-` attributes override matching entries in the front matter header.
 
+NOTE: If you specify a time zone in the value of the `revdate` attribute, that time zone is honored.
+Otherwise, the date specified is assumed to have the time zone set for the application.
+You can define the application time zone in [.path]_config.rb_ using `set :time_zone` (a setting shared with the blog extension).
+If you don't specify a time zone in the page's date or for the application, dates are assumed to be UTC.
+
 === Specifying a Layout
 
 The most important of these page attributes is `page-layout`, which determines the layout that is applied to the page.
 Middleman will look for the first file that matches this root name under the source directory and use it as the layout.
-For example, if `page-layout` has the value page, Middleman might resolve a layout named [.path]_layout.erb_.
-You can fix the extension of the layout file using the `page-layout-engine` attribute.
+For example, if `page-layout` has the value `page`, Middleman might resolve a layout named [.path]_page.erb_.
+You can set the extension of the layout file using the `page-layout-engine` attribute.
 
 If a layout is not specified, or the value of the `page-layout` attribute is empty, the default layout for the site is used.
 
-If the `page-layout` attribute is unset, the AsciiDoc processor will generated a standalone document (`header_footer: true`).
+You can set a default layout for all pages in [.path]_config.rb_ using:
+
+[source,ruby]
+----
+set :layout, :name_of_layout
+----
+
+Alternately, you can set a default layout just for AsciiDoc-based pages (pages processed by this extension) in [.path]_config.rb_ using:
+
+[source,ruby]
+----
+activate :asciidoc, layout: :name_of_layout
+----
+
+TIP: When you define the layout in [.path]_config.rb_, you can specify the value either as a String or a Symbol.
+
+If you don't set the layout in [.path]_config.rb_, the default layout is considered unset.
+(The one exception to this rule is the layout for blog articles, which is controlled by the configuration for the blog extension).
+
+AsciiDoc-based pages are configured to use the automatic layout by default (i.e., the `page-layout` attribute is set to blank).
+If you unset the `page-layout` attribute, the AsciiDoc processor will handle generating 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.
 
-To review, here are the different ways to specify a layout:
+Here are the different ways to specify a layout:
 
-* `:page-layout: default` -- use the page layout named "`default`" (e.g., [.path]_default.erb_)
-* `:!page-layout:` -- no layout; generate a standalone HTML document
-* `:page-layout:` -- use the auto-detected layout
-* _(not specified)_ -- use the auto-detected layout
+* `:page-layout:`, `:page-layout: _auto_layout`, or _not specified_ -- use the automatic layout (default: layout)
+* `:page-layout: custom` -- use the page layout named "`custom`" (e.g., [.path]_custom.erb_)
+* `:!page-layout:` or `:page-layout: false` -- generate a standalone HTML document
+* `:page-layout: -` -- no layout (don't wrap content in a layout at all)
 
 .Layout for blog posts
-WARNING: If you're using the Middleman Blog extension to write blog posts, you *must* specify the page layout using the `page-layout` attribute for each post written in AsciiDoc.
-Otherwise, an exception will be thrown.
-This requirement will be lifted once the fix for https://github.com/middleman/middleman-blog/issues/296[issue middleman-blog#296] makes it into a release.
+WARNING: If you're using the Middleman Blog extension to write blog posts, the `layout` property on the blog configuration overrides the default layout, but you can still override that setting using the `page-layout` attribute in each post.
+
+=== Ignoring a Page
+
+In addition to the normal ignore filter in Middleman, you can also control whether a page is ignored from AsciiDoc.
+To mark a page as ignored from AsciiDoc, set the `page-ignored` attribute in the AsciiDoc document header to any value other than `false`, as follows:
+
+[source,asciidoc]
+----
+= Ignored Page
+:page-ignored:
+----
+
+Once this page attribute is detected, no further processing is performed on the document by this extension.
+
+=== Marking an Article as a Draft
+
+If you're using the Middleman Blog extension, you can mark an article as a draft so it does not get published.
+To do so, assign the value `false` the page attribute named `page-published` in the AsciiDoc document header, as follows:
+
+[source,asciidoc]
+----
+= Draft Article
+:page-published: false
+----
+
+This effectively sets the `published` key in the page data to `false`.
+Recall that the AsciiDoc extension converts the value of page attributes as a YAML value, which means the string literal "`false`" becomes the boolean value `false`.
+Middleman then knows not to publish this article.
+
+Another option is to set the date of the article way into the future.
+
+[source,asciidoc]
+----
+= Future Post
+Author Name
+3001-01-01
+----
+
+By default, the blog extension does not publish articles with a future date.
+
+=== Linking Between Pages
+
+You can link from one page to another using an {uri-asciidoctor}/docs/user-manual/#inter-document-cross-references[inter-document xref].
+Let's say you have the following two pages in the source directory:
+
+* about.adoc
+* team.adoc
+
+You can link from the about page to the team page using the following:
+
+[source,asciidoc]
+----
+Meet our <<team.adoc#,team>>.
+----
+
+The `.adoc#` suffix indicates the xref targets another page.
+The target is the path from the current page to the other page (a source-to-source reference).
+This reference is then converted to the following HTML:
+
+[source,html]
+----
+Meet our <a href="team.html">team</a>.
+----
+
+Of course, we're assuming there that the input maps 1-to-1 to the output.
+That assumption breaks down as soon as you enable directory indexes.
+
+When directory indexes are enabled, each page is moved into its own folder and renamed to index.html.
+So how does the xref work in that case?
+
+This extension provides built-in support for directory indexes.
+When the directory indexes extension is enabled, this extension automatically defines the `relfileprefix` and `relfilesuffix` attributes on the AsciiDoc document.
+The `relfilesuffix` attribute honors both the `:trailing_slash` and `:strip_index_file` options in Middleman.
+However, you have to make one change to your pages for these attributes to work with the xref macro.
+
+Below the document header (but *not in* the document header), you must assign the `outfilesuffix` attribute to the value of the `relfilesuffix` attribute.
+Here's an example:
+
+[source,asciidoc]
+----
+= About Us
+
+// ^ the previous blank line is required!
+\ifdef::relfilesuffix[:outfilesuffix: {relfilesuffix}]
+
+...
+
+Meet our <<team.adoc#,team>>.
+----
+
+With the help of the `outfilesuffix` assignment, Asciidoctor automatically produces the correct link to the other page.
+
+[source,html]
+----
+Meet our <a href="../team/">team</a>.
+----
+
+Optionally, you can construct the link manually using:
+
+[source,asciidoc]
+----
+Meet our link:{relfileprefix}team{relfilesuffix}[team].
+----
+
+I think you'll agree that using the xref macro is simpler.
+
+=== Controlling the Destination Path
+
+By default, Middleman does not support controlling the destination path from the page data, often called a permalink.
+However, with the addition of a simple extension, it's possible to enable this feature.
+
+Start by adding the following Ruby code to the file [.path]_lib/permalink.rb_.
+
+.lib/permalink.rb
+[source,ruby]
+----
+class Permalink < Middleman::Extension
+  # Run after front matter extension (priority: 20), after the AsciiDoc extension (priority: 30),
+  # and before other third-party extensions (priority: 50).
+  self.resource_list_manipulator_priority = 35
+
+  def manipulate_resource_list resources
+    resources.each do |resource|
+      if !resource.ignored? && (resource.respond_to? :data) && (permalink = resource.data.permalink)
+        permalink = permalink.slice 1, permalink.length if permalink.start_with? '/'
+        resource.destination_path = %(#{permalink}#{resource.ext})
+      end
+    end
+  end
+end
+
+Middleman::Extensions.register :permalink, Permalink
+----
+
+Next, require and activate this extension in the [.path]_config.rb_ file for your site:
+
+[source,ruby]
+----
+require_relative 'lib/permalink'
+activate :permalink
+----
+
+You can now customize the destination path for any AsciiDoc-based page by adding the following attribute entry to the document header:
+
+[source,asciidoc]
+----
+:page-permalink: custom-destination-path
+----
+
+Customize the destination path to your liking.
+The leading forward slash (`/`) is optional.
 
 == Building Your Site
 
@@ -229,6 +419,6 @@ Here's how to clone the project and run the tests.
 
 == Copyright
 
-Copyright (C) 2014-2016 Dan Allen and the Asciidoctor Project.
+Copyright (C) 2014-2017 Dan Allen and the Asciidoctor Project.
 Free use of this software is granted under the terms of the MIT License.
 For the full text of the license, see the <<LICENSE.adoc#,LICENSE>> file.