jekyll-gfm-admonitions 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 73f62b9375b8f6b7d657aba5597cab2d612a70350d044af9807bbee619774aa1
+  data.tar.gz: 06e4c485c9d50d38fdb22e9ac7228ea431f8f55e41c808af6a73837cf34037fa
+SHA512:
+  metadata.gz: 299f06fe2684ed5b9f792decd2c1d666af9f17906f4c65413de499f526f5636eb834101ef95be18a93d9ec28e79cea4b0d49eafc8001792b1a0c8859b7f9be01
+  data.tar.gz: 11e51faa997ee7d745814a2d8761a36020273c559c5b492dbbcab07e4379e4d0d8469dd8b56e5429522258084b533e0bdcbb6581f26a4348933b07eea93e79e5

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Robin De Schepper
+
+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,102 @@
+# GitHub Flavored Admonitions
+
+A Jekyll plugin to render GitHub-flavored admonitions in your Jekyll sites.
+This plugin allows you to use GitHub-flavored markdown syntax to create stylish admonition
+blocks for notes, warnings, tips, cautions, and important messages.
+
+## Supported Admonitions
+
+The following admonitions are supported:
+
+- **Important**: `> [!IMPORTANT]`
+- **Note**: `> [!NOTE]`
+- **Tip**: `> [!TIP]`
+- **Warning**: `> [!WARNING]`
+- **Caution**: `> [!CAUTION]`
+
+### Example Usage
+
+To use admonitions in your markdown files, simply add the following syntax:
+
+```markdown
+> [!IMPORTANT]
+> This is an important message.
+
+> [!NOTE]
+> This is a note.
+
+> [!TIP]
+> This is a helpful tip.
+
+> [!WARNING]
+> This is a warning.
+
+> [!CAUTION]
+> This is a caution message.
+```
+
+> [!IMPORTANT]
+> This is an important message.
+
+> [!NOTE]
+> This is a note.
+
+> [!TIP]
+> This is a helpful tip.
+
+> [!WARNING]
+> This is a warning.
+
+> [!CAUTION]
+> This is a caution message.
+
+## Installation
+
+To install the plugin, add it to your Jekyll project's `Gemfile`:
+
+```ruby
+group :jekyll_plugins do
+   
+   # Other plugins go here ...
+   
+   # ... Add this line:
+   gem "jekyll-gfm-admonitions"
+end
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+### Configuring Jekyll
+
+Next, you need to enable the plugin in your Jekyll configuration file (`_config.yml`):
+
+```yaml
+plugins:
+  - jekyll-gfm-admonitions
+```
+
+Then, during build/serve, you should see a log similar to:
+
+```
+GFMA: Converted adminitions in 1 file(s).
+```
+
+## When using GitHub Pages
+
+To enable custom plugins in your Jekyll build for GitHub Pages, you need to use GitHub
+Actions (GHA) to build and deploy your Jekyll site. For detailed instructions on setting
+up GitHub Actions for your Jekyll project, please follow this link: 
+[GitHub Actions Setup for Jekyll](https://jekyllrb.com/docs/continuous-integration/github-actions/).
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE.txt](LICENSE.txt) file
+for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues or pull requests.

data/assets/admonitions.css

@@ -0,0 +1,73 @@
+.markdown-alert {
+    padding: 0.5rem 1rem;
+    margin-bottom: 1rem;
+    color: inherit;
+    border-left: .25em solid #30363d;
+}
+
+.markdown-body .markdown-alert > :first-child {
+    margin-top: 0;
+}
+
+.markdown-body .markdown-alert > :last-child {
+    margin-bottom: 0;
+}
+
+.markdown-body .markdown-alert .markdown-alert-title {
+    display: flex;
+    font-weight: 500;
+    align-items: center;
+    line-height: 1;
+}
+
+.markdown-body .markdown-alert svg {
+    margin-right: 0.5rem !important;
+}
+
+.markdown-body .markdown-alert svg path {
+    fill: currentColor;
+}
+
+.markdown-body .markdown-alert.markdown-alert-note {
+    border-left-color: #4493f8;
+}
+
+.markdown-body .markdown-alert.markdown-alert-note svg path {
+    color: #4493f8;
+}
+
+.markdown-body .markdown-alert.markdown-alert-important {
+    border-left-color: #ab7df8;
+}
+
+.markdown-body .markdown-alert.markdown-alert-important .markdown-alert-title {
+    color: #ab7df8;
+}
+
+.markdown-body .markdown-alert.markdown-alert-warning {
+    border-left-color: #9e6a03;
+}
+
+.markdown-body .markdown-alert.markdown-alert-warning .markdown-alert-title {
+    color: #d29922;
+}
+
+.markdown-body .markdown-alert.markdown-alert-tip {
+    border-left-color: #238636;
+}
+
+.markdown-body .markdown-alert.markdown-alert-tip .markdown-alert-title {
+    color: #3fb950;
+}
+
+.markdown-body .markdown-alert.markdown-alert-caution {
+    border-left-color: #da3633;
+}
+
+.markdown-body .markdown-alert.markdown-alert-caution .markdown-alert-title {
+    color: #f85149;
+}
+
+.markdown-body > :first-child > .heading-element:first-child {
+    margin-top: 0 !important;
+}

data/lib/jekyll-gfm-admonitions.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'octicons'
+require 'cssminify'
+
+ADMONITION_ICONS = {
+  'important' => 'report',
+  'note' => 'info',
+  'tip' => 'light-bulb',
+  'warning' => 'alert',
+  'caution' => 'stop'
+}.freeze
+
+# JekyllGFMAdmonitions is a module that provides functionality to process and
+# convert GitHub-flavored markdown admonitions into HTML within Jekyll.
+module JekyllGFMAdmonitions
+  # GFMAdmonitionConverter is a Jekyll generator that converts custom
+  # admonition blocks in markdown (e.g., `> [!IMPORTANT]`) into styled HTML
+  # alert boxes with icons.
+  #
+  # This generator processes both posts and pages, replacing admonition
+  # syntax with HTML markup that includes appropriate iconography and CSS styling.
+  class GFMAdmonitionConverter < Jekyll::Generator
+    safe true
+
+    def initialize(*args)
+      super(*args)
+      @converted = 0
+    end
+
+    def generate(site)
+      # Process admonitions in posts
+      site.posts.docs.each do |doc|
+        process(doc)
+      end
+
+      # Process admonitions in pages
+      site.pages.each do |page|
+        process(page)
+      end
+
+      Jekyll.logger.info 'GFMA:', "Converted adminitions in #{@converted} file(s)."
+    end
+
+    def process(doc)
+      original_content = doc.content.dup
+      convert_admonitions(doc)
+
+      return unless doc.content != original_content
+
+      inject_css(doc)
+      @converted += 1
+    end
+
+    def convert_admonitions(doc)
+      doc.content.gsub!(/>\s*\[!(IMPORTANT|NOTE|WARNING|TIP|CAUTION)\]\s*\n((?:>.*\n?)*)/) do
+        type = ::Regexp.last_match(1).downcase
+        title = type.capitalize
+        text = ::Regexp.last_match(2).gsub(/^>\s*/, '').strip
+        icon = Octicons::Octicon.new(ADMONITION_ICONS[type]).to_svg
+
+        "<div class='markdown-alert markdown-alert-#{type}'>
+          <p class='markdown-alert-title'>#{icon} #{title}</p>
+          <p>#{text}</p>
+        </div>"
+      end
+    end
+
+    def inject_css(doc)
+      css = File.read(File.expand_path('../assets/admonitions.css', __dir__))
+      doc.content += "<style>#{CSSminify.compress(css)}</style>"
+    end
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-gfm-admonitions
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Robin De Schepper
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-09-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: This plugin allows you to use GitHub-flavored markdown syntaxto create
+  admonition blocks in Jekyll sites.
+email:
+- robin.deschepper93@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- assets/admonitions.css
+- lib/jekyll-gfm-admonitions.rb
+homepage: https://github.com/helveg/jekyll-gfm-admonitions
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.20
+signing_key:
+specification_version: 4
+summary: A Jekyll plugin to render GitHub-flavored admonitions.
+test_files: []