docsify-plugin-flexible-alerts

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

Step #1 - Update index.html file

Assuming you have a working docsify app set up, it is easy to use this plugin.

1. Add the following script tag to your index.html
2. In docsify setup configure the plugin so it does fit your needs. A custom setup is not mandatory.
3. By default style 'callout' and headings 'Note', 'Tip', 'Warning', 'Attention' will be used. You can change it using plugin configuration via index.html or for a single alert in your markdown files.

<!-- Latest -->
<script src="https://unpkg.com/docsify-plugin-flexible-alerts"></script>

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"
      },
      danger: {
        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'
        }
      },
      danger: {
        label: {
          '/de-DE/': 'Achtung',
          '/': 'Attention'
        }
      }
    }
  };
</script>

Step #2 - docsify commands

Serve your documentation (docsify serve) as usual.

Usage

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).

> [!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. 'fa-info-circle'
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",

        // localization
        label: {
          '/en-GB/': 'Comment',
          '/': 'Kommentar'
        },

        // Assuming that we use Font Awesome
        icon: "fa fa-comments",
        className: "info"
      }
    }
  };
</script>

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.

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

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.