premonition 1.0.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5c6cb2b3b2a0a1819165e8f659d5155283ea02b2
-  data.tar.gz: 93837406183c136e70a64481b8d7c6c1b8c5a3e9
+SHA256:
+  metadata.gz: e9a29f7bec573bd93038e89e6d4c1abe04449288e8d359edad90df802e9fb80a
+  data.tar.gz: c2e036a85dfd010f8255017274efd32047d644e85edff6f1829ac3a03f08eb72
 SHA512:
-  metadata.gz: 2bd2fade3e41a00033f9e08f12884284aa2abb2d9e7162ace82f73b9b2c27d17f23a9a4866ca135bfced8391ee3406aadd150c2e9f8d9fd0660a8f686e7355cf
-  data.tar.gz: 2d8cc1b674470ed803e03d22ef67ed6f730a24a6cc3461f7d7d9a93c2a6420de9e48c9f52a23bc7011e4c5715da07feae2406258405ce3f46f1e5b8abadb228e
+  metadata.gz: 1cd9d612d1dd98610961f8b7f446591848639829b6b995b15f92701caca3f9a25ab048d4f4a800a43524f491ec1c8f5c097950713a3c47cc20b457bbbace3390
+  data.tar.gz: ad78680f73ac7f317cefd32f071a36b3616edb2d3a453b685f1ac57f642d88428ebcb595517c4a8a1beeb239b922262fc1d87cd43594ace997b5d53abf3a5081

data/README.md

@@ -1,128 +1,174 @@
 # Premonition
-Premonition is a [Jekyll](https://jekyllrb.com/) extension that makes it possible to add block-styled Markdown side content to your documentation, for example summaries, notes, hints or warnings.
 
-It recognizes a special header in [block quotes](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#blockquotes) and converts then into html before the Markdown parser
-are run. As of now it only supports the [RedCarpet Markdown parser](https://github.com/vmg/redcarpet), but Kramdown support might be added in the future if requested.
+**DEMO: https://amedia.github.io/premonition-demo/**
+
+Premonition is a [Jekyll](https://jekyllrb.com/) extension that makes it possible to add block-styled content to your site in plain Markdown.
+
+By adding a special header to the first line of a [block quote](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#blockquotes),
+Premonition will transform it into a markup block of your choice.
+
+<p align="center">
+<img src="https://github.com/amedia/premonition/raw/master/screen.png" height="450"/>
+</p>
 
 ## Features
 
- * Highly customizable
- * Non-intrusive - Content are rendered as block-quotes by any other parser
+ * Highly customizable (Create your own styles and templates easily)
+ * Non-intrusive - Content are presented as block-quotes by any other renderer.
  * Easy to install
+ * Comes with a stylesheet (Sass/Css) and templates for rendering typical information boxes.
+ * Support for both Kramdown and RedCarpet.
 
 ## Requirements
 
- * Redcarpet
  * Jekyll 3.7.x or higher
+ * FontAwesome 4.x (If you are using the default template and styles)
 
 ## Installation
 
-Add the following line to your `Gemfile` inside your Jekyll project. It should look something like this, depending on your Jekyll version:
+Add the following line to your `Gemfile`:
 
 ```
-gem "redcarpet"
 group :jekyll_plugins do
-  gem "premonition", "~> 1.0.0"
+  gem "premonition", "~> 2.0.0"
 end
 ```
-As Premonition depends on Redcarpet, you must make sure this dependency is added as well.
 
-Then add Premonition to `plugins` inside the Jekyll config file (`_config.yml`):
+Then add Premonition to `plugins` in `_config.yml`:
 
 ```yaml
 plugins:
     - premonition
 ```
 
+Finally run `bundle install`
+
 ## Usage
 
-Premonition blocks are really just standard Markdown block quote where the first line must follow a
+Premonition blocks are really just a standard Markdown blockquote where the first line must be on a
 special format to activate the transformation.
 
 `> [type] "Title"`
 
-The type can be any letter string. It is used to map a block to type configuration. This enables
-you to customize the look of different types. Like *Info*, *Warning* and *Error* boxes for example.
-By default the type will be added to the surrounding `<div>` block of the generated html code.
+The type can be any letter string. It is used to map a block to its type configuration and/or css.
+By default the type will be added as a class to the outer `<div>` of the
+generated markup.
+
+Default types are:
 
-The *Title* is as you might have guessed the title that will be added to the block.
+* note
+* info
+* warning
+* error
+
+The *Title* is the box header. It can be left empty to disable the box header:
+
+~~~markdown
+> warning ""
+> No headers in here
+~~~
 
 Example:
 
 ~~~markdown
 > warning "I am a warning"
-> The body of the warning goes here. Premonition also allow you to write Markdown inside the block.
+> The body of the warning goes here. Premonition allows you to write any `Markdown` inside the block.
 ~~~
 
-This will be converted into something like this bu Premonition
+Premonition will then convert this into something like:
 
 ~~~html
-<div class="premonition warning">
-  <span class="header">Info</span>
-  <p>The body of the warning goes here. Premonition also allow you to write Markdown inside the block.</p>
+<div class="premonition info"><div class="fa fa-check-square"></div><div class="content"><p class="header">Info</p><p>The body of the warning goes here. Premonition also allow you to write Markdown inside the block.</p></div></div>
 ~~~
 
-The title can be omitted by providing an empty string . Like this:
+You can change the markup into anything you like by adding your own template.
 
-~~~markdown
-> warning ""
-> No headers in here
-~~~
+## Configuration
 
-Now you can add some CSS styling.
+The templates can be customized in two eays. Either by replacing the default template, or by adding a custom template to a type.
 
-## Configuration
+All this is done inside your `_config.yml`.
+
+### Templates
 
-If you don't like the markup that Premonition produces, then you can change it in two ways.
-Either by replacing the default template, or by configuring templates for each type.
+Like Jekyll itself, Premonition uses the [Liquid Markup Language](https://github.com/Shopify/liquid) for its templates.
 
-All this are done inside your `_config.yml`
+Five variables are available to the template engine:
 
-### Replacing the default template
+* *header* Boolean that tells you if a title exists and that a header should be added.
+* *content* The rendered content for your block.
+* *title* The block title.
+* *type* The type name (eg: note).
+* *meta* This is a hash that can contain any properties you would like to make available to your template. It is configured in `_config.yml`
+
+Our default template:
+
+~~~html
+<div class="premonition {{type}}">
+  <div class="fa {{meta.fa-icon}}"></div>
+  <div class="content">{% if header %}<p class="header">{{title}}</p>{% endif %}{{content}}</div></div>
+~~~
+
+#### Overriding the default template
+
+You can override the default template like this in your `_config.yml`:
 
 ```yaml
 premonition:
   default:
-    template: '<div></i>%{header}%{content}</div>'
-    header_template: '<span class="header">%{title}</span>'
+    template: 'Liquid template goes here'
 ```
 
-Please be aware of the placeholders inside the template. These placeholders will be replaced with
-the actual content of your block.
+#### Overriding the template for a default type
 
-Available placeholders are
+If you want to override the template for one of the default types (like note), do it like this:
 
-* *header* This is where the content from the header_template will be added if the title is not empty.
-* *content* This is where the rendered content of your block quote are added.
-* *title* This is where you block title will be added.
-* *type* The type name of the block.
+```yaml
+premonition:
+  types:
+    - id: note
+      template: 'Liquid template goes here'
+```
 
 ### Adding custom types
 
-Sometimes you might want to have different markup for different block types. This can easily be done
-by adding types to your Premonition configuration inside `_config.yml`
+Adding a custom type is just a matter of adding it to `_config.yml`. You can either override one
+of the defaults, or add a new one.
+
+For each type you can
+
+* Add a custom template (template)
+* Set a default title (default_title)
+* Set meta data that can be used inside the template
+
+Each type must have unique id (lowercase letters).
 
 ~~~yaml
 premonition:
-  default:
-    template: '<div></i>%{header}%{content}</div>'
-    header_template: '<span class="header %{type}">%{title}</span>'
   types:
-    - id: tip
-      template: '<div class="alert alert-success" role=""><i class="fa fa-check-square-o"></i>%{header}%{content}</div>'
-    - id: note
-      template: '<div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i>%{header}%{content}</div>'
+    - id: custombox
+      meta:
+        fa-icon: fa-exclamation-circle
+    - id: advanced
+      template: 'Liquid template goes here'
+      default_title: 'MY BLOCK'
+      meta:
+        fa-icon: fa-exclamation-triangle
 ~~~
 
-NOTE: You cannot add a custom header_template to types at the moment. This will be fixed soon.
+## Styling
 
-#### Default titles
+Premonition comes with a stylesheet you can copy into to your project. Either
+as a Sass file or as plain css. The [Jekyll Documentation](https://jekyllrb.com/docs/assets/) describes the process in great details.
 
-You can add a default title to a type.
+Download the stylesheet from here : https://github.com/amedia/premonition/tree/master/stylesheet
 
-~~~yaml
-- id: tip
-      template: '<div class="alert alert-success" role=""><i class="fa fa-check-square-o"></i>%{header}%{content}</div>'
-      default_title: 'TIP!'
-~~~
+In order to get the fancy icons, you will have to add [Font Awesome](https://fontawesome.com/) to your html header file.
+Be aware that you have to use v4.x of Font Awesome together with our CSS.
+
+The easiest way to get startet with Font Awesome is to add this to your html header file:
+
+~~~html
+<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css"/>
+~~~~
 

data/lib/premonition.rb

@@ -1,4 +1,3 @@
-require 'redcarpet'
 require 'jekyll'
 require 'premonition/version'
 require 'premonition/resources'

data/lib/premonition/hook.rb

@@ -3,28 +3,16 @@ module Jekyll
     class Hook < Generator
       safe true
       priority :low
-      attr_reader :resources
 
       def initialize(p)
         super(p)
-        unless defined?(Redcarpet)
-          Jekyll::External.require_with_graceful_fail(
-            "redcarpet (in #{__FILE__})"
-          )
-        end
       end
 
       def generate(site)
-        @resources = Resources.new site
-        Hooks.register :documents, :pre_render do |doc|
+        @resources = Resources.new site.config
+        Hooks.register [:documents, :pages], :pre_render do |doc|
           adder(doc)
         end
-        Hooks.register :pages, :pre_render do |page|
-          adder(page)
-        end
-        Hooks.register :posts, :pre_render do |page|
-          adder(page)
-        end
       end
 
       def adder(doc)
@@ -34,12 +22,12 @@ module Jekyll
           if blockquote?(l) && empty_block?(b)
             if (m = l.match(/^\>\s+([a-z]+)\s+\"(.*)\"$/i))
               y, t = m.captures
-              b = { title: t.strip, type: y.strip.downcase, content: [] }
+              b = { 'title' => t.strip, 'type' => y.strip.downcase, 'content' => [] }
             else
               o << l
             end
           elsif blockquote?(l) && !empty_block?(b)
-            b[:content] << l.match(/^\>(.*)$/i).captures[0].strip
+            b['content'] << l.match(/^\>\s?(.*)$/i).captures[0]
           else
             if !blockquote?(l) && !empty_block?(b)
               o << render_block(b)
@@ -61,37 +49,32 @@ module Jekyll
       end
 
       def render_block(b)
-        t = create_templ(b)
-        c = "#{@resources.renderer.render(b[:content].join("\n"))}\n\n"
-        v = {
-          title: t[:title],
-          content: c,
-          type: b[:type]
-        }
-        v[:header] = header(t[:title]) % v
-        clean_markup(t[:template] % v)
-      end
-
-      def clean_markup(r)
-        br = '<br>' * 2
-        r = r.gsub('<p>', '').gsub('</p>', br).strip
-        r = r.gsub(br, '') if r.scan(/<br><br>/m).size == 1
-        r
-      end
-
-      def header(t)
-        t.empty? ? '' : @resources.config[:default][:header_template]
+        t = create_resource(b)
+        c = "#{@resources.markdown.convert(b['content'].join("\n"))}\n\n"
+        template = Liquid::Template.parse(t['template'], error_mode: :strict)
+        template.render(
+          {
+            'header' => !t['title'].nil?,
+            'title' => t['title'],
+            'content' => c,
+            'type' => b['type'],
+            'meta' => t['meta']
+          },
+          strict_variables: true
+        )
       end
 
-      def create_templ(b)
+      def create_resource(b)
         c = {
-          template: @resources.config[:default][:template],
-          title: @resources.config[:default][:title]
+          'template' => @resources.config['default']['template'],
+          'title' => @resources.config['default']['title'],
+          'meta' => @resources.config['default']['meta']
         }
-        @resources.config[:types].each do |t|
-          next unless t[:id] == b[:type]
-          c[:title] = b[:title].empty? ? t[:default_title] : b[:title]
-          c[:template] = t[:template]
+        @resources.config['types'].each do |id, t|
+          next unless id == b['type']
+          c['title'] = b['title'].empty? || b['title'].nil? ? t['default_title'] : b['title']
+          c['template'] = t['template'] unless t['template'].nil?
+          c['meta'] = c['meta'].merge(t['meta']) unless t['meta'].nil?
         end
         c
       end

data/lib/premonition/resources.rb

@@ -2,63 +2,71 @@ module Jekyll
   module Premonition
     class Resources
       attr_reader :config
-      attr_reader :renderer
+      attr_reader :markdown
 
-      def initialize(site)
-        @config = load_config site
-        @renderer = create_renderer site
+      def initialize(site_config)
+        @config = load site_config
+        @markdown = Converters::Markdown.new site_config
       end
 
-      def create_renderer(site)
-        hsh = {}
-        ext_lookup(site).each { |a| hsh[a] = true }
-        Redcarpet::Markdown.new(Redcarpet::Render::HTML, hsh)
-      end
-
-      def ext_lookup(site)
-        ((site.config['redcarpet'] || {})['extensions'] || [])
-      end
-
-      def load_config(site)
-        cfg = create_default_config
-        prem = site.config['premonition'] || {}
-        df = prem['default'] || {}
-        cfg[:default][:template] = df['template'].strip unless df['template'].nil?
-        cfg[:default][:header_template] = df['header_template'].strip unless df['header_template'].nil?
-        cfg[:default][:title] = df['title'].strip unless df['title'].nil?
-        unless prem['types'].nil?
-          fail('types configuration must be an array') unless prem['types'].is_a?(Array)
-          prem['types'].each { |t| cfg[:types] << load_config_type(t) }
-        end
+      def load(site_config)
+        cfg = default_config
+        p = site_config['premonition'] || {}
+        df = p['default'] || {}
+        validate_defaults df, p
+        cfg['default']['template'] = df['template'].strip unless df['template'].nil?
+        cfg['default']['title'] = df['title'].strip unless df['title'].nil?
+        cfg['default']['meta'] = cfg['default']['meta'].merge(df['meta']) unless df['meta'].nil?
+        load_types p, cfg
         cfg
       end
 
-      def load_config_type(t)
-        validate_config_type(t)
+      def default_config
         {
-          id: t['id'],
-          template: t['template'].strip,
-          default_title: (t['default_title'].nil? ? '' : t['default_title'].strip)
+          'default' => {
+            'template' => '<div class="premonition {{type}}"><div class="fa {{meta.fa-icon}}"></div>'\
+              '<div class="content">{% if header %}<p class="header">{{title}}</p>{% endif %}{{content}}</div></div>',
+            'meta' => { 'fa-icon' => 'fa-check-square' },
+            'title' => nil
+          },
+          'types' => {
+            'note' => { 'meta' => { 'fa-icon' => 'fa-check-square' } },
+            'info' => { 'meta' => { 'fa-icon' => 'fa-info-circle' } },
+            'warning' => { 'meta' => { 'fa-icon' => 'fa-exclamation-circle' } },
+            'error' => { 'meta' => { 'fa-icon' => 'fa-exclamation-triangle' } }
+          }
         }
       end
 
-      def validate_config_type(t)
-        fail('id missing from type') if t['id'].nil?
-        fail("id can only be lowercase letters: #{t['id']}") unless t['id'][/[a-z]+/] == t['id']
-        fail('template missing from type') if t['template'].nil?
+      def validate_defaults(df, prem)
+        fail 'meta must be a hash' if !df['meta'].nil? && !df['meta'].is_a?(Hash)
+        fail 'types must be a hash' if !prem['types'].nil? && !prem['types'].is_a?(Hash)
       end
 
-      def create_default_config
+      def load_types(p, cfg)
+        return if p['types'].nil?
+        p['types'].each do |id, obj|
+          t = type_config id, obj
+          cfg['types'][id] = cfg['types'][id].merge(t) unless cfg['types'][id].nil?
+          cfg['types'][id] = t if cfg['types'][id].nil?
+        end
+      end
+
+      def type_config(id, t)
+        validate_type(id, t)
         {
-          default: {
-            template: '<div class="premonition %{type}">%{header}%{content}</div>',
-            header_template: ' <span class="header">%{title}</span>',
-            title: 'Info'
-          },
-          types: []
+          'template' => t['template'].nil? ? nil : t['template'].strip,
+          'default_title' => t['default_title'].nil? || t['default_title'].empty? ? nil : t['default_title'].strip,
+          'meta' => t['meta'].nil? ? {} : t['meta']
         }
       end
 
+      def validate_type(id, t)
+        fail 'id missing from type' if id.nil?
+        fail "id can only be lowercase letters: #{id}" unless id[/[a-z]+/] == id
+        fail 'meta must be an hash' if !t['meta'].nil? && !t['meta'].is_a?(Hash)
+      end
+
       def fail(msg)
         Jekyll.logger.error 'Fatal (Premonition):', msg
         raise LoadError, msg

data/lib/premonition/version.rb

@@ -1,5 +1,5 @@
 module Jekyll
   module Premonition
-    VERSION = '1.0.2'.freeze
+    VERSION = '2.0.0'.freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: premonition
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 2.0.0
 platform: ruby
 authors:
 - Jakob Vad Nielsen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-06 00:00:00.000000000 Z
+date: 2018-02-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -44,6 +44,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -59,19 +73,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: turn
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '0'
 description: 
 email:
 - jakob.nielsen@amedia.no
@@ -107,7 +121,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.7.3
 signing_key: 
 specification_version: 4
 summary: Jekyll generator that will convert special block quotes into message boxes.