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.
- Highly customizable (Create your own styles and templates easily)
- Non-intrusive - Its just Markdown!
- Easy to install
- Comes with a default stylesheet (Sass/Css) and templates for beautiful messages boxes and citation.
- Font Awesome 5 support
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.
- Jekyll 3.7.x or higher (We recommend the new Jekyll 4)
Add the following line to your
Gemfile inside your Jekyll project folder:
group :jekyll_plugins do gem "premonition", "4.0.0" end
Then add the the plugin to your
plugins: - premonition
Now make sure to download the Premonition bundle:
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
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.
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
The default types are:
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.
Simple note with no header
> note "" > No headers in here
> note "I am a not" > The body of the note goes here. Premonition allows you to write any `Markdown` inside the block.
> info "I am some info" > The body of the info box goes here. Premonition allows you to write any `Markdown` inside the block.
> warning "I am a warning" > The body of the warning box goes here. Premonition allows you to write any `Markdown` inside the block.
> 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)
> citations "Mark Twain" [ cite = "mt" ] > I will be a beautiful citation quote
The templates can be customized in two eays. 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.
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
- 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
get an idea of how this is done.
Overriding the default template
You can override the default template like this in your
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 follow 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
premonition: types: error: fa-icon: "fa-bug"
Simple as that :)