jekyll-webawesome 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 11da0d2da16359893d07591941d1dcca5184c7befcaa03c95adab45b4945e2c2
+  data.tar.gz: e573335ac4e9caa1c46585593f1ab0718c58e58e03060dcb21a159a16324678a
+SHA512:
+  metadata.gz: d90cc934527c25df1c8444cb1e193f383ae60f6a4a679c590cffa1fdf25606d10f728b5bd30ab41cb96c44d1053300d49c8fdb4943b5568ff47c20d2f23636eb
+  data.tar.gz: 364c6eb910786df9e07ee90629c2a2af9fe8062d97e7837596f5ae320318eb2e65f25364c468995f79b70cbd65fd49a36628ee64aa009588349abd6ee0b39b9f

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+
+## [Unreleased]
+
+## [0.1.0] - 2025-08-09
+
+### Added
+
+- Initial release of jekyll-webawesome gem
+- Support for callout components (:::info, :::success, :::warning, :::danger, :::neutral)
+- Support for details/summary components (^^^...>>>...^^^)
+- Support for tab group components (++++++...++++++)
+- Automatic Jekyll hooks integration

data/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Janne Warén
+
+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,397 @@
+# jekyll-webawesome
+
+This is a plugin for [Jekyll](https://jekyllrb.com/) that transforms custom Markdown syntax into [Web Awesome](https://webawesome.com/) components. Use a simple, intuitive Markdown-like syntax to create rich interactive components in your Jekyll website. The goal is to keep HTML out of Markdown files and create an easier experience for non-developers to update content.
+
+The context here is a technical documentation website, and being limited to just basic Markdown features often results in a boring wall of text which the user won't read. The aim is to help create a more visually interesting page to read, by mixing in some components like callouts, tabs, cards and collapsible summary/details.
+
+## Web Awesome components
+
+This plugin focuses on the most commonly used Web Awesome components for Jekyll content. Components are organized by support status:
+
+### Currently supported
+
+| Component | Primary Syntax | Alternative Syntax | HTML Output |
+|-----------|----------------|-------------------|-------------|
+| **Badge** | `!!!variant` | `:::wa-badge variant` | `<wa-badge variant="brand">content</wa-badge>` |
+| **Button** | `%%%variant` | `:::wa-button variant` | `<wa-button variant="brand" href="url">text</wa-button>` or `<wa-button variant="brand">text</wa-button>` |
+| **Callouts** | `:::info` | `:::wa-callout info` | `<wa-callout variant="brand"><wa-icon name="circle-info"></wa-icon>content</wa-callout>` |
+| **Card** | `===` | `:::wa-card` | `<wa-card>content</wa-card>` |
+| **Details** | `^^^` | `:::wa-details` | `<wa-details><summary>summary</summary>content</wa-details>` |
+| **Tab Group** | `++++++` | `:::wa-tabs` | `<wa-tab-group><wa-tab>content</wa-tab></wa-tab-group>` |
+| **Tag** | `@@@brand` | `:::wa-tag brand` | `<wa-tag variant="brand">content</wa-tag>` |
+
+### Planned
+
+These content-focused components will get dedicated syntax in future releases:
+
+| Component | Primary Syntax | Alternative syntax | HTML Output |
+|-----------|----------------------|-------------------|-------------|
+| **Copy Button** | `<<<` | `:::wa-copy-button` | `<wa-copy-button>content</wa-copy-button>` |
+| **Divider** | `\|\|\|` | `:::wa-divider` | `<wa-divider></wa-divider>` |
+| **Icon** | `$$$icon-name` | `:::wa-icon name` | `<wa-icon name="icon-name"></wa-icon>` |
+| **Progress Bar** | `&&&value` | `:::wa-progress-bar value` | `<wa-progress-bar value="50"></wa-progress-bar>` |
+| **Rating** | `???value` | `:::wa-rating value` | `<wa-rating value="4"></wa-rating>` |
+| **Avatar** | (none) | `:::wa-avatar` | `<wa-avatar>` |
+| **QR Code** | (none) | `:::wa-qr-code` | `<wa-qr-code>` |
+| **Skeleton** | (none) | `:::wa-skeleton` | `<wa-skeleton>` |
+| **Spinner** | (none) | `:::wa-spinner` | `<wa-spinner>` |
+| **Tooltip** | (none) | `:::wa-tooltip` | `<wa-tooltip>` |
+
+Not all components will make sense to include here, to be included in the "prose" content of a web page. Some components are more suitable to be used in layouts or used in the page as includes, too complicated for this purpose.
+
+Both syntax styles work identically and can be mixed within the same document.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'jekyll-webawesome'
+```
+
+Add the plugin to your Jekyll site's `_config.yml`:
+
+```yaml
+plugins:
+  - jekyll-webawesome
+```
+
+And add configuration options as needed in `_config.yml`:
+
+```yaml
+webawesome:
+  # Enable debug output to see which files are being processed
+  debug: true
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Live Examples
+
+See the plugin in action with a complete Jekyll site showcasing all supported components:
+
+```bash
+cd examples
+bundle install
+bundle exec jekyll serve
+```
+
+Then visit `http://localhost:4000` to see all components rendered with Web Awesome styling.
+
+> **Note**: All components support dual syntax. You can use either the primary syntax (shown in examples below) or the alternative `:::wa-component` syntax.
+
+## Components
+
+### Callouts
+
+Create callouts using the `:::` syntax:
+
+```markdown
+:::info
+This is an info callout with **bold text** and [links](https://example.com).
+:::
+
+:::success
+This is a success callout.
+:::
+
+:::warning
+This is a warning callout.
+:::
+
+:::danger
+This is a danger callout.
+:::
+
+:::neutral
+This is a neutral callout.
+:::
+```
+
+These transform into Web Awesome callout components with appropriate icons and styling.
+
+### Cards
+
+Create cards using the `===` syntax:
+
+```markdown
+===
+This is a basic card with just content.
+===
+```
+
+#### Cards with Headers
+
+The first heading (`#`) automatically becomes the card header:
+
+```markdown
+===
+# Card Title
+This is the card content that appears in the main area.
+===
+```
+
+#### Cards with Media
+
+The first image automatically becomes the card media:
+
+```markdown
+===
+![Alt text](image.jpg)
+# Featured Content
+This card includes both an image and a title.
+===
+```
+
+#### Cards with Footers
+
+Links at the end of the card content automatically become footer buttons:
+
+```markdown
+===
+# Get Started
+Ready to begin your journey? 
+[Learn More](https://example.com)
+===
+```
+
+#### Complete Cards
+
+You can combine all elements for rich content cards:
+
+```markdown
+===filled
+![Hero Image](hero.jpg)
+# Complete Example
+This card has media, header, content, and footer with a filled appearance.
+[Get Started](https://example.com)
+===
+```
+
+#### Card Appearances
+
+You can specify different visual styles:
+
+```markdown
+===filled
+# Filled Card
+This card uses the filled appearance.
+===
+
+===plain
+# Plain Card
+This card uses the plain appearance.
+===
+
+===filled-outlined
+# Filled Outlined Card
+This card uses the filled-outlined appearance.
+===
+
+===accent
+# Accent Card
+This card uses the accent appearance for emphasis.
+===
+```
+
+### Tags
+
+Create tags using the `@@@` syntax:
+
+```markdown
+@@@
+Basic tag
+@@@
+
+@@@brand
+Version 2.0
+@@@
+
+@@@success
+Completed
+@@@
+
+@@@warning
+In Progress
+@@@
+
+@@@danger
+Critical Issue
+@@@
+
+@@@neutral
+Documentation
+@@@
+```
+
+These transform into Web Awesome tag components with appropriate colors and styling. Tags support markdown formatting within the content:
+
+```markdown
+@@@brand
+**v3.0** Beta
+@@@
+
+@@@success
+[View Results](https://example.com)
+@@@
+```
+
+### Details/Summary (Collapsible Content)
+
+Create collapsible content using the `^^^` syntax:
+
+```markdown
+^^^
+Click to expand this summary
+>>>
+This is the detailed content that can be collapsed and expanded.
+
+You can include:
+- Lists
+- **Bold text**
+- [Links](https://example.com)
+- Code blocks
+^^^
+```
+
+You can also specify appearance styles:
+
+```markdown
+^^^filled
+Filled appearance summary
+>>>
+Content goes here
+^^^
+
+^^^plain
+Plain appearance summary  
+>>>
+Content goes here
+^^^
+
+^^^filled-outlined
+Filled and outlined appearance summary
+>>>
+Content goes here
+^^^
+```
+
+### Tab Groups
+
+Create tabbed content using the `++++++` syntax:
+
+```markdown
+++++++
++++ First Tab
+Content for the first tab goes here.
++++
+
++++ Second Tab
+Content for the second tab.
++++
+
++++ Third Tab
+Content for the third tab.
++++
+++++++
+```
+
+You can specify tab placement:
+
+```markdown
+++++++start
++++ Tab 1
+Content here
++++
++++ Tab 2  
+More content
++++
+++++++
+
+++++++bottom
++++ Tab 1
+Content here
++++
++++ Tab 2
+More content  
++++
+++++++
+```
+
+Supported placements: `top` (default), `bottom`, `start`, `end`.
+
+## Component Reference
+
+### Callout Types
+
+| Type | Icon | Variant |
+|------|------|---------|
+| `info` | circle-info | brand |
+| `success` | circle-check | success |
+| `warning` | triangle-exclamation | warning |
+| `danger` | circle-exclamation | danger |
+| `neutral` | gear | neutral |
+
+### Card Options
+
+| Type | Description |
+|------|-------------|
+| `outlined` (default) | Default outlined appearance |
+| `filled` | Filled background appearance |
+| `plain` | Minimal plain appearance |
+| `filled-outlined` | Combination of filled and outlined |
+| `accent` | Accent appearance for emphasis |
+
+### Card Structure
+
+Cards automatically parse content into these slots:
+
+- **Media**: First image becomes media slot
+- **Header**: First `#` heading becomes header slot  
+- **Content**: Remaining content becomes main content
+- **Footer**: Trailing links become footer buttons
+
+### Tag Variants
+
+| Type | Description |
+|------|-------------|
+| (none) | Default neutral appearance |
+| `brand` | Primary brand color |
+| `success` | Success/positive state |
+| `warning` | Warning/caution state |
+| `danger` | Error/critical state |
+| `neutral` | Neutral/informational state |
+
+### Details Appearances
+
+| Type | CSS Class |
+|------|-----------|
+| `outlined` (default) | outlined |
+| `filled` | filled |
+| `plain` | plain |
+| `filled-outlined` | filled outlined |
+
+### Tab Placements
+
+- `top` (default)
+- `bottom`
+- `start`
+- `end`
+
+## Requirements
+
+- Jekyll >= 3.7
+- Kramdown >= 2.0
+- Web Awesome CSS/JS loaded in your site
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/jannewaren/jekyll-webawesome](https://github.com/jannewaren/jekyll-webawesome).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/jekyll-webawesome.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'lib/jekyll/webawesome/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'jekyll-webawesome'
+  spec.version       = Jekyll::WebAwesome::VERSION
+  spec.authors       = ['Janne Waren']
+  spec.email         = ['janne.waren@iki.fi']
+
+  spec.summary       = 'Jekyll plugin for Web Awesome components'
+  spec.description   = 'A Jekyll plugin that transforms custom Markdown syntax into Web Awesome components.'
+  spec.homepage      = 'https://github.com/jannewaren/jekyll-webawesome'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.2'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = "#{spec.homepage}/tree/main"
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    Dir.glob('lib/**/*.rb') + %w[
+      README.md
+      CHANGELOG.md
+      LICENSE.txt
+      jekyll-webawesome.gemspec
+    ]
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'jekyll', '>= 3.7', '< 5.0'
+  spec.add_dependency 'kramdown', '~> 2.0'
+
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 1.0'
+end

data/lib/jekyll/webawesome/code_block_transformer.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module WebAwesome
+    # Transforms markdown code blocks to Jekyll highlight syntax
+    module CodeBlockTransformer
+      CODE_BLOCK_PATTERN = /```([a-zA-Z0-9.+#_-]+)?(\n.*?)```/m
+
+      # Class variable to store protected blocks across hook calls
+      @@protected_blocks = {}
+
+      class << self
+        def clear_protected_blocks
+          @@protected_blocks.clear
+        end
+
+        # Check if a code block contains WebAwesome syntax that should be preserved
+        def contains_webawesome_syntax?(content)
+          # Check for WebAwesome patterns
+          callout_pattern = /^:::(info|success|neutral|warning|danger)/m
+          details_pattern = /^\^\^\^/m
+          tabs_pattern = /^\+{6}/m
+
+          content.match?(callout_pattern) || content.match?(details_pattern) || content.match?(tabs_pattern)
+        end
+
+        # Transform code blocks from markdown syntax to Jekyll highlight tags
+        def transform_code_blocks(content)
+          counter = @@protected_blocks.size
+
+          # First pass: protect markdown code blocks that contain WebAwesome syntax
+          content = content.gsub(CODE_BLOCK_PATTERN) do |match|
+            language = Regexp.last_match(1)
+            code_content = Regexp.last_match(2).strip
+
+            # If this is a markdown code block containing WebAwesome syntax, protect it
+            if language && language.downcase == 'markdown' && contains_webawesome_syntax?(code_content)
+              placeholder = "<!--PROTECTED_WEBAWESOME_EXAMPLE_#{counter}-->"
+              @@protected_blocks[placeholder] = match
+              counter += 1
+              placeholder
+            else
+              match # Leave other code blocks for normal processing
+            end
+          end
+
+          # Second pass: transform remaining code blocks normally
+          content.gsub(CODE_BLOCK_PATTERN) do |match|
+            language = Regexp.last_match(1)
+            code_content = Regexp.last_match(2).strip
+
+            if language && language.downcase != 'plain'
+              transformed = "{% highlight #{language} %}\n#{code_content}\n{% endhighlight %}"
+              transformed
+            else
+              match # Return original block if no language or 'plain'
+            end
+          end
+        end
+
+        # Restore protected WebAwesome example blocks after WaElementTransformer processing
+        def restore_protected_blocks(content)
+          @@protected_blocks.each do |placeholder, original_block|
+            content = content.gsub(placeholder, original_block)
+          end
+          content
+        end
+
+        def process(content)
+          transform_code_blocks(content)
+        end
+      end
+
+      # Register hooks directly in the transformer module
+      # Clear protected blocks at start of build
+      Jekyll::Hooks.register :site, :pre_render do |_site|
+        CodeBlockTransformer.clear_protected_blocks
+      end
+
+      Jekyll::Hooks.register :documents, :pre_render, priority: 30 do |document|
+        next unless document.relative_path =~ /.*\.md$/i
+
+        puts "Jekyll::WebAwesome::CodeBlockTransformer processing document: #{document.relative_path}\n"
+        document.content = CodeBlockTransformer.transform_code_blocks(document.content)
+      end
+
+      Jekyll::Hooks.register :pages, :pre_render, priority: 30 do |page|
+        next unless page.relative_path =~ /.*\.md$/i
+
+        puts "Jekyll::WebAwesome::CodeBlockTransformer processing page: #{page.relative_path}\n"
+        page.content = CodeBlockTransformer.transform_code_blocks(page.content)
+      end
+
+      # Register hooks to restore protected blocks after WaElementTransformer
+      Jekyll::Hooks.register :documents, :pre_render, priority: 10 do |document|
+        next unless document.relative_path =~ /.*\.md$/i
+
+        puts "Jekyll::WebAwesome::CodeBlockTransformer restoring code blocks in document: #{document.relative_path}\n"
+        document.content = CodeBlockTransformer.restore_protected_blocks(document.content)
+      end
+
+      Jekyll::Hooks.register :pages, :pre_render, priority: 10 do |page|
+        next unless page.relative_path =~ /.*\.md$/i
+
+        puts "Jekyll::WebAwesome::CodeBlockTransformer restoring code blocks in page: #{page.relative_path}\n"
+        page.content = CodeBlockTransformer.restore_protected_blocks(page.content)
+      end
+    end
+  end
+end

data/lib/jekyll/webawesome/plugin.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'transformer'
+require_relative 'code_block_transformer'
+
+module Jekyll
+  module WebAwesome
+    # Plugin class that registers hooks for pre-render processing
+    class Plugin
+      # Check if debug mode is enabled from various configuration sources
+      def self.debug_enabled?(site)
+        return true if Jekyll::WebAwesome.configuration&.debug_mode
+        return true if site.config.dig('webawesome', 'debug')
+        return true if site.config['webawesome_debug']
+
+        false
+      end
+
+      # Check if a file is a markdown file
+      def self.markdown_file?(filepath)
+        filepath.to_s.match?(/\.md$/i)
+      end
+
+      # Register hooks for pre-render processing (before markdown conversion)
+      Jekyll::Hooks.register :documents, :pre_render do |document|
+        next unless markdown_file?(document.relative_path)
+
+        puts "Jekyll::WebAwesome Processing document (pre-render): #{document.relative_path}\n" if debug_enabled?(document.site)
+        document.content = Transformer.process(document.content)
+      end
+
+      Jekyll::Hooks.register :pages, :pre_render do |page|
+        next unless markdown_file?(page.relative_path)
+
+        puts "Jekyll::WebAwesome Processing page (pre-render): #{page.relative_path}\n" if debug_enabled?(page.site)
+        page.content = Transformer.process(page.content)
+      end
+    end
+  end
+end

data/lib/jekyll/webawesome/transformer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'jekyll'
+require 'kramdown'
+require_relative 'transformers'
+
+module Jekyll
+  module WebAwesome
+    # Main transformer that orchestrates all component transformers
+    class Transformer
+      def self.process(content)
+        content = BadgeTransformer.transform(content)
+        content = ButtonTransformer.transform(content)
+        content = CalloutTransformer.transform(content)
+        content = CardTransformer.transform(content)
+        content = DetailsTransformer.transform(content)
+        content = IconTransformer.transform(content)
+        content = TagTransformer.transform(content)
+        TabsTransformer.transform(content)
+      end
+    end
+  end
+end

data/lib/jekyll/webawesome/transformers/badge_transformer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'base_transformer'
+
+module Jekyll
+  module WebAwesome
+    # Transforms badge syntax into wa-badge elements
+    # Primary syntax: !!!variant?\ncontent\n!!!
+    # Alternative syntax: :::wa-badge variant?\ncontent\n:::
+    # Variants: brand, success, neutral, warning, danger
+    class BadgeTransformer < BaseTransformer
+      def self.transform(content)
+        # Define both regex patterns
+        primary_regex = /^!!!(brand|success|neutral|warning|danger)?\n(.*?)\n!!!/m
+        alternative_regex = /^:::wa-badge\s*(brand|success|neutral|warning|danger)?\n(.*?)\n:::/m
+
+        # Define shared transformation logic
+        transform_proc = proc do |variant, badge_content|
+          badge_content = badge_content.strip
+
+          build_badge_html(badge_content, variant)
+        end
+
+        # Apply both patterns
+        patterns = dual_syntax_patterns(primary_regex, alternative_regex, transform_proc)
+        apply_multiple_patterns(content, patterns)
+      end
+
+      class << self
+        private
+
+        def build_badge_html(content, variant)
+          variant_attr = variant ? " variant=\"#{variant}\"" : ''
+          badge_html = markdown_to_html(content).strip
+
+          # Remove paragraph tags if the content is just text
+          badge_html = badge_html.gsub(%r{^<p>(.*)</p>$}m, '\1')
+
+          # Fix whitespace issues in Web Awesome badges by ensuring proper spacing
+          # Replace spaces after closing tags with non-breaking spaces to prevent CSS collapse
+          badge_html = badge_html.gsub(%r{(</\w+>)\s+}, '\1&nbsp;')
+
+          "<wa-badge#{variant_attr}>#{badge_html}</wa-badge>"
+        end
+      end
+    end
+  end
+end