GitBook plugin to convert blockquotes into beautiful and configurable alerts using preconfigured or own styles and alert types.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
book
.editorconfig
.gitignore
.npmignore
.travis.yml
LICENSE
README.md
index.js
package-lock.json
package.json

README.md

GitBook plugin: Flexible Alerts

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.

Sample alerts created with plugin 'flexible-alerts'

Installation

Step #1 - Update book.json file

  1. In you gitbook's book.json file, add flexible-alerts to plugins list.
  2. In pluginsConfig, 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 book.json or for a single alert in your markdown files.

Sample book.json file for gitbook version 2.0.0+

{
  "plugins": [
    "flexible-alerts"
  ]
}

Sample book.json file for gitbook version 2.0.0+ and style flat instead of callout

{
  "plugins": [
    "flexible-alerts"
  ],
  "pluginsConfig": {
    "flexible-alerts": {
      "style": "flat"
    }
  }
}

Sample book.json file for gitbook version 2.0.0+ and custom headings

{
  "plugins": [
    "flexible-alerts"
  ],
  "pluginsConfig": {
    "flexible-alerts": {
      "note": {
        "label": "Hinweis"
      },
      "tip": {
        "label": "Tipp"
      },
      "warning": {
        "label": "Warnung"
      },
      "danger": {
        "label": "Achtung"
      }
    }
  }
}

Sample book.json file for gitbook version 2.0.0+ and multilingual headings

{
  "plugins": [
    "flexible-alerts"
  ],
  "pluginsConfig": {
    "flexible-alerts": {
      "note": {
        "label": {
          "de": "Hinweis",
          "en": "Note"
        }
      },
      "tip": {
        "label": {
          "de": "Tipp",
          "en": "Tip"
        }
      },
      "warning": {
        "label": {
          "de": "Warnung",
          "en": "Warning"
        }
      },
      "danger": {
        "label": {
          "de": "Achtung",
          "en": "Attention"
        }
      }
    }
  }
}

Note: Above snippets can be used as complete book.json file, if one of these matches your requirements and your book doesn't have one yet.

Step #2 - gitbook commands

  1. Run gitbook install. It will automatically install flexible-alerts gitbook plugin for your book. This is needed only once.
  2. Build your book (gitbook build) or serve (gitbook 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 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 book.json. Following example shows an additional type COMMENT.

{
  "plugins": [
    "flexible-alerts"
  ],
  "pluginsConfig": {
    "flexible-alerts": {
      "style": "callout",
      "comment": {
        "label": "Comment",
        "icon": "fa fa-comments",
        "className": "info"
      }
    }
  }
}

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 not look as expected, check if your book.json as well as alerts in Markdown are valid according to this documentation.

Changelog

01/07/2019 - Moved complete icon definition to pluginsConfig section

01/05/2019 - Initial Release