jekyll-alerts-plugin 1.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3235aec0292542b5a6af0c457cf0a2e1eb6ba6e328ee65ec860362fbd4980638
+  data.tar.gz: ed7628d757e71911ad39d9f73eb3279c80e6f90eff0590423559587ea016b166
+SHA512:
+  metadata.gz: 50049d5c1eb5043a65fcbd158a0019fb0f51ad3fdaad4449c6c3cff65d4df5d5f2626d676b88a7a4768f8d85c3adb663a66ed633642687f498015bc01ed96349
+  data.tar.gz: add775adc16f5a026e3114c5a6b7b5303299d732ba5916dea0c7feacf930c3e100717c3339f858a5e724781fe49c2923acdee7d09bdbf129379eb69008c0d4e0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Adam Hassan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,100 @@
+# 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](https://hackback.zip/2024/03/10/Jekyll-GitHub-Alerts-Liquid.html).
+
+## Syntax
+
+### GitHub blockquote (recommended)
+
+Exactly like GitHub. The body is parsed as Markdown:
+
+```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
+
+```liquid
+{% 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`:
+
+   ```ruby
+   source "https://rubygems.pkg.github.com/Adamkadaban" do
+     gem "jekyll-alerts-plugin"
+   end
+   ```
+
+2. Authenticate to GitHub Packages once (a token with `read:packages`):
+
+   ```bash
+   bundle config https://rubygems.pkg.github.com/Adamkadaban USERNAME:TOKEN
+   ```
+
+3. Add it to `_config.yml`:
+
+   ```yaml
+   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):
+
+```yaml
+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`).

data/lib/jekyll-alerts-plugin.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+# jekyll-alerts-plugin
+#
+# GitHub-style alerts / callouts for Jekyll, with Markdown parsed inside the
+# body and the CSS injected automatically (no manual stylesheet import).
+#
+# Two authoring syntaxes, both parse Markdown inside:
+#
+#   > [!NOTE]
+#   > A note with a [markdown link](https://example.com) and **bold**.
+#
+#   {% alert note %}
+#   A note with a [markdown link](https://example.com) and **bold**.
+#   {% endalert %}
+#
+# This single file works both as a gem (require "jekyll-alerts-plugin") and as a
+# drop-in `_plugins/` script - it has no internal requires.
+
+require "jekyll"
+
+module JekyllAlertsPlugin
+  VERSION = "1.1.1"
+
+  TYPES = %w[note tip important warning caution].freeze
+
+  LABELS = {
+    "note" => "Note", "tip" => "Tip", "important" => "Important",
+    "warning" => "Warning", "caution" => "Caution"
+  }.freeze
+
+  ICONS = {
+    "note" => %q(<svg class="octicon octicon-info mr-2" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>),
+    "tip" => %q(<svg class="octicon octicon-tip mr-2" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path d="M8 1.5c-2.363 0-4 1.69-4 3.75 0 .984.424 1.625.984 2.304l.214.253c.223.264.47.556.673.848.284.411.537.896.621 1.49a.75.75 0 0 1-1.484.211c-.04-.282-.163-.547-.37-.847a8.456 8.456 0 0 0-.542-.68c-.084-.1-.173-.205-.268-.32C3.201 7.75 2.5 6.766 2.5 5.25 2.5 2.31 4.863 0 8 0s5.5 2.31 5.5 5.25c0 1.516-.701 2.5-1.328 3.259-.095.115-.184.22-.268.319-.207.245-.383.453-.541.681-.208.3-.33.565-.37.847a.751.751 0 0 1-1.485-.212c.084-.593.337-1.078.621-1.489.203-.292.45-.584.673-.848.075-.088.147-.173.213-.253.561-.679.985-1.32.985-2.304 0-2.06-1.637-3.75-4-3.75ZM5.75 12h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM6 15.25a.75.75 0 0 1 .75-.75h2.5a.75.75 0 0 1 0 1.5h-2.5a.75.75 0 0 1-.75-.75Z"></path></svg>),
+    "important" => %q(<svg class="octicon octicon-important mr-2" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path d="M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>),
+    "warning" => %q(<svg class="octicon octicon-warning mr-2" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path d="M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>),
+    "caution" => %q(<svg class="octicon octicon-caution mr-2" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path d="M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>)
+  }.freeze
+
+  # Default styles, injected automatically. The background falls back to a light
+  # GitHub-ish surface but honors a --bg-secondary theme variable if the site
+  # defines one, so it looks right in both standalone and themed sites.
+  CSS = <<~CSS
+    .markdown-alert{margin-bottom:16px;color:inherit;background-color:var(--bg-secondary,#f6f8fa);border-left:.3rem solid;border-radius:.3rem;padding:.5em}
+    .markdown-alert-body{margin-left:.75em;margin-top:-2px}
+    .markdown-alert-body>:first-child{margin-top:0}
+    .markdown-alert-body>:last-child{margin-bottom:0}
+    .markdown-alert>:first-child{margin-top:0}
+    .markdown-alert>:last-child{margin-bottom:0}
+    .markdown-alert .markdown-alert-title{display:flex;font-weight:bold;align-items:center;line-height:1;margin-bottom:0}
+    .markdown-alert.markdown-alert-note{border-left-color:#539bf5}
+    .markdown-alert.markdown-alert-note .markdown-alert-title{color:#539bf5}
+    .markdown-alert.markdown-alert-important{border-left-color:#986ee2}
+    .markdown-alert.markdown-alert-important .markdown-alert-title{color:#986ee2}
+    .markdown-alert.markdown-alert-warning{border-left-color:#c69026}
+    .markdown-alert.markdown-alert-warning .markdown-alert-title{color:#c69026}
+    .markdown-alert.markdown-alert-tip{border-left-color:#57ab5a}
+    .markdown-alert.markdown-alert-tip .markdown-alert-title{color:#57ab5a}
+    .markdown-alert.markdown-alert-caution{border-left-color:#e5534b}
+    .markdown-alert.markdown-alert-caution .markdown-alert-title{color:#e5534b}
+    .markdown-alert .octicon{color:inherit;padding:.75em;transform:scale(1.1);overflow:visible}
+    .markdown-alert .octicon-info{filter:invert(55%) sepia(55%) saturate(2060%) hue-rotate(191deg) brightness(99%) contrast(93%)}
+    .markdown-alert .octicon-tip{filter:invert(58%) sepia(64%) saturate(351%) hue-rotate(73deg) brightness(89%) contrast(90%)}
+    .markdown-alert .octicon-important{filter:invert(67%) sepia(41%) saturate(6791%) hue-rotate(225deg) brightness(92%) contrast(92%)}
+    .markdown-alert .octicon-caution{filter:invert(45%) sepia(68%) saturate(2586%) hue-rotate(333deg) brightness(95%) contrast(88%)}
+    .markdown-alert .octicon-warning{filter:invert(78%) sepia(17%) saturate(5107%) hue-rotate(350deg) brightness(85%) contrast(78%)}
+  CSS
+
+  def self.wrap(type, body_html)
+    %Q(<div class="markdown-alert markdown-alert-#{type}" dir="auto"><p class="markdown-alert-title" dir="auto">#{ICONS[type]}#{LABELS[type]}</p><div class="markdown-alert-body">#{body_html}</div></div>)
+  end
+
+  # Rewrite `> [!TYPE]` blockquotes into `{% alert type %} ... {% endalert %}`,
+  # skipping fenced code blocks so a `>` inside code is never mistaken for one.
+  def self.rewrite_blockquotes(content)
+    return content unless content&.include?("[!")
+
+    lines = content.split("\n", -1)
+    out = []
+    fence = nil
+    i = 0
+    while i < lines.length
+      line = lines[i]
+
+      if fence
+        out << line
+        fence = nil if line.strip.start_with?(fence)
+        i += 1
+        next
+      end
+
+      if (m = line.match(/^\s*(```+|~~~+)/))
+        fence = m[1]
+        out << line
+        i += 1
+        next
+      end
+
+      if (m = line.match(/^(\s*)>\s*\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*$/i))
+        type = m[2].downcase
+        body = []
+        i += 1
+        while i < lines.length && lines[i].match?(/^\s*>/)
+          body << lines[i].sub(/^\s*>\s?/, "")
+          i += 1
+        end
+        out << "{% alert #{type} %}"
+        out.concat(body)
+        out << "{% endalert %}"
+        next
+      end
+
+      out << line
+      i += 1
+    end
+
+    out.join("\n")
+  end
+
+  def self.inject_css?(site)
+    cfg = site.config["jekyll_alerts"] || site.config["alerts"]
+    return true unless cfg.is_a?(Hash) && cfg.key?("inject_css")
+    cfg["inject_css"] != false
+  end
+
+  class Tag < Liquid::Block
+    def initialize(tag_name, alert_type, tokens)
+      super
+      @alert_type = alert_type.strip.downcase
+    end
+
+    def render(context)
+      raw = super
+      return "" unless JekyllAlertsPlugin::TYPES.include?(@alert_type)
+
+      converter = context.registers[:site]
+                         .find_converter_instance(::Jekyll::Converters::Markdown)
+      body_html = converter.convert(raw).strip
+      JekyllAlertsPlugin.wrap(@alert_type, body_html)
+    end
+  end
+end
+
+Liquid::Template.register_tag("alert", JekyllAlertsPlugin::Tag)
+
+# Blockquote sugar: rewrite `> [!TYPE]` before Liquid runs.
+Jekyll::Hooks.register([:documents, :pages], :pre_render) do |item|
+  next unless item.respond_to?(:content) && item.content
+  item.content = JekyllAlertsPlugin.rewrite_blockquotes(item.content)
+end
+
+# Auto-inject the CSS once per rendered page that actually uses an alert, so
+# users never have to import a stylesheet. Disable with:
+#   jekyll_alerts:
+#     inject_css: false
+Jekyll::Hooks.register([:documents, :pages], :post_render) do |item|
+  next unless JekyllAlertsPlugin.inject_css?(item.site)
+  out = item.output
+  next unless out.is_a?(String)
+  next unless out.include?("markdown-alert") && out.include?("</head>")
+  next if out.include?('id="jekyll-alerts-css"')
+  style = %(<style id="jekyll-alerts-css">#{JekyllAlertsPlugin::CSS}</style>)
+  item.output = out.sub("</head>", "#{style}</head>")
+end

data/styles.scss

@@ -0,0 +1,118 @@
+ 
+// -------------------------------------------- //
+
+// copied from view-source:https://github.com/orgs/community/discussions/16925
+
+.markdown-alert {
+  margin-bottom: 16px;
+  color: inherit;
+  // modify to a secondary background color or comment out
+  background-color: var(--bg-secondary);
+  border-left: 0.3rem solid;
+  border-radius: 0.3rem;
+  padding:  0.5em;
+}
+
+.markdown-alert-body {
+    margin-left: 0.75em;
+    /* Reproduces the original tight spacing under the title. */
+    margin-top: -2px;
+}
+
+.markdown-alert-body>:first-child {
+  margin-top: 0
+}
+
+.markdown-alert-body>:last-child {
+  margin-bottom: 0
+}
+
+.markdown-alert>:first-child {
+  margin-top: 0
+}
+
+.markdown-alert>:last-child {
+  margin-bottom: 0
+}
+
+.markdown-alert .markdown-alert-title {
+  display: flex;
+  font-weight: bold;
+  align-items: center;
+  line-height: 1;
+  margin-bottom: 0;
+}
+
+.markdown-alert.markdown-alert-note {
+  border-left-color: #539bf5
+}
+
+.markdown-alert.markdown-alert-note .markdown-alert-title {
+  color: #539bf5
+}
+
+.markdown-alert.markdown-alert-important {
+  border-left-color: #986ee2;
+}
+
+.markdown-alert.markdown-alert-important .markdown-alert-title {
+  color: #986ee2;
+}
+
+.markdown-alert.markdown-alert-warning {
+  border-left-color: #c69026;
+}
+
+.markdown-alert.markdown-alert-warning .markdown-alert-title {
+  color: #c69026;
+}
+
+.markdown-alert.markdown-alert-tip {
+  border-left-color: #57ab5a;
+}
+
+.markdown-alert.markdown-alert-tip .markdown-alert-title {
+  color: #57ab5a;
+}
+
+.markdown-alert.markdown-alert-caution {
+  border-left-color: #e5534b;
+}
+
+.markdown-alert.markdown-alert-caution .markdown-alert-title {
+  color: #e5534b;
+}
+
+// octicon colors
+
+
+.markdown-alert .octicon {
+  color:  inherit;
+  padding: 0.75em;
+  transform: scale(1.1);
+  overflow: visible
+
+}
+
+// generated with https://codepen.io/sosuke/pen/Pjoqqp
+// colors taken from https://github.com/orgs/community/discussions/16925
+
+.markdown-alert .octicon-info {
+  filter: invert(55%) sepia(55%) saturate(2060%) hue-rotate(191deg) brightness(99%) contrast(93%);
+}
+
+.markdown-alert .octicon-tip {
+  filter: invert(58%) sepia(64%) saturate(351%) hue-rotate(73deg) brightness(89%) contrast(90%);
+}
+
+.markdown-alert .octicon-important {
+  filter: invert(67%) sepia(41%) saturate(6791%) hue-rotate(225deg) brightness(92%) contrast(92%);
+}
+
+.markdown-alert .octicon-caution {
+  filter: invert(45%) sepia(68%) saturate(2586%) hue-rotate(333deg) brightness(95%) contrast(88%);
+}
+
+.markdown-alert .octicon-warning {
+  filter: invert(78%) sepia(17%) saturate(5107%) hue-rotate(350deg) brightness(85%) contrast(78%);
+}

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-alerts-plugin
+version: !ruby/object:Gem::Version
+  version: 1.1.1
+platform: ruby
+authors:
+- Adam Hassan
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Adds GitHub-style alerts to Jekyll via `> [!NOTE]` blockquotes or a {%
+  alert %} tag. Markdown is parsed inside the body and the stylesheet is injected
+  automatically - no CSS import needed.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/jekyll-alerts-plugin.rb
+- styles.scss
+homepage: https://github.com/Adamkadaban/jekyll-alerts-plugin
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Adamkadaban/jekyll-alerts-plugin
+  bug_tracker_uri: https://github.com/Adamkadaban/jekyll-alerts-plugin/issues
+  github_repo: ssh://github.com/Adamkadaban/jekyll-alerts-plugin
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: GitHub-style alerts/callouts for Jekyll, with Markdown inside and auto-injected
+  CSS.
+test_files: []