Skip to content

docsify plugin to convert blockquotes into beautiful and configurable alerts using preconfigured or own styles and alert types.

License

Notifications You must be signed in to change notification settings

jamuszyn/docsify-plugin-flexible-alerts

 
 

Repository files navigation

docsify plugin: Flexible Alerts

Build Status npm Version npm Downloads

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.

Sample alerts created with plugin 'flexible-alerts'

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:false]
> 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.

Custom alert

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.

Custom alert type 'comment'

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

01/19/2019 - Fixed issue when using plugin along with themeable plugin.

01/06/2019 - Initial Release

About

docsify plugin to convert blockquotes into beautiful and configurable alerts using preconfigured or own styles and alert types.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 78.9%
  • CSS 21.1%