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 a 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 app set up, it is easy to use this plugin.
-
Add the following script tag to your index.html
<script src="https://unpkg.com/docsify-plugin-flexible-alerts"></script>
-
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
and ATTENTION
are supported.
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
<script>
window.$docsify = {
'flexible-alerts': {
style: 'flat'
}
};
</script>
Sample index.html
using custom headings
<script>
window.$docsify = {
'flexible-alerts': {
note: {
label: "Hinweis"
},
tip: {
label: "Tipp"
},
warning: {
label: "Warnung"
},
attention: {
label: "Achtung"
}
}
};
</script>
Sample index.html
using multilingual headings
<script>
window.$docsify = {
'flexible-alerts': {
note: {
label: {
'/de-DE/': 'Hinweis',
'/': 'Note'
}
},
tip: {
label: {
'/de-DE/': 'Tipp',
'/': 'Tip'
}
},
warning: {
label: {
'/de-DE/': 'Warnung',
'/': 'Warning'
}
},
attention: {
label: {
'/de-DE/': 'Achtung',
'/': 'Attention'
}
}
}
};
</script>
Step #2 - Prepare documentation
Modify or add a new blockquote so it matches required syntax like shown in following examples:
-
Sample alert using type NOTE
> [!NOTE]
> An alert of type 'note' using global style 'callout'.
-
Sample alert using type TIP
> [!TIP]
> An alert of type 'tip' using global style 'callout'.
-
Sample alert using type WARNING
> [!WARNING]
> An alert of type 'warning' using global style 'callout'.
-
Sample alert using type ATTENTION
> [!ATTENTION]
> An alert of type 'attention' using global style 'callout'.
Step #3 - docsify commands
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
and ATTENTION
are supported. You can extend the available types by providing a valid configuration (see below for an example).
> [!NOTE]
> An alert of type 'note' using global style 'callout'.
> [!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 follwowing 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 follwowing values: visible (default), hidden |
iconVisibility | One of follwowing values: visible (default), hidden |
Multiple options can be used for single alerts as shown below:
> [!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
.
<script>
window.$docsify = {
'flexible-alerts': {
comment: {
label: 'Comment',
label: {
'/en-GB/': 'Comment',
'/': 'Kommentar'
},
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.
> [!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.
<script>
window.$docsify = {
'flexibleAlerts': {
style: 'flat'
}
};
</script>
Troubleshooting
If alerts do no look as expected, check if your index.html
as well as alerts in Markdown are valid according to this documentation.
Changelog
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