docsify-plugin-flexible-alerts
Version:
docsify plugin to convert blockquotes into beautiful and configurable alerts using preconfigured or own styles and alert types.
273 lines (211 loc) • 8.67 kB
Markdown
[](https://github.com/fzankl/docsify-plugin-flexible-alerts)
[](https://www.npmjs.com/package/docsify-plugin-flexible-alerts)
[](https://www.npmjs.com/package/docsify-plugin-flexible-alerts)
This docsify plugin converts blockquotes into beautiful alerts. Look and feel can be configured on a global as well as on an alert specific level so output does fit your needs (some examples are shown below). In addition, you can provide own alert types.
## Installation and Usage
### Step #1 - Update `index.html` file
Assuming you have a working [docsify](https://docsify.js.org) app set up, it is easy to use this plugin.
1. Add the following script tag to your `index.html`
```html
<!-- Latest -->
<script src="https://unpkg.com/docsify-plugin-flexible-alerts"></script>
```
2. In docsify setup configure the plugin so it does fit your needs. A custom setup is not mandatory. By default, styles `flat` and `callout` (Default: `callout`) and types `NOTE`, `TIP`, `WARNING`, `IMPORTANT` and `ATTENTION` are supported. For a better compatibility some aliases exists. `INFO`, `DANGER` and `CAUTION` can also be used to define the alerts.
You can change it using plugin configuration via `index.html` or for a single alert in your markdown files. (please see section `Customizations` for further details)
**Sample `index.html` file using style `flat` instead of `callout`**
```javascript
<script>
window.$docsify = {
'flexible-alerts': {
style: 'flat'
}
};
</script>
```
**Sample `index.html` using custom headings**
```javascript
<script>
window.$docsify = {
'flexible-alerts': {
note: {
label: "Hinweis"
},
tip: {
label: "Tipp"
},
warning: {
label: "Warnung"
},
important: {
label: "Wichtig"
},
attention: {
label: "Achtung"
}
}
};
</script>
```
**Sample `index.html` using multilingual headings**
```javascript
<script>
window.$docsify = {
'flexible-alerts': {
note: {
label: {
'/de-DE/': 'Hinweis',
'/': 'Note'
}
},
tip: {
label: {
'/de-DE/': 'Tipp',
'/': 'Tip'
}
},
warning: {
label: {
'/de-DE/': 'Warnung',
'/': 'Warning'
}
},
important: {
label: {
'/de-DE/': 'Wichtig',
'/': 'Important'
}
},
attention: {
label: {
'/de-DE/': 'Achtung',
'/': 'Attention'
}
}
}
};
</script>
```
Modify or add a new blockquote so it matches required syntax like shown in following examples:
* Sample alert using type `NOTE`
```markdown
> [!NOTE]
> An alert of type 'note' using global style 'callout'.
```
* Sample alert using type `TIP`
```markdown
> [!TIP]
> An alert of type 'tip' using global style 'callout'.
```
* Sample alert using type `WARNING`
```markdown
> [!WARNING]
> An alert of type 'warning' using global style 'callout'.
```
* Sample alert using type `IMPORTANT`
```markdown
> [!IMPORTANT]
> An alert of type 'important' using global style 'callout'.
```
* Sample alert using type `ATTENTION`
```markdown
> [!ATTENTION]
> An alert of type 'attention' using global style 'callout'.
```
Serve your documentation (`docsify serve`) as usual.
## Customizations
To use the plugin just modify an existing blockquote and prepend a line matching pattern `[!type]`. By default, types `NOTE`, `TIP`, `WARNING`, `IMPORTANT` and `ATTENTION` along with some aliases are supported. You can extend the available types by providing a valid configuration (see below for an example).
```markdown
> [!NOTE]
> An alert of type 'note' using global style 'callout'.
```
```markdown
> [!NOTE|style:flat]
> An alert of type 'note' using alert specific style 'flat' which overrides global style 'callout'.
```
As you can see in the second snippet, output can be configured on alert level also. Supported options are listed in following table:
| Key | Allowed value |
|-----------------|---------------------------------------------------------|
| style | One of following values: callout, flat |
| label | Any text |
| icon | A valid Font Awesome icon, e.g. 'fas fa-comment' |
| className | A name of a CSS class which specifies the look and feel |
| labelVisibility | One of following values: visible (default), hidden |
| iconVisibility | One of following values: visible (default), hidden |
Multiple options can be used for single alerts as shown below:
```markdown
> [!TIP|style:flat|label:My own heading|iconVisibility:hidden]
> An alert of type 'tip' using alert specific style 'flat' which overrides global style 'callout'.
> In addition, this alert uses an own heading and hides specific icon.
```
As mentioned above you can provide your own alert types. Therefore, you have to provide the type configuration via `index.html`. Following example shows an additional type `COMMENT`.
```javascript
<script>
window.$docsify = {
'flexible-alerts': {
comment: {
label: 'Comment',
// localization
label: {
'/en-GB/': 'Comment',
'/': 'Kommentar'
},
// Assuming that we use Font Awesome
icon: 'fas fa-comment',
className: 'note'
}
}
};
</script>
```
**Since we are using FontAwesome in previous example we have to include the library via `index.html`, e.g. using a CDN.**
In Markdown just use the alert according to the types provided by default.
```markdown
> [!COMMENT]
> An alert of type 'comment' using style 'callout' with default settings.
```
Instead of configuring this plugin using key `flexible-alerts` you can use camel case notation `flexibleAlerts` as well.
```javascript
<script>
window.$docsify = {
'flexibleAlerts': {
style: 'flat'
}
};
</script>
```
The repository contains some [examples](./samples) how the plugin can be used.
To run the sample checkout the code and execute `npm run serve`.
If alerts do not look as expected, check if your `index.html` as well as alerts in Markdown are valid according to this documentation.
10/01/2025
* Added support for docsify v5.x.
* Added alert type `IMPORTANT` along with some new aliases.
* Added examples to illustrate usage
* Updated development dependencies
* Fixed issue concerning custom label containing U+2024, ONE DOT LEADER
12/22/2022
* Fixed rendering of alerts when the content does not contain white spaces which can occur with some character encodings.
08/20/2022
* Updated development dependencies and moved to GitHub Actions.
09/20/2020
* Removed dependency to FontAwesome and embedded icons as SVG directly.
* Support dark mode for callout alert style.
* Moved alert type naming from 'danger' to 'attention'. Introduced type mappings to support mapping further alert type keys to existing definitions, e.g. map legacy alert type 'danger' to new type definition 'attention'.
09/23/2019
* Fixed issue concerning custom Font Awesome icons when using on alert based level.
04/14/2019
* Added camel case support for plugin configuration key.
03/03/2019
* Fixed issue concerning languages using characters others than [a-z,A-Z,0-9] like Chinese or Russian.
01/19/2019
* Fixed issue when using plugin along with themeable plugin.
01/06/2019
* Initial release.