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 +7 -0
- data/LICENSE +21 -0
- data/README.md +128 -0
- data/lib/premonition/hook.rb +100 -0
- data/lib/premonition/resources.rb +68 -0
- data/lib/premonition/version.rb +5 -0
- data/lib/premonition.rb +10 -0
- metadata +114 -0
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
|
data/lib/premonition.rb
ADDED
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: []
|