premonition 4.0.0.pre1 → 4.0.0.pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5790ecdffbb5137fc1deacc1e29077cc574a2c05c60988f2a41b8eca8e160765
-  data.tar.gz: e9c80f5a325c183790978ad6d81d48713946935b0ad14396cb28f55ffd8dcd99
+  metadata.gz: 702f70cebe5c5bc886febd4ef952d96ae29fb3648005c0c2b479dcb6558ad05d
+  data.tar.gz: f68b77e7d9a65c7d92bf859375d6705df066c902548425f0d81020afba05991b
 SHA512:
-  metadata.gz: c6ab0056c0d15c2e2a0a05af51a9291871f62694a733ed1d10dce35d801ca9ce395f3a9eaafd0261284b2d371d884750671ab8b8b4eebe47f64203f6531ef576
-  data.tar.gz: 00b78b8282be668dde7abd6328493a6e267ed8321f209a03675e02586f26df95a56df7752b777c0e2c0fc341f025958a01ea4f7b35813dddabc299921ea94aa8
+  metadata.gz: 738fa98b26ce9d6f5a8ed7bfd7ae646d264d85a252139f4d7ad44dcff77d25bc98389ea2412d36a0f194e179745bfd085d54576e8282badbf577a446f885c862
+  data.tar.gz: 8f86832b377ba7be043d80cdde9ff8134dbb6d4f42c2caf27adbed85dfe3f5902ba45b3316981918fe23ba3f6d0980fd788eebe0572c11302710dbb3ed7f85df

data/README.md

@@ -1,10 +1,10 @@
 # Premonition
 
-[Demo site](https://lazee.github.io/premonition-demo/) | [Source code](https://github.com/lazee/premonition-demo)
+[Demo site](https://lazee.github.io/premonition-demo/) ([Source code](https://github.com/lazee/premonition-demo))
 
-Premonition is a [Jekyll](https://jekyllrb.com/) extension 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 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.
+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"/>
@@ -15,28 +15,31 @@ By simply adding a special header to the first line of a [block quote](https://g
  * Highly customizable (Create your own styles and templates easily)
  * Non-intrusive - Its just Markdown!
  * Easy to install
- * Comes with a stylesheet (Sass/Css) and templates for rendering the most common boxes.
-
- ## Version 4 highlights
-
- * Added Jekyll Excerpts support
- * Kramdown reference links now supported
- * Jekyll 4 support
- * Added support for block attributes. This is in use in the new citation 
-   block type: 
-   
-   `> citation "-- jakob" [ cite = "jvn" ]`
- * Other minor bug fixes
-
-
+ * 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
- * FontAwesome 5.x
-
+ * Jekyll 3.7.x or higher (We recommend the new Jekyll 4)
+ 
 ## Installation
 
-Add the following line to your `Gemfile`:
+Add the following line to your `Gemfile` inside your Jekyll project folder:
 
 ```
 group :jekyll_plugins do
@@ -44,80 +47,115 @@ group :jekyll_plugins do
 end
 ```
 
-Then add Premonition to `plugins` in `_config.yml`:
+Then add the the plugin to your `_config.yml`:
 
 ```yaml
 plugins:
     - premonition
 ```
 
-Finally run `bundle install`
+Now make sure to download the Premonition bundle:
+
+```
+bundle install
+```
+
+### Installing the default stylesheet
+
+Finally, if you want to use the default Premonition styling (You really should!), then you have to install the SASS stylesheet.
+
+From your Jekyll project folder, run:
+
+```
+bundle exec jekyll premonition-install
+```
+
+This will add the `premonition.scss` file to your `_sass` folder and ask if you want to import this file into your `assets/main.scss` file.
+Both of these settings (destination folder and main file) can be configured. Run `bundle exec jekyll premonition-install --help` to see how.
+
+If you prefer CSS, then download the stylesheet/premonition.css file directly from this repo.
 
 ## Usage
 
-Premonition blocks are really just a standard Markdown blockquote where the first line must be on a
-special format to activate the transformation.
+A Premonition block is really just a standard Markdown blockquote where the first line of the block must follow a certain syntax.
 
-`> [type] "Title"`
+`> [type] "Title" [ attributes... ]`
 
-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.
+The type must be set to one of the default Premonition block types, or a type
+defined by you in `_config.yml`.
 
-Default types are:
+The default types are:
 
 * note
 * info
 * warning
 * error
+* citation
+
+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.
 
-The *Title* is the box header. It can be left empty to disable the box header:
+### Examples
 
+Simple note with no header
 ~~~markdown
-> warning ""
+> note ""
 > No headers in here
 ~~~
 
-Example:
+Note
+~~~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
+> 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
 > warning "I am a warning"
-> The body of the warning goes here. Premonition allows you to write any `Markdown` inside the block.
+> The body of the warning box goes here. Premonition allows you to write any `Markdown` inside the block.
 ~~~
 
-Premonition will then convert this into something like:
-
-~~~html
-<div class="premonition info"><i class="fas fa-check-square"></i><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>
+Error
+~~~markdown
+> error "I am an error"
+> The body of the error box goes here. Premonition allows you to write any `Markdown` inside the block.
 ~~~
 
-You can change the markup into anything you like by adding your own template.
+Citation (Note the use of attributes here)
+~~~markdown
+> citations "Mark Twain" [ cite = "mt" ]
+> I will be a beautiful citation quote
+~~~
 
 ## Configuration
 
-The templates can be customized in two eays. Either by replacing the default template, or by adding a custom template to a type.
+The templates can be customized in two eays. Either by replacing one of the default templates, or by adding a new type from scratch.
 
-All this is done inside your `_config.yml`.
+All this is done inside your `_config.yml`. Look at the [source code for our demo site](https://github.com/lazee/premonition-demo), for live examples on how configuration can be done.
 
 ### Templates
 
-Like Jekyll itself, Premonition uses the [Liquid Markup Language](https://github.com/Shopify/liquid) for its templates.
+Like Jekyll itself, Premonition uses the [Liquid Markup Language](https://github.com/Shopify/liquid) for templating.
 
-Five variables are available to the template engine:
+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.
 
-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>
-~~~
+Take a look at our default template inside `lib/premonition/resources.rb` to
+get an idea of how this is done.
 
 #### Overriding the default template
 
@@ -158,32 +196,49 @@ premonition:
   types:
     custombox:
       meta:
-        fa-icon: fa-exclamation-circle
+        my-meta: 'By myself'
     advanced:
       template: 'Liquid template goes here'
       default_title: 'MY BLOCK'
       meta:
-        fa-icon: fa-exclamation-triangle
+        my-meta: 'By myself'
 ~~~
 
-## Styling
+## More on styling
+
+As described in the Installation section above, it is pretty easy to install the default stylesheet into your project.
+But we recognize that this design probably isn't a perfect fit for everybody. Luckily you can modify it :)
 
-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.
+Our recommendation is to install the default stylesheet and override it in another SASS file. This way it will be
+easy to upgrade the default Stylesheet later without loosing your changes.
 
-Download the stylesheet from here : https://github.com/lazee/premonition/tree/master/stylesheet
+The [Jekyll Documentation](https://jekyllrb.com/docs/assets/) describes the process of adding your own SASS files in great details.
 
-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 v5.x of Font Awesome together with our CSS.
+## Font Awesome support
 
-The easiest way to get startet with Font Awesome is to add this to your html header file:
+Premonition 4.x no longer depends on Font Awesome for its default stylesheet.
+But it is still supported.
 
-~~~html
+To add Font Awesome support you should add something like this
+to your head template file:
+
+```
 <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.12.1/css/all.css">
-~~~~
+```
 
-If you need backward compability with v4:
+Feel free to install it any other way you prefer, as long as you follow their
+[license](https://fontawesome.com/license/free).
 
-~~~html
-<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.12.1/css/v4-shims.css">
-~~~
+Now you can swith to Font Awesome for any of the default types by adding
+`fa-icon` to a types meta object. Let's say you want to replace the default error box icon with the beautiful `fa-bug` icon from Font Awesome.
+
+Then just add this to your `_config.yml`:
+
+```yml
+premonition:
+  types:
+    error:
+      fa-icon: 'fa-bug'
+```
+
+Simple as that :)

data/lib/premonition.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'jekyll'
+require_relative 'premonition/commands/install_scss.rb'
 require_relative 'premonition/attributes/error'
 require_relative 'premonition/attributes/stacker'
 require_relative 'premonition/attributes/parser'

data/lib/premonition/commands/install_scss.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module Jekyll
+  module Premonition
+    class InstallScssCommand < Jekyll::Command
+      class << self
+        def init_with_program(prog)
+          prog.command(:"premonition-install") do |c|
+            c.syntax 'premonition-install [options]'
+            c.description 'Install Premonition SASS stylesheet into your Jekyll site.'
+            c.option 'dest', '-d DEST', 'Where premonition.scss should be stored. (defaults to _sass/)'
+            c.option 'main', '-m DEST', 'The path to your main SASS file (defaults to assets/main.scss)'
+            c.action do |args, opts|
+              Jekyll::Premonition::InstallScssCommand.process(args, opts)
+            end
+          end
+        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/main.scss' : opts['main']
+            raise StandardError, "#{dest} folder does not exist" 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"
+
+            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}"
+
+            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
+                f = File.open(main, 'a')
+                f.write("\n@import \"premonition\";\n")
+                f.close
+                puts "Added Premonition stylesheet to #{main}."
+              end
+            end
+
+          rescue StandardError => msg
+            puts "ERROR: #{msg}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/premonition/processor.rb

@@ -93,8 +93,8 @@ module Jekyll
 
         unless @resources.config['types'].include? block['type']
           c['title'] = ''
-          c['meta'] = { 'fa-icon' => 'fa-bug' }
-          c['template'] = '<div class="premonition error"><div class="fa {{meta.fa-icon}}"></div>'\
+          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>'
           return c
         end

data/lib/premonition/resources.rb

@@ -27,18 +27,18 @@ module Jekyll
       def default_config
         {
           'default' => {
-            'template' => '<div class="premonition {{type}}"><i class="fas {{meta.fa-icon}}"></i>'\
+            '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>',
-            'meta' => { 'fa-icon' => 'fa-check-square' },
+            'meta' => { 'pn-icon' => 'pn-square', 'fa-icon' => nil },
             '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' } },
-            'citation' => { 'meta' => { 'fa-icon' => 'fa-quote-left' }, 'template' =>
-              '<div class="premonition {{type}}"><i class="fas {{meta.fa-icon}}"></i>'\
+            'note' => { 'meta' => { 'pn-icon' => 'pn-note' } },
+            '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>' }

data/lib/premonition/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   module Premonition
-    VERSION = '4.0.0.pre1'
+    VERSION = '4.0.0.pre2'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: premonition
 version: !ruby/object:Gem::Version
-  version: 4.0.0.pre1
+  version: 4.0.0.pre2
 platform: ruby
 authors:
 - Jakob Vad Nielsen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-03-16 00:00:00.000000000 Z
+date: 2020-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -134,6 +134,7 @@ files:
 - lib/premonition/attributes/error.rb
 - lib/premonition/attributes/parser.rb
 - lib/premonition/attributes/stacker.rb
+- lib/premonition/commands/install_scss.rb
 - lib/premonition/hook.rb
 - lib/premonition/processor.rb
 - lib/premonition/resources.rb
@@ -158,7 +159,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 1.3.1
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Jekyll generator that will convert special block quotes into message boxes.