premonition 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA1:
3
+ metadata.gz: 5c6cb2b3b2a0a1819165e8f659d5155283ea02b2
4
+ data.tar.gz: 93837406183c136e70a64481b8d7c6c1b8c5a3e9
5
+ SHA512:
6
+ metadata.gz: 2bd2fade3e41a00033f9e08f12884284aa2abb2d9e7162ace82f73b9b2c27d17f23a9a4866ca135bfced8391ee3406aadd150c2e9f8d9fd0660a8f686e7355cf
7
+ data.tar.gz: 2d8cc1b674470ed803e03d22ef67ed6f730a24a6cc3461f7d7d9a93c2a6420de9e48c9f52a23bc7011e4c5715da07feae2406258405ce3f46f1e5b8abadb228e
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2018 Amedia Utvikling AS
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,128 @@
1
+ # Premonition
2
+ 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.
3
+
4
+ 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
5
+ 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.
6
+
7
+ ## Features
8
+
9
+ * Highly customizable
10
+ * Non-intrusive - Content are rendered as block-quotes by any other parser
11
+ * Easy to install
12
+
13
+ ## Requirements
14
+
15
+ * Redcarpet
16
+ * Jekyll 3.7.x or higher
17
+
18
+ ## Installation
19
+
20
+ Add the following line to your `Gemfile` inside your Jekyll project. It should look something like this, depending on your Jekyll version:
21
+
22
+ ```
23
+ gem "redcarpet"
24
+ group :jekyll_plugins do
25
+ gem "premonition", "~> 1.0.0"
26
+ end
27
+ ```
28
+ As Premonition depends on Redcarpet, you must make sure this dependency is added as well.
29
+
30
+ Then add Premonition to `plugins` inside the Jekyll config file (`_config.yml`):
31
+
32
+ ```yaml
33
+ plugins:
34
+ - premonition
35
+ ```
36
+
37
+ ## Usage
38
+
39
+ Premonition blocks are really just standard Markdown block quote where the first line must follow a
40
+ special format to activate the transformation.
41
+
42
+ `> [type] "Title"`
43
+
44
+ The type can be any letter string. It is used to map a block to type configuration. This enables
45
+ you to customize the look of different types. Like *Info*, *Warning* and *Error* boxes for example.
46
+ By default the type will be added to the surrounding `<div>` block of the generated html code.
47
+
48
+ The *Title* is as you might have guessed the title that will be added to the block.
49
+
50
+ Example:
51
+
52
+ ~~~markdown
53
+ > warning "I am a warning"
54
+ > The body of the warning goes here. Premonition also allow you to write Markdown inside the block.
55
+ ~~~
56
+
57
+ This will be converted into something like this bu Premonition
58
+
59
+ ~~~html
60
+ <div class="premonition warning">
61
+ <span class="header">Info</span>
62
+ <p>The body of the warning goes here. Premonition also allow you to write Markdown inside the block.</p>
63
+ ~~~
64
+
65
+ The title can be omitted by providing an empty string . Like this:
66
+
67
+ ~~~markdown
68
+ > warning ""
69
+ > No headers in here
70
+ ~~~
71
+
72
+ Now you can add some CSS styling.
73
+
74
+ ## Configuration
75
+
76
+ If you don't like the markup that Premonition produces, then you can change it in two ways.
77
+ Either by replacing the default template, or by configuring templates for each type.
78
+
79
+ All this are done inside your `_config.yml`
80
+
81
+ ### Replacing the default template
82
+
83
+ ```yaml
84
+ premonition:
85
+ default:
86
+ template: '<div></i>%{header}%{content}</div>'
87
+ header_template: '<span class="header">%{title}</span>'
88
+ ```
89
+
90
+ Please be aware of the placeholders inside the template. These placeholders will be replaced with
91
+ the actual content of your block.
92
+
93
+ Available placeholders are
94
+
95
+ * *header* This is where the content from the header_template will be added if the title is not empty.
96
+ * *content* This is where the rendered content of your block quote are added.
97
+ * *title* This is where you block title will be added.
98
+ * *type* The type name of the block.
99
+
100
+ ### Adding custom types
101
+
102
+ Sometimes you might want to have different markup for different block types. This can easily be done
103
+ by adding types to your Premonition configuration inside `_config.yml`
104
+
105
+ ~~~yaml
106
+ premonition:
107
+ default:
108
+ template: '<div></i>%{header}%{content}</div>'
109
+ header_template: '<span class="header %{type}">%{title}</span>'
110
+ types:
111
+ - id: tip
112
+ template: '<div class="alert alert-success" role=""><i class="fa fa-check-square-o"></i>%{header}%{content}</div>'
113
+ - id: note
114
+ template: '<div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i>%{header}%{content}</div>'
115
+ ~~~
116
+
117
+ NOTE: You cannot add a custom header_template to types at the moment. This will be fixed soon.
118
+
119
+ #### Default titles
120
+
121
+ You can add a default title to a type.
122
+
123
+ ~~~yaml
124
+ - id: tip
125
+ template: '<div class="alert alert-success" role=""><i class="fa fa-check-square-o"></i>%{header}%{content}</div>'
126
+ default_title: 'TIP!'
127
+ ~~~
128
+
@@ -0,0 +1,100 @@
1
+ module Jekyll
2
+ module Premonition
3
+ class Hook < Generator
4
+ safe true
5
+ priority :low
6
+ attr_reader :resources
7
+
8
+ def initialize(p)
9
+ super(p)
10
+ unless defined?(Redcarpet)
11
+ Jekyll::External.require_with_graceful_fail(
12
+ "redcarpet (in #{__FILE__})"
13
+ )
14
+ end
15
+ end
16
+
17
+ def generate(site)
18
+ @resources = Resources.new site
19
+ Hooks.register :documents, :pre_render do |doc|
20
+ adder(doc)
21
+ end
22
+ Hooks.register :pages, :pre_render do |page|
23
+ adder(page)
24
+ end
25
+ Hooks.register :posts, :pre_render do |page|
26
+ adder(page)
27
+ end
28
+ end
29
+
30
+ def adder(doc)
31
+ o = []
32
+ b = nil
33
+ doc.content.each_line do |l|
34
+ if blockquote?(l) && empty_block?(b)
35
+ if (m = l.match(/^\>\s+([a-z]+)\s+\"(.*)\"$/i))
36
+ y, t = m.captures
37
+ b = { title: t.strip, type: y.strip.downcase, content: [] }
38
+ else
39
+ o << l
40
+ end
41
+ elsif blockquote?(l) && !empty_block?(b)
42
+ b[:content] << l.match(/^\>(.*)$/i).captures[0].strip
43
+ else
44
+ if !blockquote?(l) && !empty_block?(b)
45
+ o << render_block(b)
46
+ b = nil
47
+ end
48
+ o << l
49
+ end
50
+ end
51
+ o << render_block(b) unless empty_block?(b)
52
+ doc.content = o.join
53
+ end
54
+
55
+ def blockquote?(l)
56
+ l.strip.start_with?('>')
57
+ end
58
+
59
+ def empty_block?(b)
60
+ b.nil?
61
+ end
62
+
63
+ def render_block(b)
64
+ t = create_templ(b)
65
+ c = "#{@resources.renderer.render(b[:content].join("\n"))}\n\n"
66
+ v = {
67
+ title: t[:title],
68
+ content: c,
69
+ type: b[:type]
70
+ }
71
+ v[:header] = header(t[:title]) % v
72
+ clean_markup(t[:template] % v)
73
+ end
74
+
75
+ def clean_markup(r)
76
+ br = '<br>' * 2
77
+ r = r.gsub('<p>', '').gsub('</p>', br).strip
78
+ r = r.gsub(br, '') if r.scan(/<br><br>/m).size == 1
79
+ r
80
+ end
81
+
82
+ def header(t)
83
+ t.empty? ? '' : @resources.config[:default][:header_template]
84
+ end
85
+
86
+ def create_templ(b)
87
+ c = {
88
+ template: @resources.config[:default][:template],
89
+ title: @resources.config[:default][:title]
90
+ }
91
+ @resources.config[:types].each do |t|
92
+ next unless t[:id] == b[:type]
93
+ c[:title] = b[:title].empty? ? t[:default_title] : b[:title]
94
+ c[:template] = t[:template]
95
+ end
96
+ c
97
+ end
98
+ end
99
+ end
100
+ end
@@ -0,0 +1,68 @@
1
+ module Jekyll
2
+ module Premonition
3
+ class Resources
4
+ attr_reader :config
5
+ attr_reader :renderer
6
+
7
+ def initialize(site)
8
+ @config = load_config site
9
+ @renderer = create_renderer site
10
+ end
11
+
12
+ def create_renderer(site)
13
+ hsh = {}
14
+ ext_lookup(site).each { |a| hsh[a] = true }
15
+ Redcarpet::Markdown.new(Redcarpet::Render::HTML, hsh)
16
+ end
17
+
18
+ def ext_lookup(site)
19
+ ((site.config['redcarpet'] || {})['extensions'] || [])
20
+ end
21
+
22
+ def load_config(site)
23
+ cfg = create_default_config
24
+ prem = site.config['premonition'] || {}
25
+ df = prem['default'] || {}
26
+ cfg[:default][:template] = df['template'].strip unless df['template'].nil?
27
+ cfg[:default][:header_template] = df['header_template'].strip unless df['header_template'].nil?
28
+ cfg[:default][:title] = df['title'].strip unless df['title'].nil?
29
+ unless prem['types'].nil?
30
+ fail('types configuration must be an array') unless prem['types'].is_a?(Array)
31
+ prem['types'].each { |t| cfg[:types] << load_config_type(t) }
32
+ end
33
+ cfg
34
+ end
35
+
36
+ def load_config_type(t)
37
+ validate_config_type(t)
38
+ {
39
+ id: t['id'],
40
+ template: t['template'].strip,
41
+ default_title: (t['default_title'].nil? ? '' : t['default_title'].strip)
42
+ }
43
+ end
44
+
45
+ def validate_config_type(t)
46
+ fail('id missing from type') if t['id'].nil?
47
+ fail("id can only be lowercase letters: #{t['id']}") unless t['id'][/[a-z]+/] == t['id']
48
+ fail('template missing from type') if t['template'].nil?
49
+ end
50
+
51
+ def create_default_config
52
+ {
53
+ default: {
54
+ template: '<div class="premonition %{type}">%{header}%{content}</div>',
55
+ header_template: ' <span class="header">%{title}</span>',
56
+ title: 'Info'
57
+ },
58
+ types: []
59
+ }
60
+ end
61
+
62
+ def fail(msg)
63
+ Jekyll.logger.error 'Fatal (Premonition):', msg
64
+ raise LoadError, msg
65
+ end
66
+ end
67
+ end
68
+ end
@@ -0,0 +1,5 @@
1
+ module Jekyll
2
+ module Premonition
3
+ VERSION = '1.0.2'.freeze
4
+ end
5
+ end
@@ -0,0 +1,10 @@
1
+ require 'redcarpet'
2
+ require 'jekyll'
3
+ require 'premonition/version'
4
+ require 'premonition/resources'
5
+ require 'premonition/hook'
6
+
7
+ module Jekyll
8
+ module Premonition
9
+ end
10
+ end
metadata ADDED
@@ -0,0 +1,114 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: premonition
3
+ version: !ruby/object:Gem::Version
4
+ version: 1.0.2
5
+ platform: ruby
6
+ authors:
7
+ - Jakob Vad Nielsen
8
+ autorequire:
9
+ bindir: bin
10
+ cert_chain: []
11
+ date: 2018-02-06 00:00:00.000000000 Z
12
+ dependencies:
13
+ - !ruby/object:Gem::Dependency
14
+ name: bundler
15
+ requirement: !ruby/object:Gem::Requirement
16
+ requirements:
17
+ - - "~>"
18
+ - !ruby/object:Gem::Version
19
+ version: '1.5'
20
+ type: :development
21
+ prerelease: false
22
+ version_requirements: !ruby/object:Gem::Requirement
23
+ requirements:
24
+ - - "~>"
25
+ - !ruby/object:Gem::Version
26
+ version: '1.5'
27
+ - !ruby/object:Gem::Dependency
28
+ name: jekyll
29
+ requirement: !ruby/object:Gem::Requirement
30
+ requirements:
31
+ - - ">="
32
+ - !ruby/object:Gem::Version
33
+ version: '2.0'
34
+ - - "<"
35
+ - !ruby/object:Gem::Version
36
+ version: '3.0'
37
+ type: :development
38
+ prerelease: false
39
+ version_requirements: !ruby/object:Gem::Requirement
40
+ requirements:
41
+ - - ">="
42
+ - !ruby/object:Gem::Version
43
+ version: '2.0'
44
+ - - "<"
45
+ - !ruby/object:Gem::Version
46
+ version: '3.0'
47
+ - !ruby/object:Gem::Dependency
48
+ name: rake
49
+ requirement: !ruby/object:Gem::Requirement
50
+ requirements:
51
+ - - ">="
52
+ - !ruby/object:Gem::Version
53
+ version: '0'
54
+ type: :development
55
+ prerelease: false
56
+ version_requirements: !ruby/object:Gem::Requirement
57
+ requirements:
58
+ - - ">="
59
+ - !ruby/object:Gem::Version
60
+ version: '0'
61
+ - !ruby/object:Gem::Dependency
62
+ name: rspec
63
+ requirement: !ruby/object:Gem::Requirement
64
+ requirements:
65
+ - - "~>"
66
+ - !ruby/object:Gem::Version
67
+ version: '3.0'
68
+ type: :development
69
+ prerelease: false
70
+ version_requirements: !ruby/object:Gem::Requirement
71
+ requirements:
72
+ - - "~>"
73
+ - !ruby/object:Gem::Version
74
+ version: '3.0'
75
+ description:
76
+ email:
77
+ - jakob.nielsen@amedia.no
78
+ executables: []
79
+ extensions: []
80
+ extra_rdoc_files:
81
+ - README.md
82
+ files:
83
+ - LICENSE
84
+ - README.md
85
+ - lib/premonition.rb
86
+ - lib/premonition/hook.rb
87
+ - lib/premonition/resources.rb
88
+ - lib/premonition/version.rb
89
+ homepage: http://github.com/amedia/premonition
90
+ licenses:
91
+ - MIT
92
+ metadata: {}
93
+ post_install_message:
94
+ rdoc_options: []
95
+ require_paths:
96
+ - lib
97
+ - lib
98
+ required_ruby_version: !ruby/object:Gem::Requirement
99
+ requirements:
100
+ - - ">="
101
+ - !ruby/object:Gem::Version
102
+ version: '0'
103
+ required_rubygems_version: !ruby/object:Gem::Requirement
104
+ requirements:
105
+ - - ">="
106
+ - !ruby/object:Gem::Version
107
+ version: '0'
108
+ requirements: []
109
+ rubyforge_project:
110
+ rubygems_version: 2.5.1
111
+ signing_key:
112
+ specification_version: 4
113
+ summary: Jekyll generator that will convert special block quotes into message boxes.
114
+ test_files: []