jekyll-alerts-plugin

GitHub-style alerts / callouts for Jekyll. Markdown works inside the body and the CSS is injected automatically - add the plugin and you're done, no stylesheet to import.

Blog write-up here.

Syntax

GitHub blockquote (recommended)

Exactly like GitHub. The body is parsed as Markdown:

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

Liquid block

{% alert note %}
A note with a [markdown link](https://example.com), **bold**, and `code`.

- lists work too
- across multiple lines
{% endalert %}

Install

[!NOTE] Custom plugins (gem or _plugins/) run on any Jekyll build except GitHub Pages' native build. Use GitHub Actions, Netlify, or a local build.

As a gem (from GitHub Packages)

1. Tell Bundler where to find the package, then add the gem. In your Gemfile:

   source "https://rubygems.pkg.github.com/Adamkadaban" do
     gem "jekyll-alerts-plugin"
   end
   

2. Authenticate to GitHub Packages once (a token with read:packages):

   bundle config https://rubygems.pkg.github.com/Adamkadaban USERNAME:TOKEN
   

3. Add it to _config.yml:

   plugins:
     - jekyll-alerts-plugin
   

That's it - alerts render and the stylesheet is injected automatically.

Drop-in (no gem)

Copy lib/jekyll-alerts-plugin.rb into your site's _plugins/ directory. It is self-contained, so it works the same way (including auto-injected CSS).

Styling

The default GitHub palette is injected automatically. The alert background uses var(--bg-secondary, #f6f8fa), so it adopts your theme's --bg-secondary if you have one and falls back to a light surface otherwise.

To supply your own CSS instead, disable the injection and add the rules from styles.scss (which use CSS variables you can theme for light/dark):

jekyll_alerts:
  inject_css: false

How it works

• A Liquid block tag ({% alert %}) renders the body through the site's Markdown converter, then wraps it in GitHub-style markup with an Octicon.
• A pre_render hook rewrites > [!TYPE] blockquotes into that tag before Liquid runs, skipping fenced code blocks. Ordinary blockquotes are left untouched.
• A post_render hook injects the stylesheet once into any page that contains an alert (unless inject_css: false).