jekyll-asciidoc 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 97faf9f23f10a720b2ac0b8110ccd556ce089a34
-  data.tar.gz: ebdeb3ce72ecb28138262ef94bd995f65e5b8e7e
+  metadata.gz: 038ace39e983d8f6e710306e70ba7acd02af1c80
+  data.tar.gz: 81a0bed37126dce92290fb9fc8eb20369e9c27be
 SHA512:
-  metadata.gz: 6f498445e512a283e7b7599efe904e8a58713bb01b10c8441e345749d580818ba794fd7014d2a5e5cc889870d11a37238b49bc05cb309442e5aa6eff0288860f
-  data.tar.gz: b10dc4780ab898db1059665f79c3b433dcebd1b078967d16b51ae315c68613ac73fb84710d4df2b51e04f55c6d14c4ee24f0b73871426c31b6d931a0c9a9364d
+  metadata.gz: 67b47225a5f907acd69454fe83570c95192ec9b07e968ebeb23b4a192aa912f19a5025ed74cab9e73461c2a1c5d31364a67d988fae00a10ba11f4846a0cf4db1
+  data.tar.gz: 02bb49e0c9b2a1943ab637fd9e8def0d6e06cf490fc7af444b80feccdfccb1ec9b93463652e52c7428c7cd25812c12c408099d599cc5afaed3e443620ea434b4

data/README.adoc

@@ -1,7 +1,13 @@
 = Jekyll AsciiDoc Plugin (powered by Asciidoctor)
-Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
+Paul Rayner <https://github.com/paulrayner[@paulrayner]>; Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
+:toc: preamble
+:toclevels: 1
 
-A http://jekyllrb.com[Jekyll] plugin that converts http://asciidoc.org[AsciiDoc] files in your site source to HTML pages using http://asciidoctor.org[Asciidoctor].
+image:https://badge.fury.io/rb/jekyll-asciidoc.svg["Gem Version", link="https://badge.fury.io/rb/jekyll-asciidoc"]
+
+A plugin for http://jekyllrb.com[Jekyll] that converts http://asciidoc.org[AsciiDoc] files in your site source to HTML pages using http://asciidoctor.org[Asciidoctor].
+
+== Overview
 
 The plugin consists of three extensions:
 
@@ -12,16 +18,16 @@ The plugin consists of three extensions:
 `Jekyll::Filters.asciidocify`::
   A Liquid filter for converting AsciiDoc content to HTML using the AsciiDocConverter
 
-All these extensions are included in the file `lib/asciidoc_plugin.rb`.
+These extensions are loaded automatically when the jekyll-asciidoc is required.
 
 == Installation
 
-The plugin depends on the Asciidoctor gem (named http://rubygems.org/gems/asciidoctor[asciidoctor]).
+The plugin depends on the http://rubygems.org/gems/asciidoctor[asciidoctor] gem.
 You can install the gem using:
 
  $ gem install asciidoctor
 
-If you are using Bundler to manage the dependencies in your Jekyll project, then add the Asciidoctor gem to your `Gemfile` (below the Jekyll gem, named jekyll):
+If you're using Bundler to manage the dependencies in your Jekyll project, instead add the asciidoctor gem to your [path]_Gemfile_ (beneath the jekyll gem):
 
 [source,ruby]
 ----
@@ -31,7 +37,7 @@ gem 'jekyll'
 gem 'asciidoctor'
 ----
 
-Then, run the Bundler install command
+Then, run the Bundler install command:
 
  $ bundle install
 
@@ -39,45 +45,49 @@ Then, run the Bundler install command
 
 Using Bundler::
 +
-Add `jekyll-asciidoc` plugin gem to your `Gemfile`
-+
+--
+Add the `jekyll-asciidoc` plugin gem to your [path]_Gemfile_
+
 [source,ruby]
-----
 group :jekyll_plugins do
-  gem "jekyll-asciidoc"
+  gem 'jekyll-asciidoc'
 end
-----
-+
+
 Then, run the Bundler command to install it:
 
  $ bundle install
+--
 
 Without Bundler::
 +
+--
 If you are not using Bundler for managing Jekyll then install gems manually
-+
- $ gem install jekyll-asciidoc 
-+
-And then, add `jekyll-asciidoc` gem to the list of gems for Jekyll to load in your site's `_config.yml` file:
-+
+
+ $ gem install jekyll-asciidoc
+
+And then, add the `jekyll-asciidoc` gem to the list of gems for Jekyll to load in your site's [path]_{empty}_config.yml_ file:
+
 [source,yaml]
-----
 gems:
   - jekyll-asciidoc
-----
+--
 
 === Installing development version of the plugin
 
-To install the development version of this plugin, copy `lib/asciidoc_plugin.rb` to the `_plugins` directory in the root of your site source.
+To install the development version of this plugin, use:
 
-NOTE: If no `_plugins` directory exists, you need to first create it.
+ $ rake install
 
-== Creating Pages
+An alternative--though not recommend--approach is to copy the file [path]_lib/jekyll-asciidoc.rb_ to the [path]_{empty}_plugins_ directory in the root of your site source.
+
+NOTE: If the [path]_{empty}_plugins_ directory does not exist, you need to first create it.
+
+== Creating pages
 
 To add a page composed in AsciiDoc, simply add an AsciiDoc file to the root of the project with an AsciiDoc file extension.
 
 .sample.adoc
-[source,asciidoc]
+[listing]
 ....
 ---
 ---
@@ -100,7 +110,7 @@ You can use an empty front matter header, as shown above, or you can define all
 You can now build your site using:
 
  $ jekyll build
- 
+
 and preview it using:
 
  $ jekyll serve
@@ -109,26 +119,26 @@ If you are using Bundler then use following commands to do the same
 
  $ bundle exec jekyll build
  $ bundle exec jekyll serve
- 
+
 IMPORTANT: If you use the `--safe` option, the AsciiDoc plugin will not be activated.
 The `--safe` flag disables third-party plugins such as this one.
 
-== Configuration (Optional)
+== Configuration (optional)
 
 By default, this plugin uses Asciidoctor to convert AsciiDoc files.
-Since Asciidoctor is the only option, the default setting is equivalent to the following configuration in `_config.yml`:
+Since Asciidoctor is the only option, the default setting is equivalent to the following configuration in [path]_{empty}_config.yml_:
 
 [source,yaml]
 asciidoc: asciidoctor
 
-To tell Jekyll which extensions to recognize as AsciiDoc files, add the following line to your `_config.yml`:
+To tell Jekyll which extensions to recognize as AsciiDoc files, add the following line to your [path]_{empty}_config.yml_:
 
 [source,yaml]
 asciidoc_ext: asciidoc,adoc,ad
 
 The extensions shown in the previous listing are the default values, so you don't need to specify this option if those defaults are sufficient.
 
-To pass additional attributes to AsciiDoc, or override the default attributes defined in the plugin, add the following lines to your `_config.yml`:
+To pass additional attributes to AsciiDoc, or override the default attributes defined in the plugin, add the following lines to your [path]_{empty}_config.yml_:
 
 [source,yaml]
 asciidoctor:
@@ -137,18 +147,196 @@ asciidoctor:
     - source-highlighter=pygments
     - pygments-css=style
 
-=== Hard line breaks
+=== Disabling hard line breaks
 
 The Jekyll AsciiDoc integration is configured to preserve hard line breaks in paragraph content by default.
 Since many Jekyll users are used to writing in GitHub-flavored Markdown (GFM), this default was selected to ease the transition to AsciiDoc.
-If you want the standard AsciiDoc behavior of collapsing hard line breaks in paragraph content, add the following settings to your site's `_config.yml` file:
+If you want the standard AsciiDoc behavior of collapsing hard line breaks in paragraph content, add the following settings to your site's [path]_{empty}_config.yml_ file:
 
 [source,yaml]
 asciidoctor:
   attributes:
     - hardbreaks!
 
-If you already have AsciiDoc attributes defined in the `_config.yml`, the `hardbreaks!` attribute should be added as a sibling entry in the YAML collection.
+If you already have AsciiDoc attributes defined in the [path]_{empty}_config.yml_, the `hardbreaks!` attribute should be added as a sibling entry in the YAML collection.
+
+== Enabling Asciidoctor Diagram (optional)
+
+Asciidoctor Diagram is a set of extensions for Asciidoctor that allow you to embed diagrams written using the PlantUML, Graphviz, ditaa, or Shaape syntax inside your AsciiDoc documents.
+
+[IMPORTANT]
+For Graphviz and PlantUML diagram generation, http://www.graphviz.org[Graphviz] must be installed (i.e., the `dot` utility must be available on your `$PATH`.
+
+=== Installation
+
+Using Bundler::
++
+--
+Add `asciidoctor-diagram` gem to your [path]_Gemfile_
+
+[source,ruby]
+----
+group :jekyll_plugins do
+  ....
+  gem 'asciidoctor-diagram', '>= 1.3.1' <1>
+  ...
+end
+----
+<1> version can be configured differently
+
+Then, run the Bundler command to install it:
+
+ $ bundle install
+--
+
+Without Bundler::
++
+--
+Install gems manually
+
+ $ gem install asciidoctor-diagram
+
+Then, add the `asciidoctor-diagram` gem to the list of gems for Jekyll to load in your site's [path]_{empty}_config.yml_ file:
+
+[source,yaml]
+gems:
+  - asciidoctor-diagram
+--
+
+Both of the previous configurations are the equivalent of passing `-r asciidoctor-diagram` to the `asciidoctor` command.
+
+=== Generated image location
+
+By default diagram images are generated in the root folder.
+Thus, images URLs are not properly referenced from the generated HTML pages.
+
+To fix this, set the `imagesdir` attribute in any AsciiDoc file that contains diagrams.
+
+._posts/2015-12-24-diagrams.adoc
+[listing]
+....
+---
+---
+= Diagrams
+:imagesdir: /images/2015-12-24 <1>
+
+[graphviz, dot-example, svg]
+----
+digraph g {
+    a -> b
+    b -> c
+    c -> d
+    d -> a
+}
+----
+....
+<1> the date in the imagesdir value must match the date of the post (e.g., 2015-12-24)
+
+WARNING: The images are generated after Jekyll copies assets to the [path]_{empty}_site_ directory.
+Therefore, you'll have to run `jeykll` twice before you see the images in the preview.
+
+== Supplemental AsciiDoc Assets
+
+Certain Asciidoctor features, such as icons, require additional CSS rules and other assets to work.
+These CSS rules and other assets do not get automatically included in the pages generated by Jekyll.
+This section documents how to configure these additional resources.
+
+TIP: If you want to take a shortcut that skips all this configuration, clone the https://github.com/asciidoctor/jekyll-asciidoc-quickstart[Jekyll AsciiDoc Quickstart (JAQ)] repository and use it as a starting point for your site.
+JAQ provides a page layout out of the box configured to fully style body content generated from AsciiDoc.
+
+=== Setup
+
+The Jekyll AsciiDoc plugin converts AsciiDoc to embeddable HTML.
+This HTML is then inserted into the page layout.
+You need to augment the page layout to include resources typically present in a standalone HTML document that Asciidoctor produces.
+
+. Create a stylesheet in the [path]_css_ directory named [path]_asciidoc.css_ to hold additional CSS for body content generated from AsciiDoc.
+. Add this stylesheet to the HTML `<head>` in [path]_{empty}_includes/head.html_ under the main.css declaration:
++
+[source,html]
+<link rel="stylesheet" href="{{ "/css/asciidoc.css" | prepend: site.baseurl }}">
+
+=== Font-based Admonition and Inline Icons
+
+To enable font-based admonition and inline icons, you first need to add Font Awesome to [path]_{empty}_includes/head.html_ file under the asciidoc.css declaration:
+
+[source,html]
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.4.0/css/font-awesome.min.css">
+
+NOTE: You can also link to local copy of Font Awesome.
+
+Next, you need to add the following CSS rules from the default Asciidoctor stylesheet to the [path]_css/asciidoc.css_ file:
+
+[source,css]
+----
+span.icon>.fa {
+  cursor: default;
+}
+.admonitionblock td.icon {
+  text-align: center;
+  width: 80px;
+}
+.admonitionblock td.icon [class^="fa icon-"] {
+  font-size: 2.5em;
+  text-shadow: 1px 1px 2px rgba(0,0,0,.5);
+  cursor: default;
+}
+.admonitionblock td.icon .icon-note:before {
+  content: "\f05a";
+  color: #19407c;
+}
+.admonitionblock td.icon .icon-tip:before {
+  content: "\f0eb";
+  text-shadow: 1px 1px 2px rgba(155,155,0,.8);
+  color: #111;
+}
+.admonitionblock td.icon .icon-warning:before {
+  content: "\f071";
+  color: #bf6900;
+}
+.admonitionblock td.icon .icon-caution:before {
+  content: "\f06d";
+  color: #bf3400;
+}
+.admonitionblock td.icon .icon-important:before {
+  content: "\f06a";
+  color: #bf0000;
+}
+----
+
+Feel free to modify the CSS to your liking.
+
+Finally, you need to enable the font-based icons in the header of the document:
+
+ :icons: font
+
+or in the site configuration:
+
+[source,yaml]
+asciidoctor:
+  attributes:
+    - icons=font
+    ...
+
+=== Image-based Admonition and Inline Icons
+
+As an alternative to font-based icons, you can configure Asciidoctor to use image-based icons.
+In this case, all you need to do is provide the icons at the proper location.
+
+First, enable image-based icons and configure the path to the icons in the header of the document:
+
+ :icons:
+ :iconsdir: /images/icons
+
+or your site configuration:
+
+[source,yaml]
+asciidoctor:
+  attributes:
+    - icons
+    - iconsdir=/images/icons
+
+Then, simply put the icon images that the page needs in the [path]_images/icons_ directory.
 
 == GitHub Pages
 
@@ -162,3 +350,20 @@ Refer to the tutorial http://eshepelyuk.github.io/2014/10/28/automate-github-pag
 You can also refer to the https://github.com/johncarl81/transfuse/tree/transfuse-jeykll-site[Tranfuse website build^] for an example in practice.
 
 Refer to the https://help.github.com/articles/using-jekyll-plugins-with-github-pages[Jekyll Plugins on GitHub Pages] for a list of the plugins currently supported on the server-side (in addition to Markdown, which isn't listed).
+
+== Releasing the gem to RubyGems.org
+
+When you are ready for a release, first set the version in the file [path]_lib/jekyll-asciidoc/version.rb_.
+Then, commit the change using the following commit message template:
+
+ Release X.Y.Z
+
+where `X.Y.Z` is the version number of the gem.
+
+Next, package, tag and release the gem to RubyGems.org, run the following rake task:
+
+ $ rake release
+
+IMPORTANT: Ensure you have the proper credentials setup as described in the guide http://guides.rubygems.org/publishing/#publishing-to-rubygemsorg[Publishing to RubyGems.org].
+
+Once you finish the release, you should update the version to the next micro version in the sequence using the `.dev` suffix (e.g., 1.0.1.dev).

data/Rakefile

@@ -6,6 +6,10 @@ begin
   require 'bundler/gem_tasks'
   default_tasks << :build
 rescue LoadError
+  warn 'jekyll-asciidoc: Bundler is required to build this gem.
+You can install Bundler using the `gem install` command:
+
+ $ gem install bundler' + %(\n\n)
 end
 
 task :default => default_tasks unless default_tasks.empty?

data/lib/jekyll-asciidoc.rb

@@ -1,3 +1,5 @@
+JEKYLL_MIN_VERSION_3 = Gem::Version.new(Jekyll::VERSION) >= Gem::Version.new('3.0.0') unless defined? JEKYLL_MIN_VERSION_3
+
 module Jekyll
   module Converters
     class AsciiDocConverter < Converter
@@ -17,7 +19,7 @@ module Jekyll
         end
         @asciidoctor_config[:safe] ||= 'safe'
         user_defined_attributes = @asciidoctor_config[:attributes]
-        @asciidoctor_config[:attributes] = %w(notitle! hardbreaks idprefix= idseparator=- linkattrs)
+        @asciidoctor_config[:attributes] = %w(notitle hardbreaks idprefix= idseparator=- linkattrs)
         unless user_defined_attributes.nil?
           @asciidoctor_config[:attributes].concat(user_defined_attributes)
         end
@@ -81,7 +83,9 @@ module Jekyll
     # Promotes select AsciiDoc attributes to Jekyll front matter
     class AsciiDocPreprocessor < Generator
       def generate(site)
-        asciidoc_converter = site.getConverterImpl(Jekyll::Converters::AsciiDocConverter)
+        asciidoc_converter = JEKYLL_MIN_VERSION_3 ?
+            site.find_converter_instance(Jekyll::Converters::AsciiDocConverter) :
+            site.getConverterImpl(Jekyll::Converters::AsciiDocConverter)
         asciidoc_converter.setup
         key_prefix = (site.config['asciidoc_key_prefix'] || 'jekyll-')
         key_prefix_len = key_prefix.length
@@ -108,8 +112,8 @@ module Jekyll
             end
           end
         end
-        site.posts.each do |post|
-          if asciidoc_converter.matches(post.ext)
+        (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)
             doc = asciidoc_converter.load(post.content)
             next if doc.nil?
 
@@ -146,7 +150,9 @@ module Jekyll
     # Returns the HTML formatted String.
     def asciidocify(input)
       site = @context.registers[:site]
-      converter = site.getConverterImpl(Jekyll::Converters::AsciiDocConverter)
+      converter = JEKYLL_MIN_VERSION_3 ?
+          site.find_converter_instance(Jekyll::Converters::AsciiDocConverter) :
+          site.getConverterImpl(Jekyll::Converters::AsciiDocConverter)
       converter.convert(input)
     end
   end

data/lib/jekyll-asciidoc/version.rb

@@ -0,0 +1,5 @@
+module Jekyll
+  module AsciiDoc
+    VERSION = '1.0.1'
+  end
+end

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-asciidoc
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Dan Allen
-- Paul Rayner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-08 00:00:00.000000000 Z
+date: 2016-03-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -25,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.4
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
 - !ruby/object:Gem::Dependency
   name: jekyll
   requirement: !ruby/object:Gem::Requirement
@@ -43,7 +56,6 @@ description: A Jekyll plugin that converts AsciiDoc files in your site source to
   pages using Asciidoctor.
 email:
 - dan.j.allen@gmail.com
-- paul@virtual-genius.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -52,6 +64,7 @@ files:
 - README.adoc
 - Rakefile
 - lib/jekyll-asciidoc.rb
+- lib/jekyll-asciidoc/version.rb
 homepage: https://github.com/asciidoctor/jekyll-asciidoc
 licenses:
 - MIT
@@ -72,10 +85,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: A Jekyll plugin that converts AsciiDoc files in your site source to HTML
   pages using Asciidoctor.
 test_files: []
-has_rdoc: