gitbook-plugin-asciidoc-admonition-icons

1.1.0 • Public • Published

GitBook Plugin: Provides font icons for AsciiDoc admonition blocks.

npm npm GitHub contributors

Stars, issues, PRs, etc, on GitHub @ msavy/gitbook-plugin-asciidoc-admonition-icons.


As of publishing, the GitBook AsciiDoc 3.x.x rendering pipeline does not support icons for admonition blocks, providing an inconspicuous, text-only representation:

image

With this plugin, admonition blocks are altered to provide the missing icons:

image

The default styling provides a similar look-and-feel to the Asciidoctor's standard theme; with FontAwesome icons and a comparable colour scheme. Naturally, you can override both the glyphs and styling.

Refer to the Configuration section for more detail.

Examples

image

Configuration

Installation

In book.json, add asciidoc-admonition-icons to your plugins array:

{
    "plugins": ["asciidoc-admonition-icons"]
}

Basic Configuration

Override the default configuration in the pluginsConfig.admonitions section of book.json.

  • The 5 standard AsciiDoc admonition types are available, with the following mutable attributes [1]:
    • classes: CSS classes of the admonition icon container.
    • title: HTML title attribute of admonition icon container.
    • content: Unicode value of glyph to use.

The entire set of defaults are shown here for illustrative purposes, but you need only provide those you're overriding:

Example book.json configuration:

"pluginsConfig"{
    "admonitions": {
        "note": {
            "classes": "fa icon-note",
            "title": "Note",
            "content": "\uf05a"
        },
        "tip": {
            "classes": "fa icon-tip",
            "title": "Tip",
            "content": "\uf0eb"
        },
        "important": {
            "classes": "fa icon-important",
            "title": "Important",
            "content": "\uf06a"
        },
        "caution": {
            "classes": "fa icon-caution",
            "title": "Caution",
            "content": "\uf06d"
        },
        "warning": {
            "classes": "fa icon-warning",
            "title": "Warning",
            "content": "\uf071"
        }
    }
}

For example, to override the TIP admonition type, you could alter the content field to be something else:

"pluginsConfig"{
    "admonitions": {
        "warning": {
            "classes": "fa icon-tip",
            "title": "Tip",
            "content": "\uf197"
        }
    }
}

Now, it will look something like:

icon-tip overridden

Overriding Style

You can override the default CSS in (at least) two ways:

  1. Change the classes attribute(s) and provide your own style.
  2. Override or extend the existing CSS. You may need to use the !important property in some circumstances.

Example colour override in style/website.css:

.icon-tip {
    color: rgb(243, 21, 243, 0.7) !important;
}

Refer to the GitBook documentation about including user CSS.

Provenance

The default Less/CSS is derived from the apiman blog theme, which is in turn derived from Asciidoctor default theme. Thanks to them.

I initially forked (a fork of) https://github.com/erixtekila/gitbook-plugin-richquotes, but what you see here bears little resemblance to it; however, it provided an excellent skeleton for a neophyte.

License

Where appropriate, code is copyright 2017, Marc Savy marc@rhymewithgravy.com. Released under Apache License, Version 2.0.

Footnotes

  1. NOTE, TIP, IMPORTANT, CAUTION, WARNING

Dependencies (1)

Dev Dependencies (2)

Package Sidebar

Install

npm i gitbook-plugin-asciidoc-admonition-icons

Weekly Downloads

4

Version

1.1.0

License

Apache-2.0

Last publish

Collaborators

  • marcsavy