Premonition

Demo site (Source code)

Premonition is a higly customizable Jekyll plugin that can convert Markdown block-quotes into beautiful block styled content.

By simply adding a custom header to the first line of a block quote, Premonition will transform it into a markup block of your choice.

Features

• Highly customizable (Create your own styles and templates easily)
• Non-intrusive - It's just Markdown!
• Easy to install
• Comes with a default stylesheet (Sass/Css) and templates for beautiful messages boxes and citation.
• Font Awesome 5 support
• Support for Jekyll Collections (Added in 4.0.2)

Version 4 Highlights

• Jekyll Post Excerpts support
• New install command for the default stylesheet.
• Kramdown reference links support
• Jekyll 4 support (3.7 still supported)
• Added support for block attributes (See documentation further down)
• Added new citation block type.
• Minor fixes to the Premonition stylesheet.
• Removed the need Font Awesome css in default stylesheet, but Font Awesome is still supported.
• Other bug fixes. See HISTORY.md.

See UPGRADE.md for help on how to upgrade from 2.x to 4.0.

Requirements

• Jekyll 3.7.x or higher (We recommend the new Jekyll 4)

Installation

Add the following line to your Gemfile inside your Jekyll project folder:

group :jekyll_plugins do
  gem "premonition", "4.0.1"
end

Then add the the plugin to your _config.yml:

plugins:
  - premonition

Now make sure to download the Premonition bundle:

bundle install

Installing the default stylesheet

Finally, if you want to use the default Premonition styling (You really should!), then you have to install the SASS stylesheet. Note: The installer expect you to have installed SASS support like it is described in the Jekyll documentation: https://jekyllrb.com/docs/step-by-step/07-assets/#sass.

From your Jekyll project folder, run:

bundle exec jekyll premonition-install

This will add the premonition.scss file to your _sass folder and ask if you want to import this file into your assets/main.scss file. Both of these settings (destination folder and main file) can be configured. Run bundle exec jekyll premonition-install --help to see how.

If you prefer CSS, then download the stylesheet/premonition.css file directly from this repo.

Usage

A Premonition block is really just a standard Markdown blockquote where the first line of the block must follow a certain syntax.

> [type] "Title" [ attributes... ]

The type must be set to one of the default Premonition block types, or a type defined by you in _config.yml.

The default types are:

• note
• info
• warning
• error
• citation

The Title will normally be the block header. Leave it empty to disable the header.

attributes are in use by the Citation type, but can be skipped for the other default types. See section about custom types for more info.

Examples

Simple note with no header

> note ""
> No headers in here

Note

> note "I am a note"
> The body of the note goes here. Premonition allows you to write any `Markdown` inside the block.

Info

> info "I am some info"
> The body of the info box goes here. Premonition allows you to write any `Markdown` inside the block.

Warning

> warning "I am a warning"
> The body of the warning box goes here. Premonition allows you to write any `Markdown` inside the block.

Error

> error "I am an error"
> The body of the error box goes here. Premonition allows you to write any `Markdown` inside the block.

Citation (Note the use of attributes here)

> citation "Mark Twain" [ cite = "mt" ]
> I will be a beautiful citation quote

Configuration

The templates can be customized in two ways. Either by replacing one of the default templates, or by adding a new type from scratch.

All this is done inside your _config.yml. Look at the source code for our demo site, for live examples on how configuration can be done.

Templates

Like Jekyll itself, Premonition uses the Liquid Markup Language for templating.

Six variables are available to the template engine:

• header Boolean that tells you if a title exists and that a header should be added.
• content The rendered content for your block.
• title The block title.
• type The type name (eg: note).
• meta This is a hash that can contain any properties you would like to make available to your template. It is configured in _config.yml
• attrs These are the attributes set in the block header. Like we did in the Citation example above.

Take a look at our default template inside lib/premonition/resources.rb to get an idea of how this is done.

Overriding the default template

You can override the default template like this in your _config.yml:

premonition:
  default:
    template: "Liquid template goes here"

Overriding the template for a default type

If you want to override the template for one of the default types (like note), do it like this:

premonition:
  types:
    note:
      template: "Liquid template goes here"

Adding custom types

Adding a custom type is just a matter of adding it to _config.yml. You can either override one of the defaults, or add a new one.

For each type you can

• Add a custom template (template)
• Set a default title (default_title)
• Set meta data that can be used inside the template

Each type must have unique id (lowercase letters).

premonition:
  types:
    custombox:
      meta:
        my-meta: "By myself"
    advanced:
      template: "Liquid template goes here"
      default_title: "MY BLOCK"
      meta:
        my-meta: "By myself"

More on styling

As described in the Installation section above, it is pretty easy to install the default stylesheet into your project. But we recognize that this design probably isn't a perfect fit for everybody. Luckily you can modify it :)

Our recommendation is to install the default stylesheet and override it in another SASS file. This way it will be easy to upgrade the default Stylesheet later without loosing your changes.

The Jekyll Documentation describes the process of adding your own SASS files in great details.

Font Awesome support

Premonition 4.x no longer depends on Font Awesome for its default stylesheet. But it is still supported.

To add Font Awesome support you should add something like this to your head template file:

<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.12.1/css/all.css">

Feel free to install it any other way you prefer, as long as you adhere to their license.

Now you can swith to Font Awesome for any of the default types by adding fa-icon to a types meta object. Let's say you want to replace the default error box icon with the beautiful fa-bug icon from Font Awesome.

Then just add this to your _config.yml:

premonition:
  types:
    error:
      fa-icon: "fa-bug"

Simple as that :)