premonition 4.0.0.pre3 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: abfe46c768bd3eb585a45c353bfec07ec3949d9e429fa6ad33048c7ea95f1073
-  data.tar.gz: f4faec4011c684028b26ad4a6d8e4e1f898d39b430be3d52699811ae874de136
+  metadata.gz: c5958da36843569e59519ea1ccf58975c8604a2f087d9b0a21c2b0b85c945773
+  data.tar.gz: c1fb3d763996a86bc7ca3dadf0a72b2afcbeb8cfad7196c6099e9dd82dd77751
 SHA512:
-  metadata.gz: d7e50e23298fdba22b884c1a26b1c7ccb6cc4210c0c08b20d0bb29e40e2034c60fbb253e5f1b542b6109fd82d3d878cc95e3da18887e2bb409393daf6ed2a978
-  data.tar.gz: a419bd8dca3eadc59799eefbea6b7738a316629f45aa925c146482e202633a6685550f23fc0e15a17075f0d3bbc42ce68085786c6391333b6b420ef5df8e1cb5
+  metadata.gz: 92953692e95d66d1913d8a924b8db826379168e7fb2746501f1f693f8183fe00a320b29a47c3163915f88329d94ac7dde0bf14ffb760ae9c5931be54f7a157e7
+  data.tar.gz: ef822540e419bdc92f6a154ae388120f07289f499bb6f8e95888d3d9c44339ecfed3b5e550d4e5b1d38e89c74ed6f13e68e29084ee15cb628479c0ad950af420

data/README.md

@@ -1,51 +1,49 @@
 # Premonition
 
-NOTE: This is the documentation for the version 4 release, coming soon. For 2.x documentation, please switch to the `2.x` branch.
-
 [Demo site](https://lazee.github.io/premonition-demo/) ([Source code](https://github.com/lazee/premonition-demo))
 
-Premonition is a higly customizable [Jekyll](https://jekyllrb.com/) plugin that can convert Markdown block-quotes into beautiful block styled content. 
+Premonition is a higly customizable [Jekyll](https://jekyllrb.com/) plugin that can convert Markdown block-quotes into beautiful block styled content.
 
 By simply adding a custom 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/lazee/premonition/raw/master/screen.png" height="450"/>
+<img src="https://github.com/lazee/premonition/raw/master/screen.png" height="550"/>
 </p>
 
 ## Features
 
- * Highly customizable (Create your own styles and templates easily)
- * Non-intrusive - Its just Markdown!
- * Easy to install
- * Comes with a default stylesheet (Sass/Css) and templates for beautiful messages boxes and citation.
- * Font Awesome 5 support
-
- ## Version 4 Highlights
-
- * Jekyll [Post Excerpts](https://jekyllrb.com/docs/posts/#post-excerpts) support
- * New install command for the default stylesheet.
- * [Kramdown reference links](https://kramdown.gettalong.org/quickref.html#links-and-images) support
- * Jekyll 4 support (3.7 still supported)
- * Added support for block attributes (See documentation further down)
- * Added new citation block type.
- * Minor fixes to the Premonition stylesheet.
- * Removed the need Font Awesome css in default stylesheet, but
-   Font Awesome is still supported.
- * Other bug fixes. See HISTORY.md.
- 
- See UPGRADE.md for help on how to upgrade from 2.x to 4.0.
- 
+- Highly customizable (Create your own styles and templates easily)
+- Non-intrusive - Its just Markdown!
+- Easy to install
+- Comes with a default stylesheet (Sass/Css) and templates for beautiful messages boxes and citation.
+- Font Awesome 5 support
+
+## Version 4 Highlights
+
+- Jekyll [Post Excerpts](https://jekyllrb.com/docs/posts/#post-excerpts) support
+- New install command for the default stylesheet.
+- [Kramdown reference links](https://kramdown.gettalong.org/quickref.html#links-and-images) support
+- Jekyll 4 support (3.7 still supported)
+- Added support for block attributes (See documentation further down)
+- Added new citation block type.
+- Minor fixes to the Premonition stylesheet.
+- Removed the need Font Awesome css in default stylesheet, but
+  Font Awesome is still supported.
+- Other bug fixes. See HISTORY.md.
+
+See UPGRADE.md for help on how to upgrade from 2.x to 4.0.
+
 ## Requirements
 
- * Jekyll 3.7.x or higher (We recommend the new Jekyll 4)
- 
+- Jekyll 3.7.x or higher (We recommend the new Jekyll 4)
+
 ## Installation
 
 Add the following line to your `Gemfile` inside your Jekyll project folder:
 
 ```
 group :jekyll_plugins do
-  gem "premonition", "4.0.0.pre3"
+  gem "premonition", "4.0.0"
 end
 ```
 
@@ -53,7 +51,7 @@ Then add the the plugin to your `_config.yml`:
 
 ```yaml
 plugins:
-    - premonition
+  - premonition
 ```
 
 Now make sure to download the Premonition bundle:
@@ -89,54 +87,60 @@ defined by you in `_config.yml`.
 
 The default types are:
 
-* note
-* info
-* warning
-* error
-* citation
+- note
+- info
+- warning
+- error
+- citation
 
-The *Title* will normally be the block header. Leave it empty to disable
+The _Title_ will normally be the block header. Leave it empty to disable
 the header.
 
-*attributes* are in use by the Citation type, but can be skipped for the other default types. See section about custom types for more info.
+_attributes_ are in use by the Citation type, but can be skipped for the other default types. See section about custom types for more info.
 
 ### Examples
 
 Simple note with no header
-~~~markdown
+
+```markdown
 > note ""
 > No headers in here
-~~~
+```
 
 Note
-~~~markdown
+
+```markdown
 > note "I am a not"
 > The body of the note goes here. Premonition allows you to write any `Markdown` inside the block.
-~~~
+```
 
 Info
-~~~markdown
+
+```markdown
 > info "I am some info"
 > The body of the info box goes here. Premonition allows you to write any `Markdown` inside the block.
-~~~
+```
 
 Warning
-~~~markdown
+
+```markdown
 > warning "I am a warning"
 > The body of the warning box goes here. Premonition allows you to write any `Markdown` inside the block.
-~~~
+```
 
 Error
-~~~markdown
+
+```markdown
 > error "I am an error"
 > The body of the error box goes here. Premonition allows you to write any `Markdown` inside the block.
-~~~
+```
 
 Citation (Note the use of attributes here)
-~~~markdown
+
+```markdown
 > citations "Mark Twain" [ cite = "mt" ]
 > I will be a beautiful citation quote
-~~~
+```
 
 ## Configuration
 
@@ -150,12 +154,12 @@ Like Jekyll itself, Premonition uses the [Liquid Markup Language](https://github
 
 Six variables are available to the template engine:
 
-* *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`
-* *attrs* These are the attributes set in the block header. Like we did in the Citation example above.
+- _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`
+- _attrs_ These are the attributes set in the block header. Like we did in the Citation example above.
 
 Take a look at our default template inside `lib/premonition/resources.rb` to
 get an idea of how this is done.
@@ -167,7 +171,7 @@ You can override the default template like this in your `_config.yml`:
 ```yaml
 premonition:
   default:
-    template: 'Liquid template goes here'
+    template: "Liquid template goes here"
 ```
 
 #### Overriding the template for a default type
@@ -178,7 +182,7 @@ If you want to override the template for one of the default types (like note), d
 premonition:
   types:
     note:
-      template: 'Liquid template goes here'
+      template: "Liquid template goes here"
 ```
 
 ### Adding custom types
@@ -188,24 +192,24 @@ 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
+- 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
+```yaml
 premonition:
   types:
     custombox:
       meta:
-        my-meta: 'By myself'
+        my-meta: "By myself"
     advanced:
-      template: 'Liquid template goes here'
-      default_title: 'MY BLOCK'
+      template: "Liquid template goes here"
+      default_title: "MY BLOCK"
       meta:
-        my-meta: 'By myself'
-~~~
+        my-meta: "By myself"
+```
 
 ## More on styling
 
@@ -241,7 +245,7 @@ Then just add this to your `_config.yml`:
 premonition:
   types:
     error:
-      fa-icon: 'fa-bug'
+      fa-icon: "fa-bug"
 ```
 
 Simple as that :)

data/lib/premonition/attributes/parser.rb

@@ -46,7 +46,6 @@ module Jekyll
 
           until @buffer.eos?
             char = @buffer.getch
-
             case @stack.last.type
             when 0 # Outside block mode
               push_stacker(1) if char == '['

data/lib/premonition/commands/install_scss.rb

@@ -4,6 +4,9 @@ require 'net/http'
 
 module Jekyll
   module Premonition
+    # Public: Premonition stylesheet installer command
+    #
+    # Jekyll command that will install the Premonition stylesheet and add it to the needed resource files.
     class InstallScssCommand < Jekyll::Command
       class << self
         def init_with_program(prog)
@@ -19,45 +22,42 @@ module Jekyll
         end
 
         def process(_args, opts)
-          begin
-            puts '== Installing Premonition Stylesheet and resources =="'
-            puts '-- premonition.scss --'
-            dest = opts['dest'].nil? || opts['dest'].empty? ? './_sass/' : File.join(opts['dest'], '')
-            main = opts['main'].nil? || opts['main'].empty? ? './assets/css/styles.scss' : opts['main']
-            raise StandardError, "#{dest} folder does not exist. Create it manually, and run script again." unless Dir.exist?(dest)
-            raise StandardError, "#{main} does not exist" unless File.exist?(main)
+          puts '== Installing Premonition Stylesheet and resources =="'
+          puts '-- premonition.scss --'
+          dest = opts['dest'].nil? || opts['dest'].empty? ? './_sass/' : File.join(opts['dest'], '')
+          main = opts['main'].nil? || opts['main'].empty? ? './assets/css/styles.scss' : opts['main']
+          raise StandardError, "#{dest} folder does not exist. Create it manually, and run script again." unless Dir.exist?(dest)
+          raise StandardError, "#{main} does not exist" unless File.exist?(main)
 
-            uri = URI('https://raw.githubusercontent.com/lazee/premonition/master/stylesheet/premonition.scss')
-            pf = "#{dest}premonition.scss"
+          uri = URI('https://raw.githubusercontent.com/lazee/premonition/master/stylesheet/premonition.scss')
+          pf = "#{dest}premonition.scss"
 
-            if File.exist?(pf)
-              print "You already have #{pf} installed. Continue? [Y/n]"
-              override = gets.chomp
-              raise StandardError, "Aborted. No harm done." if override == 'n'
-            end
+          if File.exist?(pf)
+            print "You already have #{pf} installed. Continue? [Y/n]"
+            override = gets.chomp
+            raise StandardError, 'Aborted. No harm done.' if override == 'n'
+          end
 
-            File.write(pf, Net::HTTP.get(uri))
-            puts "Saved stylesheet in #{pf}"
+          File.write(pf, Net::HTTP.get(uri))
+          puts "Saved stylesheet in #{pf}"
 
-            if File.readlines(main).grep(/\@import \"premonition\"/).any?
-              puts "#{main} already imports the Premonition stylesheet."
+          if File.readlines(main).grep(/\@import \"premonition\"/).any?
+            puts "#{main} already imports the Premonition stylesheet."
+          else
+            puts 'You must add Premonition to your main SASS file.'
+            print "Add '@import \"premonition\";' to end of #{main} now? [Y/n] "
+            add = gets.chomp
+            if add == 'n'
+              puts 'Ok. But then you will need to add it manually for the styling of Premonition to work.'
             else
-              puts 'You must add Premonition to your main SASS file.'
-              print "Add '@import \"premonition\";' to end of #{main} now? [Y/n] "
-              add = gets.chomp
-              if add == 'n'
-                puts 'Ok. But then you will need to add it manually for the styling of Premonition to work.'
-              else
-                f = File.open(main, 'a')
-                f.write("\n@import \"premonition\";\n")
-                f.close
-                puts "Added Premonition stylesheet to #{main}."
-              end
+              f = File.open(main, 'a')
+              f.write("\n@import \"premonition\";\n")
+              f.close
+              puts "Added Premonition stylesheet to #{main}."
             end
-
-          rescue StandardError => msg
-            puts "ERROR: #{msg}"
           end
+        rescue StandardError => e
+          puts "ERROR: #{e}"
         end
       end
     end

data/lib/premonition/hook.rb

@@ -2,6 +2,16 @@
 
 module Jekyll
   module Premonition
+    # Registers Premonition hooks in Jekyll.
+    #
+    # Two hooks are added. One general hook for pages and another special
+    # hook for dealing with excerpts within posts.
+    #
+    # This ladder is really a hack as we scan all Markdown files and insert the
+    # excerpt ourselves in the document data. Unfortunately Jekyll prepares
+    # the excerpt way to early in the process, preventing us from hooking
+    # into it in a prober way. We only support excerpts if the excerpt_separator
+    # is explicitly set: https://jekyllrb.com/docs/posts/#post-excerpts
     class Hook < Generator
       safe true
       priority :high
@@ -10,14 +20,6 @@ module Jekyll
         super(p)
       end
 
-      def generate_excerpt?(doc)
-        !doc.data['excerpt_separator'].nil? && !doc.data['excerpt_separator'].empty?
-      end
-
-      def process?(resources, doc)
-        resources.config['extensions'].include?(File.extname(doc.relative_path)[1..-1])
-      end
-
       def generate(site)
         resources = Resources.new site.config
         processor = Processor.new resources
@@ -33,6 +35,16 @@ module Jekyll
           doc.content = processor.adder(doc.content) if process?(resources, doc)
         end
       end
+
+      private
+
+      def generate_excerpt?(doc)
+        !doc.data['excerpt_separator'].nil? && !doc.data['excerpt_separator'].empty?
+      end
+
+      def process?(resources, doc)
+        resources.config['extensions'].include?(File.extname(doc.relative_path)[1..-1])
+      end
     end
   end
 end

data/lib/premonition/processor.rb

@@ -2,11 +2,18 @@
 
 module Jekyll
   module Premonition
+    # Class that does all of the rendering magic within Premonition.
     class Processor
       def initialize(resources)
         @resources = resources
       end
 
+      # Called by the registered pre_render hooks.
+      #
+      # This function takes markdown content as input and converts
+      # all the block quotes, with a Premonition header, into html.
+      #
+      # content - Markdown content
       def adder(content)
         o = []
         references = load_references(content)
@@ -39,6 +46,9 @@ module Jekyll
 
       private
 
+      # Find all the Kramdown reference name links.
+      # https://kramdown.gettalong.org/quickref.html#links-and-images
+      # https://github.com/lazee/premonition/issues/10
       def load_references(content)
         refs = ["\n"]
         content.each_line do |l|
@@ -84,6 +94,19 @@ module Jekyll
         )
       end
 
+      def error_template
+        <<~TEMPLATE
+          <div class="premonition error">
+            <div class="fa {{meta.pn-icon}}"></div>
+            <div class="content">
+              <p class="header">PREMONITION ERROR: Invalid box type</p>
+              You have specified an invalid box type "{{type}}". You can customize your own box types in `_config.yml`.
+              See documentation for more help.
+            </div>
+          </div>
+        TEMPLATE
+      end
+
       def create_resource(block)
         c = {
           'template' => @resources.config['default']['template'],
@@ -94,8 +117,7 @@ module Jekyll
         unless @resources.config['types'].include? block['type']
           c['title'] = ''
           c['meta'] = { 'pn-icon' => 'pn-error' }
-          c['template'] = '<div class="premonition error"><div class="fa {{meta.pn-icon}}"></div>'\
-          '<div class="content"><p class="header">PREMONITION ERROR: Invalid box type</p>You have specified an invalid box type "{{type}}". You can customize your own box types in `_config.yml`. See documentation for help.</div></div>'
+          c['template'] = error_template
           return c
         end
 

data/lib/premonition/resources.rb

@@ -2,15 +2,18 @@
 
 module Jekyll
   module Premonition
+    # Class for loading the Premonition configuration and preparing it for use.
     class Resources
       attr_reader :config
       attr_reader :markdown
 
       def initialize(site_config)
         @config = load site_config
+        # Setup a new Markdown renderer.
         @markdown = Converters::Markdown.new site_config
       end
 
+      # Load the configuration of Premonition from Jekyll site configuration object.
       def load(site_config)
         cfg = default_config
         p = site_config['premonition'] || {}
@@ -24,11 +27,38 @@ module Jekyll
         cfg
       end
 
+      def default_template
+        <<~TEMPLATE
+          <div class="premonition {% if meta.style %}{{meta.style}} {% endif %}{{type}}">
+            <i class="{% if meta.fa-icon %}fas {{meta.fa-icon}}{% else %}premonition {{meta.pn-icon}}{% endif %}"></i>
+            <div class="content">
+              {% if header %}<p class="header">{{title}}</p>{% endif %}{{content}}
+            </div>
+          </div>
+        TEMPLATE
+      end
+
+      def citation_template
+        <<~TEMPLATE
+          <div class="premonition {% if meta.style %}{{meta.style}} {% endif %}{{type}}">
+            <i class="{% if meta.fa-icon %}fas {{meta.fa-icon}}{% else %}premonition {{meta.pn-icon}}{% endif %}"></i>
+            <blockquote class="content blockquote"{% if attrs.cite %} cite="{{attrs.cite}}"{% endif %}>
+              {{content}}
+              {% if header %}
+              <footer class="blockquote-footer">
+                <cite title="{{title}}">{{title}}</cite>
+              </footer>
+              {% endif %}
+            </blockquote>
+          </div>
+        TEMPLATE
+      end
+
+      # Setup the default configuration and types
       def default_config
         {
           'default' => {
-            'template' => '<div class="premonition {{type}}"><i class="{% if meta.fa-icon %}fas {{meta.fa-icon}}{% else %}premonition {{meta.pn-icon}}{% endif %}"></i>'\
-              '<div class="content">{% if header %}<p class="header">{{title}}</p>{% endif %}{{content}}</div></div>',
+            'template' => default_template,
             'meta' => { 'pn-icon' => 'pn-square', 'fa-icon' => nil },
             'title' => nil
           },
@@ -37,24 +67,22 @@ module Jekyll
             'info' => { 'meta' => { 'pn-icon' => 'pn-info' } },
             'warning' => { 'meta' => { 'pn-icon' => 'pn-warn' } },
             'error' => { 'meta' => { 'pn-icon' => 'pn-error' } },
-            'citation' => { 'meta' => { 'pn-icon' => 'pn-quote' }, 'template' =>
-              '<div class="premonition {{type}}"><i class="{% if meta.fa-icon %}fas {{meta.fa-icon}}{% else %}premonition {{meta.pn-icon}}{% endif %}"></i>'\
-              '<blockquote class="content blockquote"{% if attrs.cite %} cite="{{attrs.cite}}"{% endif %}>{{content}}{% if header %}'\
-              '<footer class="blockquote-footer">'\
-              '<cite title="{{title}}">{{title}}</cite></footer>{% endif %}</blockquote></div>' }
+            'citation' => { 'meta' => { 'pn-icon' => 'pn-quote' }, 'template' => citation_template }
           },
-          'extensions' => [
-            'md',
-            'markdown'
+          'extensions' => %w[
+            md
+            markdown
           ]
         }
       end
 
+      # Basic configuration validation
       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
 
+      # Load extra Premonition types configured/overriden in _config.yml
       def load_types(p, cfg)
         return if p['types'].nil?
 
@@ -65,6 +93,9 @@ module Jekyll
         end
       end
 
+      # Load extra extensions from config.
+      #
+      # We need this when looking for excerpts
       def load_extensions(p, cfg)
         return if p['extensions'].nil?
         return unless p['extensions'].is_a?(Array)
@@ -76,6 +107,7 @@ module Jekyll
         end
       end
 
+      # Validate a configured type and return as type hash
       def type_config(id, t)
         validate_type(id, t)
         {
@@ -85,6 +117,7 @@ module Jekyll
         }
       end
 
+      # Type validation
       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

data/lib/premonition/version.rb

@@ -2,6 +2,7 @@
 
 module Jekyll
   module Premonition
-    VERSION = '4.0.0.pre3'
+    # Make sure to change this manually before a release.
+    VERSION = '4.0.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: premonition
 version: !ruby/object:Gem::Version
-  version: 4.0.0.pre3
+  version: 4.0.0
 platform: ruby
 authors:
 - Jakob Vad Nielsen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-03-17 00:00:00.000000000 Z
+date: 2020-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -106,6 +106,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.10.0
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.5
 - !ruby/object:Gem::Dependency
   name: turn
   requirement: !ruby/object:Gem::Requirement
@@ -155,9 +169,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.1.2
 signing_key: