Skip to content

Commit 84c25a3

Browse files
fzanklfzankl
authored
Merge pull request #8 from develop
New configuration options to allow custom alert types.
2 parents 5f90078 + 9b3b13b commit 84c25a3

3 files changed

Lines changed: 114 additions & 97 deletions

File tree

‎README.md‎

Lines changed: 62 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# GitBook Plugin: Flexible Alerts
22

3-
This GitBook Plugin converts blockquotes into beautiful alerts. Look and feel can be configured so the alerts fit your needs (some examples are shown below).
3+
This GitBook Plugin converts blockquotes into beautiful alerts. Look and feel can be configured on a global as well as on a alert specific level so output does fit your needs (some examples are shown below). In addition, you can provide own alert types.
44

55
![Sample alerts created with plugin 'flexible-alerts'](https://user-images.githubusercontent.com/44210522/50688702-ea774f00-1026-11e9-9281-ca615cb466f5.jpg)
66

@@ -9,7 +9,7 @@ This GitBook Plugin converts blockquotes into beautiful alerts. Look and feel ca
99
### Step #1 - Update book.json file
1010

1111
1. In you gitbook's book.json file, add `flexible-alerts` to plugins list.
12-
2. In pluginsConfig, set base value which is base path to your github or gitlab or other code repo. Trailing slash is NOT required.
12+
2. In pluginsConfig, configure the plugin so it does fit your needs. A custom setup is not mandatory.
1313
3. By default style 'callout' and headings 'Note', 'Tip', 'Warning', 'Attention' will be used. You can change it using plugin configuration via `book.json` or for a single alert in your markdown files.
1414

1515
**Sample `book.json` file for gitbook version 2.0.0+**
@@ -46,10 +46,18 @@ This GitBook Plugin converts blockquotes into beautiful alerts. Look and feel ca
4646
],
4747
"pluginsConfig": {
4848
"flexible-alerts": {
49-
"note": "Hinweis",
50-
"tip": "Tipp",
51-
"warning": "Warnung",
52-
"danger": "Achtung"
49+
"note": {
50+
"label": "Hinweis"
51+
},
52+
"tip": {
53+
"label": "Tipp"
54+
},
55+
"warning": {
56+
"label": "Warnung"
57+
},
58+
"danger": {
59+
"label": "Achtung"
60+
}
5361
}
5462
}
5563
}
@@ -65,20 +73,28 @@ This GitBook Plugin converts blockquotes into beautiful alerts. Look and feel ca
6573
"pluginsConfig": {
6674
"flexible-alerts": {
6775
"note": {
76+
"label": {
6877
"de": "Hinweis",
6978
"en": "Note"
79+
}
7080
},
7181
"tip": {
82+
"label": {
7283
"de": "Tipp",
7384
"en": "Tip"
85+
}
7486
},
7587
"warning": {
88+
"label": {
7689
"de": "Warnung",
7790
"en": "Warning"
91+
}
7892
},
7993
"danger": {
94+
"label": {
8095
"de": "Achtung",
8196
"en": "Attention"
97+
}
8298
}
8399
}
84100
}
@@ -94,12 +110,7 @@ Note: Above snippets can be used as complete `book.json` file, if one of these m
94110

95111
## Usage
96112

97-
To use the plugin just modify an existing blockquote and prepend a line matching pattern `[!type]`, using one of following types. Please see code snippets for working alerts.
98-
99-
* NOTE
100-
* TIP
101-
* WARNING
102-
* DANGER
113+
To use the plugin just modify an existing blockquote and prepend a line matching pattern `[!type]`. By default types `NOTE`, `TIP`, `WARNING` and `DANGER` are supported. You can extend the available types by providing a valid configuration (see below for an example).
103114

104115
```markdown
105116
> [!NOTE]
@@ -111,28 +122,59 @@ To use the plugin just modify an existing blockquote and prepend a line matching
111122
> An alert of type 'note' using alert specific style 'flat' which overrides global style 'callout'.
112123
```
113124

114-
As you can see in the second snippet output can be configured on alert level also. Supported options are listed in following table:
125+
As you can see in the second snippet, output can be configured on alert level also. Supported options are listed in following table:
115126

116127
| Key | Allowed value |
117128
| --------------- | ---- |
118-
| style | callout, flat |
119-
| label | any text |
120-
| labelVisibility | visible (default), hidden |
121-
| iconVisibility | visible (default), hidden |
129+
| style | One of follwowing values: callout, flat |
130+
| label | Any text |
131+
| icon | A valid Font Awesome icon, e.g. 'fa-info-circle' |
132+
| className | A name of a CSS class which specifies the look and feel |
133+
| labelVisibility | One of follwowing values: visible (default), hidden |
134+
| iconVisibility | One of follwowing values: visible (default), hidden |
122135

123136
Multiple options can be used for single alerts as shown below:
124137

125138
```markdown
126-
> [!NOTE|style:flat|label:My own heading|iconVisibility:false]
127-
> An alert of type 'note' using alert specific style 'flat' which overrides global style 'callout'.
139+
> [!TIP|style:flat|label:My own heading|iconVisibility:false]
140+
> An alert of type 'tip' using alert specific style 'flat' which overrides global style 'callout'.
128141
> In addition, this alert uses an own heading and hides specific icon.
129142
```
130143

131144
![Custom alert](https://user-images.githubusercontent.com/44210522/50689970-04676080-102c-11e9-9cbc-8af129cb988c.png)
132145

146+
As mentioned above you can provide your own alert types. Therefore, you have to provide the type configuration via `book.json`. Following example shows an additional type `COMMENT`.
147+
148+
```json
149+
{
150+
"plugins": [
151+
"flexible-alerts"
152+
],
153+
"pluginsConfig": {
154+
"flexible-alerts": {
155+
"style": "callout",
156+
"comment": {
157+
"label": "Comment",
158+
"icon": "fa-comments",
159+
"className": "info"
160+
}
161+
}
162+
}
163+
}
164+
```
165+
166+
In Markdown just use the alert according to the types provided by default.
167+
168+
```markdown
169+
> [!COMMENT]
170+
> An alert of type 'comment' using style 'callout' with default settings.
171+
```
172+
173+
![Custom alert type 'comment'](https://user-images.githubusercontent.com/44210522/50722960-6f21a600-10d7-11e9-87e7-d40d87045afe.png)
174+
133175
## Troubleshooting
134176

135177
If alerts do no look as expected, check if your `book.json` as well as alerts in Markdown are valid according to this documentation.
136178

137179
## Changelog
138-
01/04/2019 - Initial release
180+
01/05/2019 - Initial Release

‎book/plugin.js‎

Lines changed: 18 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,3 @@
1-
var styleConfiguration = {
2-
note: {
3-
callout: {
4-
icon: '<i class="fa fa-info-circle"></i>',
5-
className: 'alert callout info'
6-
},
7-
flat: {
8-
icon: '<i class="fa fa-info-circle"></i>',
9-
className: 'alert flat info'
10-
}
11-
},
12-
tip: {
13-
callout: {
14-
icon: '<i class="fa fa-lightbulb-o"></i>',
15-
className: 'alert callout tip'
16-
},
17-
flat: {
18-
icon: '<i class="fa fa-lightbulb-o"></i>',
19-
className: 'alert flat tip'
20-
}
21-
},
22-
warning: {
23-
callout: {
24-
icon: '<i class="fa fa-exclamation-triangle"></i>',
25-
className: 'alert callout warning'
26-
},
27-
flat: {
28-
icon: '<i class="fa fa-exclamation-triangle"></i>',
29-
className: 'alert flat warning'
30-
}
31-
},
32-
danger: {
33-
callout: {
34-
icon: '<i class="fa fa-ban"></i>',
35-
className: 'alert callout danger'
36-
},
37-
flat: {
38-
icon: '<i class="fa fa-ban"></i>',
39-
className: 'alert flat danger'
40-
}
41-
}
42-
};
43-
441
function findAlertSetting(input, key, fallback, callback) {
452
var match = (input || '').match(new RegExp(`${key}:(([\\w\\s]*))`));
463

@@ -58,14 +15,19 @@ require(["gitbook", "jQuery"], function(gitbook, $) {
5815
$('blockquote').each(function() {
5916
var origin = $(this).html();
6017
var content = origin.replace(/\[!(\w*)((?:\|[\w*:[\w\s]*)*?)\]([\s\S]*)/g, (match, key, settings, value) => {
61-
// Style configuration
62-
var styleKey = findAlertSetting(settings, 'style', gitBookConfiguration['style']);
63-
var style = styleConfiguration[key.toLowerCase()][styleKey];
18+
var config = gitBookConfiguration[key.toLowerCase()]
19+
20+
if (!config) {
21+
return match;
22+
}
6423

65-
// Heading configuration
24+
// Style configuration
25+
var style = findAlertSetting(settings, 'style', gitBookConfiguration['style']);
6626
var isIconVisible = findAlertSetting(settings, 'iconVisibility', 'visible', (value) => value !== 'hidden');
6727
var isLabelVisible = findAlertSetting(settings, 'labelVisibility', 'visible', (value) => value !== 'hidden');
68-
var label = findAlertSetting(settings, 'label', gitBookConfiguration[key.toLowerCase()]);
28+
var label = findAlertSetting(settings, 'label', config['label']);
29+
var icon = findAlertSetting(settings, 'icon', config['icon']);
30+
var className = findAlertSetting(settings, 'className', config['className']);
6931

7032
// Label can be language specific and could be specified via user configuration
7133
if (typeof label === 'object') {
@@ -79,9 +41,15 @@ require(["gitbook", "jQuery"], function(gitbook, $) {
7941
}
8042
}
8143

44+
var iconTag = `<i class="fa ${icon}"></i>`;
45+
8246
return (
83-
`<div class="${style.className}">
84-
<p class="title">${isIconVisible ? style.icon : ''}${isLabelVisible ? label : ''}</p><p>${value}
47+
`<div class="alert ${style} ${className}">
48+
<p class="title">
49+
${isIconVisible ? iconTag : ''}
50+
${isLabelVisible ? label : ''}
51+
</p>
52+
<p>${value}
8553
</div>`
8654
);
8755
});

‎package.json‎

Lines changed: 34 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,15 @@
11
{
22
"name": "gitbook-plugin-flexible-alerts",
33
"version": "1.0.0",
4-
"description": "GitBook plugin to convert blockquotes into beautiful and configurable alerts.",
4+
"description": "GitBook plugin to convert blockquotes into beautiful and configurable alerts using preconfigured or own styles and alert types.",
55
"keywords": [
66
"gitbook",
77
"plugin",
8-
"alerts",
9-
"blockquotes"
8+
"alert",
9+
"blockquotes",
10+
"quote",
11+
"hint",
12+
"callout"
1013
],
1114
"author": "Fabian Zankl",
1215
"license": "MIT",
@@ -33,36 +36,40 @@
3336
"default": "callout"
3437
},
3538
"note": {
36-
"type": [
37-
"string",
38-
"object"
39-
],
40-
"title": "Label for alerts of type 'note'",
41-
"default": "Note"
39+
"type": "object",
40+
"title": "Configuration for alerts of type 'note'",
41+
"default": {
42+
"label": "Note",
43+
"icon": "fa-info-circle",
44+
"className": "info"
45+
}
4246
},
4347
"tip": {
44-
"type": [
45-
"string",
46-
"object"
47-
],
48-
"title": "Label for alerts of type 'tip'",
49-
"default": "Tip"
48+
"type": "object",
49+
"title": "Configuration for alerts of type 'tip'",
50+
"default": {
51+
"label": "Tip",
52+
"icon": "fa-lightbulb-o",
53+
"className": "tip"
54+
}
5055
},
5156
"warning": {
52-
"type": [
53-
"string",
54-
"object"
55-
],
56-
"title": "Label for alerts of type 'warning'",
57-
"default": "Warning"
57+
"type": "object",
58+
"title": "Configuration for alerts of type 'warning'",
59+
"default": {
60+
"label": "Warning",
61+
"icon": "fa-exclamation-triangle",
62+
"className": "warning"
63+
}
5864
},
5965
"danger": {
60-
"type": [
61-
"string",
62-
"object"
63-
],
64-
"title": "Label for alerts of type 'danger'",
65-
"default": "Attention"
66+
"type": "object",
67+
"title": "Configuration for alerts of type 'danger'",
68+
"default": {
69+
"label": "Attention",
70+
"icon": "fa-ban",
71+
"className": "danger"
72+
}
6673
}
6774
}
6875
}

0 commit comments

Comments
 (0)